التحكم في كيفية تنفيذ الوكيل مع التدفقات

أنت تعرض مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. info

يتضمن أي نموذج لبرمجة التطبيقات طريقة للتحكم في تدفق المعالجة. في خادم وكيل واجهة برمجة التطبيقات، يتم ذلك من خلال عمليات التدفق. يمكنك إضافة منطق وبيانات شرطية ومعالجة الأخطاء وغيرها إلى مسارات الإحالات الناجحة. ويمكنك استخدام مسارات الإحالات الناجحة للتحكّم في ما يحدث والوقت الذي يحدث فيه ذلك.

التدفقات هي مراحل متسلسلة على طول مسار معالجة طلبات واجهة برمجة التطبيقات. عند إضافة منطق الخادم الوكيل، مثل التحقّق من مفتاح واجهة برمجة التطبيقات، يمكنك إضافة المنطق كخطوة في التسلسل المحدّد من خلال التدفق. عند تحديد شرط لتحديد ما إذا كان سيتم تنفيذ المنطق ومتى، تتم إضافة الشرط إلى مسار.

يحدد مثال ضبط التدفق التالي التدفق الذي يتم فيه تنفيذ سياسة VerifyAPIKey إذا كان مسار الطلب الوارد ينتهي بـ / وكان فعل HTTP للطلب هو GET.

<Flow name="Get Food Carts">
    <Description>Get Food Carts</Description>
    <Request>
        <Step>
            <Name>Verify-API-Key</Name>
        </Step>
    </Request>
    <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

تهدف قيمة Verify-API-Key في العنصر <Name> في المسار إلى تضمين سياسة تم ضبطها في مكان آخر في الخادم الوكيل باستخدام XML، مثل ما يلي:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
    <DisplayName>Verify API Key</DisplayName>
    <Properties/>
    <APIKey ref="request.header.x-api-key"/>
</VerifyAPIKey>

تصميم تسلسل تنفيذ الخطوات

يمكنك تنظيم التدفقات بحيث يمكن تنفيذ العمليات المنطقية بالتسلسل الصحيح على طول مسار المعالجة.

عند تحديد مكان إضافة المنطق، عليك أولاً اختيار ما إذا كنت تريد إضافته إلى نقطة نهاية وكيل أو نقطة نهاية مستهدَفة. يقسّم الوكيل لواجهة برمجة التطبيقات رمزه بين الرمز الذي يتفاعل مع العميل للوكيل (نقطة نهاية الوكيل) والرمز الاختياري الذي يتفاعل مع الهدف الخلفي للوكيل، إن توفّر (نقطة نهاية الهدف).

تحتوي كلتا النقطتَين النهائيتَين على عمليات تدفق، كما هو موضّح هنا:

نوع نقطة النهاية	الوصف	المسارات المتاحة
ProxyEndpoint	يحتوي على مسارات وكيل واجهة برمجة التطبيقات الأقرب إلى العميل. يوفر أماكن منطقية لاتخاذ إجراء أولاً بشأن الطلب الوارد من العميل، ثم في النهاية في الرد الذي يلقاه العميل.	PreFlow و"تدفقات شرطية" وPostFlow وPostClientFlow
TargetEndpoint	يحتوي على عمليات تدفق الوكيل لواجهة برمجة التطبيقات الأقرب إلى مورد الخلفية. يوفر أماكن للمنطق لإعداد طلب، ثم التعامل مع الاستجابة من مورد الخلفية.	PreFlow و"تدفقات شرطية" وPostFlow

يمكنك تهيئة التدفق باستخدام XML الذي يحدد ما يجب أن يحدث وبأي ترتيب. توضِّح الصورة التوضيحية التالية كيفية ترتيب التدفقات بشكل تسلسلي ضمن نقطة نهاية الخادم الوكيل ونقطة نهاية العميل:

تحتوي كلّ من نقطة نهاية الخادم الوكيل ونقطة النهاية المستهدَفة على عمليات تدفق يمكنك ترتيبها في التسلسل التالي:

الموضع	نوع التدفق	الوصف
1	PreFlow	يكون هذا الخيار مفيدًا عندما تحتاج إلى التأكد من تنفيذ رموز برمجية معيّنة قبل حدوث أي شيء آخر. إذا كان المسار التمهيدي في نقطة نهاية مستهدفة، يتم تنفيذه بعد المسار التالي لنقطة نهاية الخادم الوكيل.
2	المسار الشرطي	مكان المنطق الشرطي. يتم تنفيذه بعد PreFlow وقبل PostFlow. يتم تنفيذ مسار واحد فقط للمسار الشرطي لكل شريحة، وهو المسار الأول الذي يتم تقييم شرطه على أنّه صحيح. وهذا يعني أنّه يمكنك تنفيذ مسار شرطي واحد كجزء من كلّ من: مسار طلب ProxyEndpoint مسار طلب TargetEndpoint مسار استجابة ProxyEndpoint مسار استجابة TargetEndpoint
3	PostFlow	مكان مناسب لتسجيل البيانات وإرسال إشعار بحدوث خطأ أثناء معالجة الطلب وما إلى ذلك. يتم التنفيذ بعد التدفقات الشرطية وPreFlow. إذا كانت PostFlow نقطة نهاية خادم وكيل، وكانت هناك نقطة نهاية هدف، يتم تنفيذ نقطة نهاية الخادم الوكيل PostFlow قبل نقطة النهاية المستهدفة PreFlow.
4	PostClientFlow (تدفق الخادم الوكيل فقط)	مسار لتسجيل الرسائل بعد إرجاع ردّ إلى العميل

تنفيذ الرمز البرمجي أولاً باستخدام عملية PreFlow

يكون المسار التمهيدي مفيدًا عندما تحتاج إلى التأكّد من تنفيذ رمز معيّن قبل حدوث أي إجراء آخر.

في نقطة نهاية الخادم الوكيل، يُعدّ PreFlow مكانًا رائعًا للرمز الذي يُعتمِد العميل ويحدد عدد الزيارات الواردة من العملاء. في نقطة نهاية مستهدفة، حيث يبدأ التحضير لإرسال طلب إلى هدف في الخلفية، يكون المسار التمهيدي مناسبًا للخطوات الأولى في التحضير لإرسال الطلب.

على سبيل المثال، لا تريد عادةً تقديم خدمة لعميل تجاوز حصته. لدعم هذه المتطلبات، يمكنك وضع سياسات الأمان والحصص في قسم "المسار التمهيدي". بهذه الطريقة، لا داعي للقلق بشأن تعذُّر تقييم الشرط في تدفق شرطي لاحق. وسيتم دائمًا تنفيذ السياسات في هذه العملية قبل إجراء أي معالجة أخرى.

في المثال التالي، يتم تنفيذ سياستَي SpikeArrest وQuota قبل أن يتم نقل عمليات المعالجة إلى مسارات المعالجة الشَرطية.

<PreFlow name="MyPreFlow">
    <Request>
        <Step>
            <Name>Spike-Arrest</Name>
        </Step>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
</PreFlow>

تنفيذ الرمز البرمجي بشكل مشروط من خلال تدفق مشروط

بين PreFlow وPostFlow، يمكنك اختيار تدفقات يتم تنفيذها بشكل مشروط. يمنحك ذلك فرصة لضبط تسلسلات منطقية متعددة، ولكن يتم تنفيذ تسلسل واحد فقط استنادًا إلى حالة الخادم الوكيل. يكون التدفق المشروط اختياريًا إذا كان بإمكانك تنفيذ كل المنطق في PreFlow أو PostFlow ولم تكن هناك أي شروط مطلوبة (بمعنى آخر، لا يتوفّر سوى مسار واحد فقط من خلال نقطة النهاية).

يحدد كل مسار شرطًا يتم اختباره لقيم الحالة المختلفة. ويؤدي ذلك إلى تفرع التنفيذ بشكل فعّال استنادًا إلى الشروط. على سبيل المثال، قد تحتاج إلى تحويل ملف XML إلى ملف JSON فقط عندما يكون التطبيق الذي يطلب البيانات قيد التشغيل على جهاز جوّال.

في هذه الحالة، لا يتم فرض قيود الحصة إلا إذا كان الطلب هو طلب GET يتضمّن /issue/** نمط معرّف الموارد المنتظم (/issue/ مع أي محتوى في معرّف الموارد المنتظم بعد العلامة الحادة الأخيرة).

<Flow name="MyFlow">
    <Description/>
    <Request>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/issue/**") and (request.verb = "GET")</Condition>
</Flow>

يمكنك استخدام متغيّرات المسار لتحديد الشروط. لمزيد من المعلومات عن استخدام المتغيّرات في الشروط، راجِع الشروط التي تتضمّن متغيّرات التدفق.

للحصول على أمثلة على استخدام مطابقة الأنماط في الشروط، راجِع مطابقة الأنماط.

تنفيذ الرمز بعد المنطق الأساسي باستخدام PostFlow

إنّ PostFlow هو مكان رائع لتنفيذ الإجراءات بعد المنطق الأساسي لنقطة النهاية وقبل اكتمال معالجة نقطة النهاية. يتم تنفيذ PostFlow بعد التدفقات الشرطية وPreFlow.

يُعد PostFlow مكانًا جيدًا لتسجيل بعض البيانات، وإرسال إشعار بحدوث خطأ، وتحويل تنسيق رسالة الرد، وما إلى ذلك.

في المثال التالي، تضبط سياسة AssignMessage التي تُسمى SetResponseHeaders عناوين رسالة الاستجابة قبل أن ترسل Apigee Edge الرد إلى العميل.

<PostFlow>
    <Response>
        <Step>
            <Name>SetResponseHeaders</Name>
        </Step>
    </Response>
 </PostFlow>

تنفيذ التعليمات البرمجية بعد تلقي العميل رد الخادم الوكيل باستخدام PostClientFlow

يمكن أن يتضمّن PostClientFlow السياسات التالية:

• سياسة ExtensionCallout
• سياسة Floodlight^*
• سياسة تسجيل الرسائل النصية
• سياسة ServiceCallout

^* يمكن لسياسة FlowCallout فقط استدعاء المسارات المشتركة التي تستوفي في حد ذاتها معايير وجودها في PostClientFlow (أي أنها تحتوي على سياسات متوافقة فقط).

في حال تضمين سلسلة إجراءات، سيكون PostClientFlow آخر مسار يتم تنفيذه، ويتم تنفيذه بعد إرسال ردّ إلى العميل.

يعتبر PostClientFlow جيدًا للتسجيل النهائي. يمكنك أيضًا تسجيل الطوابع الزمنية لوقت بدء رسالة الردّ وانتهائها.

في ما يلي مثال على PostClientFlow مع إرفاق سياسة MessageLogging.

    ...
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <PostClientFlow>
        <Request/>
        <Response>
            <Step>
                <Name>Message-Logging-1</Name>
            </Step>
        </Response>
    </PostClientFlow>
    ...

يمكنك الاطّلاع على ما يلي للحصول على مزيد من المعلومات:

• مرجع إعدادات الوكيل لواجهة برمجة التطبيقات
• البرنامج التعليمي : Apigee Edge - Post Client Flow

إضافة منطق إلى مسارات الإحالات الناجحة

عند إضافة منطق إلى الخادم الوكيل، يمكنك إجراء ذلك من خلال إضافة سياسات إلى عمليات الخادم الوكيل. تمامًا كما يتم تنفيذ مسارات الإحالة الناجحة بالتسلسل (مسار ما قبل الإحالة الناجحة ثم مسار الإحالة الناجحة ثم مسار ما بعد الإحالة الناجحة، كما هو موضّح في هذا الموضوع)، يتم تنفيذ محتوى مسار الإحالة الناجحة بالتسلسل.

يشير مثال إعداد العملية التالي إلى ثلاث سياسات (تم ضبطها في مكان آخر في ملفات XML الخاصة بها). يتم تنفيذ السياسة المُشار إليها في Verify-API-Key قبل سياسة المُشار إليها في Remove-API-Key، ويليها كلتا السياستَين المُمثّلتين في Quota.

<Flow name="Get Food Cart Menus">
    <Description>Get Food Cart Menus</Description>
    <Request>
        <Step>
            <Name>Verify-API-Key</Name>
        </Step>
        <Step>
            <Name>Remove-API-Key</Name>
        </Step>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

تقدّم وحدة تحكّم Apigee Edge هذا التسلسل من السياسات كصف من الرموز حيث يمثّل كل رمز السياسة.

مسارات تصحيح الأخطاء

توفّر أداة Apigee Edge Trace طريقة رسومية لمعرفة طريقة تنفيذ المنطق في الخادم الوكيل لواجهة برمجة التطبيقات بعد تنفيذ الطلب. توضّح الأداة المعالجة بين الطلب والاستجابة. وهو لا يوضّح على وجه التحديد الفصل بين PreFlow والتدفقات الشرطية وPostFlow.

لمزيد من المعلومات عن الخوادم الوكيلة للتتبُّع، اطّلِع على استخدام أداة التتبُّع.

معالجة الأخطاء في مسارات الإحالات الناجحة

يمكنك رفع الأعطال من أماكن مختلفة في وكيل واجهة برمجة التطبيقات، بما في ذلك من عمليات التدفق.

في ما يلي مثال على الاستجابة من PreFlow في نقطة نهاية مستهدفة، أي الرمز الذي يتم تنفيذه مباشرةً عند تلقّي استجابة من واجهة خلفية مستهدفة. في المثال، يظهر خطأ إذا لم تكن الاستجابة من الهدف 200 (نجاح).

<PreFlow name="PreFlow">
    <Response>
        <Step>
            <Name>RaiseFault</Name>
            <Condition>(response.status.code GreaterThan "200")</Condition>
        </Step>
    </Response>
</PreFlow>

لمزيد من المعلومات عن التعامل مع الأخطاء، يمكنك الاطّلاع على معالجة الأخطاء.