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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تنفيذ التعليمات البرمجية أولاً باستخدام 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 من سلسلة "4MV4D" (فيديو مدته 4 دقائق للمطوّرين).

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

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

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

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

معالجة الأخطاء في التدفقات

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

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

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

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