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

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

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

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

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

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

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

الموضع نوع التدفق الوصف
1 PreFlow

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

إذا كان PreFlow في نقطة نهاية هدف، سيتم تنفيذه بعد نقطة نهاية الخادم الوكيل PostFlow:
2 التدفق الشرطي

مكان المنطق الشرطي. يتم تنفيذه بعد تدفق PreFlow وقبل PostFlow:

يتم تنفيذ تدفق شرطي واحد فقط لكل مقطع - التدفق الأول الذي يكون شرطه يتم تقييمه إلى true. هذا يعني أنه يمكنك استخدام تدفق شرطي واحد يتم تنفيذه كجزء من كل مما يلي:
  • مسار طلبات ProxyEndpoint
  • مسار طلب TargetEndpoint
  • مسار استجابة ProxyEndpoint
  • مسار استجابة TargetEndpoint
3 PostFlow

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

إذا كانت PostFlow في نقطة نهاية خادم وكيل، وكانت هناك نقطة نهاية هدف، فإن الخادم الوكيل يتم تنفيذ نقطة النهاية PostFlow قبل نقطة النهاية المستهدفة PreFlow.
4 PostClientFlow (تدفق الخادم الوكيل فقط) مسار لتسجيل الرسائل بعد إرجاع ردّ إلى العميل

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

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

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

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

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

<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 السياسات التالية:

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

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

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

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

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

فيديو: شاهِد هذا الفيديو القصير الذي يوضّح لك كيفية إنشاء PostClientFlow. باستخدام سياسة MessageLogging من سلسلة Four Minute Video For Developers (4MV4D).

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

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

عند إضافة منطق إلى الخادم الوكيل، يمكنك إجراء ذلك من خلال إضافة سياسات إلى مسارات الخادم الوكيل. تمامًا عمليات التدفق بالتسلسل (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 هذا التسلسل من السياسات كصف من الرموز حيث يمثّل كل رمز السياسة. تشمل الرموز التي تظهر في مسار الطلب ما يلي: &quot;التحقّق من مفتاح واجهة برمجة التطبيقات&quot; و&quot;إزالة مفتاح واجهة برمجة التطبيقات&quot; و&quot;الحصة&quot;.

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

توفّر أداة 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>

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