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

أنت الآن بصدد الاطّلاع على مستندات 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>

تصميم تسلسل تنفيذ سير العمل

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

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

تحتوي كلتا نقطتَي النهاية على مسارات، كما هو موضّح هنا:

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

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

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

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

في نقطة نهاية وكيل، يكون PreFlow مكانًا رائعًا للرمز الذي يصادق على العميل ويحدّ من عدد الزيارات من العملاء. في نقطة نهاية مستهدَفة، حيث تبدأ عملية إعداد طلب لإرساله إلى نقطة نهاية مستهدَفة في الخلفية، يكون 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 بنمط URI يبلغ /issue/** (/issue/ مع أي شيء في URI بعد الشرطة المائلة الأخيرة).

<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
• سياسة FlowCallout^*
• سياسة MessageLogging
• سياسة 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

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

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

يشير مثال إعدادات سير العمل التالي إلى ثلاث سياسات (تم إعدادها في مكان آخر في ملفات 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 طريقة بيانية لمعرفة كيفية تنفيذ منطق خادم وكيل واجهة برمجة التطبيقات بعد تلقّي طلب. توضّح الأداة عملية المعالجة بين الطلب والاستجابة. ولا يوضّح هذا المخطط بشكل خاص الفصل بين PreFlow والتدفقات الشرطية وPostFlow.

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

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

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

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

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

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