الشروط بمتغيّرات تدفق

أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. info

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

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

ضبط العبارات الشرطية

يتم تنفيذ السلوك الشرطي في خوادم وكيل واجهة برمجة التطبيقات باستخدام مجموعة من الشروط والمتغيرات. يتم إنشاء عبارة شرطية باستخدام عنصر Condition. في ما يلي مثال على شرط فارغ:

<Condition></Condition>

لإنشاء عبارة شرطية، عليك إضافة عامل تشغيل شرطي ومتغيّر لإنشاء البنية التالية:

<Condition>{variable.name}{operator}{"value"}</Condition>

تشمل عوامل التشغيل الشرطية المتوافقة = (يساوي) و!= (لا يساوي) و> (أكبر من). لتسهيل القراءة، يمكنك أيضًا كتابة الشروط على النحو التالي: النص: equals، notequals، greaterthan.

عند العمل مع مسارات URI، يمكنك استخدام ~/ أو MatchesPath. يمكنك أيضًا مطابقة التعابير العادية JavaRegex باستخدام عامل التشغيل ~~.

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

المتغيّرات

تؤدي الشروط عملها من خلال تقييم قيم المتغيرات. المتغيّر هو خاصية لمعاملة HTTP يتم تنفيذها بواسطة خادم وكيل لواجهة برمجة التطبيقات، أو خاصية لإعدادات خادم وكيل لواجهة برمجة التطبيقات نفسها. عندما يتلقّى خادم وكيل لواجهة برمجة التطبيقات طلبًا من تطبيق، تملأ منصة Apigee Edge قائمة طويلة من المتغيرات المرتبطة بأشياء مثل وقت النظام ومعلومات شبكة التطبيق وعناوين HTTP في الرسائل وإعدادات خادم وكيل لواجهة برمجة التطبيقات وعمليات تنفيذ السياسات وما إلى ذلك. يؤدي ذلك إلى إنشاء سياق غني يمكنك استخدامه لإعداد عبارات شرطية.

تستخدم المتغيّرات دائمًا صيغة منقّطة. على سبيل المثال، تتوفّر عناوين HTTP في رسالة الطلب كمتغيّرات تُسمّى request.header.{header_name}. لذا، لتقييم عنوان Content-type، يمكنك استخدام المتغيّر request.header.Content-type. على سبيل المثال، يشير request.header.Content-type = "application/json" إلى أنّ نوع محتوى الطلب يجب أن يكون JSON.

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

<Condition>request.verb = "GET"</Condition>

<Condition>request.verb equals "GET"</Condition>

يستخدم Edge عبارة من هذا النوع لتقييم الشروط. يتم تقييم المثال أعلاه على أنّه صحيح إذا كان فعل HTTP المرتبط بالطلب هو GET. إذا كان فعل HTTP المرتبط بالطلب هو POST، سيتم تقييم العبارة إلى false.

لتفعيل السلوك الديناميكي، يمكنك ربط "الشروط" بـ "عمليات التنفيذ" و"الخطوات" و"قواعد التوجيه".

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

على سبيل المثال، لإنشاء Flow لا يتم تنفيذه إلا عندما يكون فعل الطلب هو GET:

<Flows>
  <Flow name="ExecuteForGETs">
  <Condition>request.verb="GET"</Condition>
  </Flow>
</Flows>

لإنشاء عملية GET واحدة وعملية POST أخرى:

<Flows>
  <Flow name="ExecuteForGETs">
  <Condition>request.verb="GET"</Condition>
  </Flow>
  <Flow name="ExecuteForPOSTs">
  <Condition>request.verb="POST"</Condition>
  </Flow>
</Flows>

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

<PreFlow name="PreFlow">
    <Request>
        <Step>
            <Condition>request.verb equals "POST"</Condition>
            <Name>VerifyApiKey</Name>
        </Step>
    </Request>
</PreFlow>

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

للحصول على معلومات مرجعية شاملة، يُرجى الاطّلاع على المراجع التالية:

• مرجع متغيّرات التدفق
• مرجع الشروط

مثال 1

يعرض المثال التالي مسارًا شرطيًا واحدًا باسم Convert-for-devices، تم إعداده في مسار الردّ ProxyEndpoint. أضِف الشرط كعنصر إلى الكيان الذي ينطبق عليه الشرط. في هذا المثال، الشرط هو أحد مكونات مسار العمل. لذلك، سيتم تنفيذ التدفق كلما تم تقييم العبارة إلى "صحيح".

<Flows>
  <Flow name="Convert-for-devices">
  <Condition>(request.header.User-Agent = "Mozilla")</Condition>
    <Response>
      <Step><Name>ConvertToJSON</Name></Step>
    </Response>
  </Flow>
</Flows>

بالنسبة إلى كل طلب يتم تلقّيه من تطبيق، يخزّن Edge قيم جميع عناوين HTTP المتوفّرة كمتغيّرات. إذا كان الطلب يتضمّن عنوان HTTP باسم User-Agent، يتم تخزين هذا العنوان وقيمته كمتغيّر باسم request.header.User-Agent.

بالنظر إلى إعداد ProxyEndpoint أعلاه، يتحقّق Edge من قيمة المتغيّر request.header.User-Agent لمعرفة ما إذا كان الشرط صحيحًا.

إذا تم تقييم الشرط على أنّه صحيح، أي أنّ قيمة المتغيّر request.header.User-Agent تساوي Mozilla، يتم تنفيذ Flow الشرطي ويتم فرض سياسة XMLtoJSON المسماة ConvertToJSON. وفي حال عدم توفّرها، لن يتم تنفيذ Flow، وسيتم عرض استجابة XML بدون تعديل (بتنسيق XML) للتطبيق الذي أرسل الطلب.

مثال 2

لنستخدِم مثالاً محدّدًا تحتاج فيه إلى تحويل رسالة الرد من XML إلى JSON، ولكن فقط للأجهزة الجوّالة. أولاً، أنشئ السياسة التي ستحوّل الاستجابة المنسَّقة بتنسيق XML من Weather API إلى JSON:

<XMLToJSON name="ConvertToJSON">
  <Options>
  </Options>
  <OutputVariable>response</OutputVariable>
  <Source>response</Source>
</XMLToJSON>

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

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

<Flows>
  <Flow name="Convert-for-devices">
    <Response>
      <Step><Name>ConvertToJSON</Name></Step>
    </Response>
  </Flow>
</Flows>

عند استدعاء واجهة برمجة التطبيقات باستخدام الطلب العادي، يتم تنسيق الاستجابة بتنسيق JSON.

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

اختبار سير العمل المشروط

في نموذج الطلب هذا، تم ضبط عنوان HTTP User-Agent على Mozilla، ما يؤدي إلى تقييم العبارة الشرطية على أنّها صحيحة وتنفيذ التدفق الشرطي Convert-for-devices.

$ curl -H "User-Agent:Mozilla" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

أو، لطباعة المحتوى بتنسيق جميل حيثما تتوفّر لغة Python:

$ curl -H "User-Agent:Mozilla" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282 | python -mjson.tool

نموذج الرد:

. . .

"yweather_forecast": [
         {
              "code": "11",
              "date": "12 Dec 2012",
              "day": "Wed",
              "high": "55",
              "low": "36",
              "text": "Showers"
          },
          {
              "code": "32",
              "date": "13 Dec 2012",
              "day": "Thu",
              "high": "56",
              "low": "38",
              "text": "Sunny"
          }
      ]
  }

. . .

سيؤدي إرسال طلب بدون العنوان User-Agent أو بقيمة مختلفة عن Mozilla إلى تلقّي استجابة بتنسيق XML.

$ curl http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

يتم عرض استجابة XML غير معدَّلة.

نموذج الرد:

<yweather:forecast day="Wed" date="12 Dec 2012" low="36" high="55" text="Showers" code="11" /> <yweather:forecast day="Thu" date="13 Dec 2012" low="38" high="56" text="Sunny" code="32" />

تطابق النمط

يوضّح هذا القسم كيفية استخدام مطابقة الأنماط مع الشروط في أحد مسارات Apigee.

المشغِّلون

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

• عامل التشغيل "مطابقات": مطابقة الأنماط البسيطة
• عامل JavaRegex: تحكّم أدق في المطابقة
• عامل التشغيل MatchesPath: مطابقة جزء من المسار

أعواد ثقاب

لنلقِ نظرة أولاً على عامل التشغيل الشرطي "مطابقات" أو "~". عامل التشغيل هذا هو نفسه عامل التشغيل "مطابقة"، ولكن يُعدّ الخيار الأخير أكثر قابلية للقراءة.

الملخّص: يمنحك عامل التشغيل "المطابقات" احتمالَين. إما أن تطابق السلسلة حرفيًا، أو أن تطابقها باستخدام حرف بدل "*". وكما هو متوقع، يتطابق حرف البدل مع صفر أو أكثر من الأحرف. لنرى كيف يعمل ذلك.

يوضّح ملف XML التالي شرط الخطوة. يتم تنفيذ السياسة SomePolicy عندما يكون تقييم الشرط صحيحًا. في هذا المثال، نختبر المتغيّر proxy.pathsuffix، وهو متغيّر مضمّن في Edge يخزّن لاحقة مسار الطلب. ومع ذلك، يمكنك اختبار قيمة أي متغيّر في التدفق يحتوي على سلسلة. لذا، في هذه الحالة، إذا كان المسار الأساسي للطلب الوارد هو /animals، وكان الطلب هو /animals/cat، يكون لاحقة المسار هي السلسلة الحرفية "/cat".

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix Matches "/cat")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

السؤال: ما هو لاحقة مسار الخادم الوكيل التي ستؤدي إلى تنفيذ SomePolicy؟ لا يوجد سوى احتمال واحد.

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/cat

هل يتم تنفيذ السياسة؟ نعم، لأنّ لاحقة مسار الخادم الوكيل تتطابق تمامًا مع "/cat". لن يتم تنفيذها إذا كان اللاحقة /bat أو /dog أو "/" أو أي شيء آخر.

الآن، لنلقِ نظرة على هذه العبارة الشرطية التي نستخدم فيها حرف البدل "*":

<Condition>(proxy.pathsuffix Matches "/*at")</Condition>

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/cat

هل يتم تنفيذ السياسة؟ نعم، لأنّ حرف البدل يتطابق مع أي حرف، و"/cat" هو تطابق.

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/bat

هل يتم تنفيذ السياسة؟ نعم، لأنّ حرف البدل يتطابق مع أي حرف، وبالتالي فإنّ "/bat" يمثّل تطابقًا.

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/owl

هل يتم تنفيذ السياسة؟ بالطبع لا، فمع أنّ حرف البدل يتطابق مع "o"، إلا أنّه لا يتطابق مع الحرفين "wl".

لننقل الآن حرف البدل إلى نهاية اللاحقة:

<Condition>(proxy.pathsuffix Matches "/cat*")</Condition>

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/cat

هل يتم تنفيذ السياسة؟ نعم، لأنّ حرف البدل يتطابق مع صفر أو أكثر من أي أحرف.

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/bat

هل يتم تنفيذ السياسة؟ لا، "/bat" ليس تطابقًا.

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/cat123

هل يتم تنفيذ السياسة؟ نعم، يتطابق حرف البدل مع صفر أو أكثر من أي أحرف، وبالتالي فإن "123" يؤدي إلى تطابق.

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/cat/bird/mouse

هل يتم تنفيذ السياسة؟ نعم، لأنّ حرف البدل يتطابق مع صفر أو أكثر من أي أحرف، وبالتالي فإنّ "/bird/mouse" يؤدي إلى تطابق. لاحظ كيف يمكن أن تتسبّب عبارة مثل هذه في حدوث مشاكل لأنّها تطابق كل ما يلي الأحرف الحرفية.

السؤال: هل عامل التشغيل "مطابقات" حسّاس لحالة الأحرف؟

نعم. لنفترض أنّ لديك شرطًا على النحو التالي:

<Condition>(proxy.pathsuffix Matches "/*At")</Condition>

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/cat

هل يتم تنفيذ السياسة؟ لا، يتطابق حرف البدل مع أي حرف (بغض النظر عن حالة الأحرف)، ولكن الحرف "a" الصغير لا يتطابق مع "A".

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/bAt

هل يتم تنفيذ السياسة؟ نعم، تتطابق حالة الأحرف.

السؤال: كيف يمكنني تجاهل الرموز باستخدام عامل التشغيل "مطابقة"؟

استخدِم الرمز "%" لتجنُّب الأحرف المحجوزة. على سبيل المثال:

<Condition>(proxy.pathsuffix Matches "/c%*at")</Condition>

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/cat

هل يتم تنفيذ السياسة؟ لا، يبحث عامل التشغيل "مطابقة" عن السلسلة الحرفية "c*at".

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/c*at

السؤال:هل يتم تنفيذ السياسة؟

نعم، يتطابق هذا المسار، على الرغم من أنّه غير معتاد.

JavaRegex

كما ترى، فإنّ عامل التشغيل "مطابقات" مناسب للحالات البسيطة. ولكن يمكنك استخدام عامل تشغيل آخر، وهو عامل التشغيل "JavaRegex" أو "~~". هذان العاملان هما نفس العامل، إلا أنّ JavaRegex يُعتبر أكثر قابلية للقراءة. يُطلق عليه اسم JavaRegex لأنّه يتيح مطابقة الأنماط باستخدام التعبيرات العادية، ويتّبع Edge القواعد نفسها المتّبعة في الفئات ضمن حزمة java.util.regex في لغة Java. تختلف طريقة عمل عامل التشغيل JavaRegex عن عامل التشغيل Matches، لذا من المهم عدم الخلط بينهما.

الملخّص: يتيح لك عامل التشغيل "JavaRegex" استخدام بنية التعبير العادي في العبارات الشرطية.

يعرض الرمز التالي شرط الخطوة. يتم تنفيذ السياسة SomePolicy إذا كان تقييم الشرط صحيحًا. في هذا المثال، نختبر المتغيّر proxy.pathsuffix، وهو متغيّر مضمّن في Edge يخزّن لاحقة مسار الطلب. إذا كان المسار الأساسي للطلب الوارد هو /animals، وكان الطلب هو /animals/cat، يكون لاحقة المسار هي السلسلة الحرفية "/cat".

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix JavaRegex "/cat")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

السؤال: ما هو لاحقة مسار الخادم الوكيل التي ستؤدي إلى تنفيذ SomePolicy؟ كما هو الحال مع عامل التشغيل Matches، لا يوجد سوى احتمال واحد في هذه الحالة.

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/cat

هل يتم تنفيذ السياسة؟ نعم، لأنّ لاحقة مسار الخادم الوكيل تتطابق تمامًا مع "/cat". ولن يتم تنفيذه إذا كان اللاحقة /bat أو /dog أو أي شيء آخر.

لننشئ الآن تعبيرًا عاديًا باستخدام أداة التحديد "*". يتطابق هذا الكمّي مع صفر أو أكثر من الحرف السابق.

<Condition>(proxy.pathsuffix JavaRegex "/c*t")</Condition>

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/cat

هل يتم تنفيذ السياسة؟ لا يُطابق المحدد الكمي "*" صفرًا أو أكثر من الحرف السابق، وهو "c".

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/ccccct

هل يتم تنفيذ السياسة؟ نعم، لأنّ حرف البدل يتطابق مع صفر أو أكثر من الحرف السابق.

بعد ذلك، نستخدم محدد الكمية "?" الذي يتطابق مع الحرف السابق مرة واحدة أو لا يتطابق معه على الإطلاق.

<Condition>(proxy.pathsuffix JavaRegex "/ca?t")</Condition>

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/cat

هل يتم تنفيذ السياسة؟ نعم. يطابق محدد الكمية "?" صفرًا أو تكرارًا واحدًا للحرف السابق، وهو "a".

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/ct

هل يتم تنفيذ السياسة؟ نعم. يتطابق المحدد الكمي "?" مع الحرف السابق مرة واحدة أو لا يتطابق معه. في هذه الحالة، لا يوجد الحرف "a"، لذا يكون تقييم الشرط صحيحًا.

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/caat

هل يتم تنفيذ السياسة؟ لا، لأنّ الكمّية المحدّدة "؟" تتطابق مع حرف واحد من الحرف السابق، وهو "a".

بعد ذلك، نستخدم نمط "[abc]" أو "التجميع" للتعبير العادي. تتطابق مع الأحرف "a" أو "b" أو "c".

<Condition>(proxy.pathsuffix JavaRegex "/[cbr]at")</Condition>

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/cat

هل يتم تنفيذ السياسة؟ نعم. نستخدم هنا تعابير عادية، ويتطابق التعبير "[cbr]" مع الحرف "c" أو "b" أو "r". تُعدّ هذه المكالمات أيضًا من المطابقات:

GET http://artomatic-test.apigee.net/matchtest/bat

GET http://artomatic-test.apigee.net/matchtest/rat

ولكن هذا ليس تطابقًا:

GET http://artomatic-test.apigee.net/matchtest/mat

السؤال: هل عامل JavaRegex حساس لحالة الأحرف؟

نعم. لنفترض أنّ لديك شرطًا على النحو التالي:

<Condition>(proxy.pathsuffix JavaRegex "/ca?t")</Condition>

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/cat

هل يتم تنفيذ السياسة؟ نعم، يتطابق التعبير العادي مع الحرف السابق مرة واحدة أو لا يتطابق معه، والحرف السابق هو "a".

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/cAt

السؤال: هل يتم تنفيذ السياسة؟

لا، لأنّ الحرف الكبير "A" لا يتطابق مع الحرف الصغير "a".

MatchesPath

يمكن أيضًا تحديد عامل التشغيل MatchesPath على النحو التالي "~/". ويبدو مشابهًا قليلاً لعاملَي التشغيل Matches (~) وJavaRegex (~~). لكنّ MatchesPath يختلف تمامًا.

تذكَّر فقط أنّ عامل التشغيل هذا ينظر إلى المسار كسلسلة من الأجزاء. لذلك، إذا كان المسار هو /animals/cats/wild، يمكنك اعتبار المسار مؤلفًا من الأجزاء "/animals" و"/cats" و "/wild".

يتيح لك عامل التشغيل MatchesPath استخدام صيغتين لأحرف البدل: علامة نجمة واحدة (*) وعلامتا نجمة مزدوجتان (**). تطابق علامة النجمة الواحدة عنصر مسار واحدًا. تطابق النجمتان المزدوجتان عنصرًا واحدًا أو عدة عناصر من عناصر المسار.

لنلقِ نظرةً على المثال التالي. في هذا المثال، نختبر المتغيّر proxy.pathsuffix، وهو متغيّر مضمّن في Edge يخزّن لاحقة مسار الطلب. ومع ذلك، يمكنك اختبار قيمة أي متغيّر في التدفق يحتوي على سلسلة.

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix MatchesPath "/animals/*")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

السؤال: ما هو لاحقة مسار الخادم الوكيل التي ستؤدي إلى تنفيذ SomePolicy؟

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/animals

السؤال: هل يتم تنفيذ السياسة؟

لا، لأنّ الشرط يتطلّب عنصر مسار آخر بعد "/animals"، كما هو محدّد في "/*".

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/animals/

هل يتم تنفيذ السياسة؟ نعم، يتضمّن المسار عنصر مسار آخر (الجزء الذي يلي "/animals/")، ولكنّه فارغ.

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/animals/cats

هل يتم تنفيذ السياسة؟ نعم، لأنّ المسار يتضمّن بوضوح عنصرًا ("/cats") يأتي بعد "/animals"

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/animals/cats/wild

السؤال: هل يتم تنفيذ السياسة؟

لا، لأنّ علامة النجمة المفردة تتطابق مع عنصر مسار واحد فقط، وتتضمّن واجهة برمجة التطبيقات هذه أكثر من عنصر واحد بعد "/animals".

لنستخدم الآن علامة النجمة المزدوجة:

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix MatchesPath "/animals/**")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

السؤال: ما هو لاحقة مسار الخادم الوكيل التي ستؤدي إلى تنفيذ SomePolicy؟

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/animals

هل يتم تنفيذ السياسة؟ لا، لأنّ الشرط يتطلّب تحديد عنصر مسار واحد على الأقل يتم تحديده بواسطة "/**".

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/animals/

هل يتم تنفيذ السياسة؟

نعم، يتضمّن المسار عنصر مسار آخر (الجزء الذي يلي "/animals/")، ولكنّه فارغ.

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/animals/cats

هل يتم تنفيذ السياسة؟

نعم، لأنّ المسار يتضمّن عنصرًا واحدًا على الأقل يأتي بعد "/animals".

طلب البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/animals/cats/wild

هل يتم تنفيذ السياسة؟

نعم، لأنّ المسار يتضمّن أكثر من عنصر واحد يأتي بعد "/animals"

خلط العلامات النجمية

يمكنك استخدام مجموعات من علامة النجمة المفردة (*) والمزدوجة (**) لتحسين مطابقة المسارات.

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix MatchesPath "/animals/*/wild/**")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

طلب البيانات من واجهة برمجة التطبيقات:

ستؤدي جميع طلبات البيانات من واجهة برمجة التطبيقات هذه إلى ظهور نتيجة مطابقة:

‫GET http://artomatic-test.apigee.net/matchtest/animals/cats/wild/

و

‫GET http://artomatic-test.apigee.net/matchtest/animals/dogs/wild/austrailian

و

GET http://artomatic-test.apigee.net/matchtest/animals/birds/wild/american/finches

مراجع واجهة برمجة التطبيقات

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

• http://mygreatweatherforecast.com/reports
• http://mygreatweatherforecast.com/forecasts

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

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

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

تعرض الصورة التالية الفرق في السلوك بين عنوانَي URL يؤديان في النهاية إلى الوصول إلى الخلفية نفسها. أحدهما هو عنوان URL للمورد غير الوكيل، والآخر هو وكيل Edge API يتضمّن مسارًا شرطيًا إلى مورد الخلفية نفسه. سنشرح التدفقات الشرطية بمزيد من التفصيل أدناه.

كيفية ربط خوادم وكيل API بموارد خلفية معيّنة

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

لنفترض أنّك تريد أن يتخذ Edge "إجراءً" عند تلقّي مكالمات إلى الموارد /reports أو /forecasts. في هذه المرحلة، أنت لا تحدّد لـ Edge ما يجب فعله، بل تحدّد فقط أنّه يجب أن يستمع إلى الطلبات الموجّهة إلى هذه الموارد. يمكنك إجراء ذلك باستخدام الشروط. في خادم وكيل Edge API، يمكنك إنشاء تدفقات شرطية لكل من /reports و/forecasts. لأغراض توضيحية، يعرض ملف XML التالي الخاص بخادم وكيل لواجهة برمجة التطبيقات الشكل المحتمل لهذه الشروط.

<Flows>
    <Flow name="reports">
        <Description/>
        <Request/>
        <Response/>
        <Condition>(proxy.pathsuffix MatchesPath "/reports") and (request.verb = "GET")</Condition>
    </Flow>
    <Flow name="forecasts">
        <Description/>
        <Request/>
        <Response/>
        <Condition>(proxy.pathsuffix MatchesPath "/forecasts") and (request.verb = "GET")</Condition>
    </Flow>
</Flows>

تنصّ هذه الشروط على ما يلي: "عندما يصل طلب GET مع /reports و/forecasts في عنوان URL، سينفّذ Edge أي إجراء تطلبه أنت (مطوّر واجهة برمجة التطبيقات)، وذلك من خلال السياسات التي تربطها بتلك التدفقات.

في ما يلي مثال على إخبار Edge بما يجب فعله عند استيفاء شرط معيّن. في رمز XML التالي لخادم وكيل لواجهة برمجة التطبيقات، عندما يتم إرسال طلب GET إلى https://yourorg-test.apigee.net/mygreatweatherforecast/reports، ينفّذ Edge السياسة "XML-to-JSON-1" في الردّ.

<Flows>
    <Flow name="reports">
        <Description/>
        <Request/>
        <Response>
            <Step>
                <Name>XML-to-JSON-1</Name>
            </Step>
        </Response>
        <Condition>(proxy.pathsuffix MatchesPath "/reports") and (request.verb = "GET")</Condition>
</Flow>

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

إنشاء مسارات شرطية لموارد الخلفية

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

ستتمكّن من إجراء ما يلي:

• تطبيق الإدارة بطريقة تعكس دلالات نموذج واجهة برمجة التطبيقات
• تطبيق السياسات والسلوك المكتوب في البرامج النصية على مسارات الموارد الفردية (معرّفات الموارد الموحّدة)
• جمع مقاييس دقيقة لخدمات "إحصاءات Google"

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

لإجراء ذلك، عليك إضافة مسارَين شرطيَّين في خادم وكيل واجهة برمجة التطبيقات: /developers و/apps.

في "طريقة العرض" Develop (تطوير) في جزء "المستكشف" (Navigator) الخاص بأداة تعديل خادم وكيل لواجهة برمجة التطبيقات، انقر على رمز علامة الجمع (+) بجانب default (الإعداد التلقائي) في Proxy Endpoints (نقاط نهاية الخادم الوكيل).

في نافذة "مسار جديد مشروط"، عليك إدخال إعدادات المفاتيح التالية:

• اسم سير العمل: المطوّرون
• نوع الشرط: المسار
• المسار: /developers

سيتم تفعيل الشرط (وسيتم تنفيذ السياسات) إذا تم إرسال طلب إلى الخادم الوكيل مع /developers في نهاية معرّف الموارد المنتظم (URI).

الآن، أضِف مسارًا شرطيًا إلى /apps، وافترض أنّك تريد تفعيل الشرط على كلّ من معرّف الموارد الموحّد وفعل POST في الطلب. يتضمّن الإعداد ما يلي:

• اسم مسار الإحالة الناجحة: التطبيقات
• نوع الشرط: المسار والفعل
• المسار: /apps
• الفعل: POST

سيتم تفعيل الشرط (وسيتم تنفيذ السياسات) إذا تم إرسال طلب إلى الخادم الوكيل مع /apps في نهاية معرّف الموارد الموحّد وفعل POST.

في لوحة "المستكشف"، ستظهر لك مسارات جديدة للتطبيقات والمطوّرين.

اختَر أحد التدفقات لعرض إعدادات التدفق الشرطي في عرض الرمز البرمجي لمحرّر خادم وكيل واجهة برمجة التطبيقات:

<Flow name="Apps">
    <Description>Developer apps registered in Developer Services</Description>
    <Request/>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/apps") and (request.verb = "POST")</Condition>
</Flow>

كما ترى، فإنّ موارد واجهة برمجة التطبيقات هي ببساطة عبارة عن عمليات سير مشروطة تقيّم مسار عنوان URI للطلب الوارد. (يحدّد المتغيّر proxy.pathsuffix معرّف الموارد المنتظم (URI) للطلب الذي يلي BasePath الذي تم ضبطه في إعدادات ProxyEndpoint).

يتم تنفيذ كل مورد من موارد واجهة برمجة التطبيقات تحدّده من خلال تدفّق شرطي في خادم وكيل لواجهة برمجة التطبيقات. (راجِع ضبط التدفقات.)

بعد نشر خادم وكيل لواجهة برمجة التطبيقات في بيئة الاختبار، سيتم إرسال الطلب التالي:

http://{org_name}-test.apigee.net/{proxy_path}/apps

سيؤدي ذلك إلى تقييم الشرط على أنّه صحيح، وسيتم تنفيذ هذا المسار وأي سياسات مرتبطة به.

يستخدم شرط المثال التالي تعبيرًا عاديًا بلغة Java للتعرّف على الطلبات التي يتم إجراؤها إلى المورد /apps مع أو بدون شَرطة مائلة لاحقة (/apps أو /apps/**):

<Condition>(proxy.pathsuffix JavaRegex "/apps(/?)") and (request.verb = "POST")</Condition>

لمزيد من المعلومات حول هذا النوع من الشروط، راجِع كيفية المطابقة بغض النظر عن ... في منتدى Apigee.

نمذجة معرّفات الموارد المنتظمة (URI) الهرمية

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

/developers/{developer_email}/apps

قد تتوفّر لديك مراجع يتم فيها إنشاء معرّف فريد لكل كيان في مجموعة، ويتم أحيانًا إضافة التعليقات التوضيحية إليها على النحو التالي:

/genus/:id/species

ينطبق هذا المسار بالتساوي على عنوانَي URI التاليَين:

/genus/18904/species
/genus/17908/species

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

/developers/*/apps

/developers/*example.com/apps

/genus/*/species

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

/developers/**

سيؤدي مورد واجهة برمجة التطبيقات إلى حلّ مسارات معرّف الموارد المنتظم (URI) التالية:

/developers/{developer_email}/apps
/developers/{developer_email}/keys
/developers/{developer_email}/apps/{app_id}/keys

في ما يلي الشكل الذي سيبدو عليه شرط التدفق الشرطي في تعريف خادم وكيل لواجهة برمجة التطبيقات:

<Condition>(proxy.pathsuffix MatchesPath "/developers/**") and (request.verb = "POST")</Condition>

مزيد من الأمثلة

الشرط المرتبط بـ RouteRule

<RouteRule name="default">
 <!--this routing executes if the header indicates that this is an XML call. If true, the call is routed to the endpoint XMLTargetEndpoint-->
  <Condition>request.header.content-type = "text/xml"</Condition>
  <TargetEndpoint>XmlTargetEndpoint</TargetEndpoint>
</RouteRule>

شرط مرتبط بسياسة

<Step>
<!--the policy MaintenancePolicy only executes if the response status code is exactly 503-->
  <Condition>response.status.code = 503</Condition>
  <Name>MaintenancePolicy</Name>
</Step>

سير العمل الشرطي

<!-- this entire flow is executed only if the request verb is a GET-->
<Flow name="GetRequests">
  <Condition>request.verb="GET"</Condition>
  <Request>
    <Step>
<!-- this policy only executes if request path includes a term like statues-->
<Condition>request.path ~ "/statuses/**"</Condition>
      <Name>StatusesRequestPolicy</Name>
    </Step>
  </Request>
  <Response>
    <Step>
<!-- this condition has multiple expressions. The policy executes if the response code status is exactly 503 or 400-->
<Condition>(response.status.code = 503) or (response.status.code = 400)</Condition>
      <Name>MaintenancePolicy</Name>
    </Step>
  </Response>
</Flow>

أمثلة على عوامل التشغيل في الشروط

في ما يلي بعض الأمثلة على عوامل التشغيل المستخدَمة لإنشاء الشروط:

• request.header.content-type = "text/xml"
• request.header.content-length < 4096 && request.verb = "PUT"
• response.status.code = 404 || response.status.code = 500
• request.uri MatchesPath "/*/statuses/**"
• request.queryparam.q0 NotEquals 10

مثال عملي: تجاهل "/" في نهاية المسار

يريد مطوّرو Edge عادةً التعامل مع لاحقتَي المسار هاتين: "/cat" و"/cat/". ويرجع ذلك إلى أنّ بعض المستخدمين أو العملاء قد يستدعون واجهة برمجة التطبيقات مع الشرطة المائلة الإضافية في نهاية المسار، وعليك أن تكون قادرًا على التعامل مع ذلك في عباراتك الشرطية. تمت مناقشة حالة الاستخدام المحدّدة هذه في منتدى Apigee.

إذا كنت تفضّل ذلك، يمكنك تحقيق ذلك بدون استخدام التعبير العادي على النحو التالي:

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>((proxy.pathsuffix = "/cat") OR (proxy.pathsuffix = "/cat/")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

هذا خيار جيد. أن يكون النص واضحًا ومقروءًا

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

<Condition>(proxy.pathsuffix JavaRegex "/cat(/?)"</Condition>

طلبات البيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/cat
or
GET http://artomatic-test.apigee.net/matchtest/cat/

هل يتم تنفيذ السياسة؟ نعم. يُرجى العِلم أنّه في التعبير العادي، يعني الحرف "?" ما يلي: لا تطابق الحرف السابق أو تطابقه مرة واحدة. لذلك، يتطابق كل من "/cat" و "/cat/".

طلب بيانات من واجهة برمجة التطبيقات:

GET http://artomatic-test.apigee.net/matchtest/cat/spotted

هل يتم تنفيذ السياسة؟ لا، لأنّ التعبير العادي يطابق صفرًا أو تكرارًا واحدًا فقط للحرف السابق، ولا يُسمح بأي شيء آخر.

مطابقة سلاسل عشوائية باستخدام JavaRegex

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

إذا كان لديك مثلاً شرط يختبر سلسلة عشوائية، ربما سلسلة تم إرجاعها في حمولة خلفية أو سلسلة تم إرجاعها من عملية بحث في خادم مصادقة، يمكنك استخدام عوامل التشغيل المطابقة لاختبارها. في حال استخدام JavaRegex، ستتم مقارنة التعبير العادي بسلسلة الموضوع بأكملها. إذا كان الموضوع هو "abc" والتعبير العادي هو "[a-z]"، لن يتم العثور على تطابق، لأنّ "[a-z]" يتطابق تمامًا مع حرف أبجدي واحد. يعمل التعبير "[a-z]+"، كما يعمل التعبير "[a-z]*" والتعبير "[a-z]{3}.

لنلقِ نظرة على مثال ملموس. لنفترض أنّ خادم المصادقة يعرض قائمة بالأدوار كسلسلة مفصولة بفواصل: "محرّر، مؤلف، ضيف".

لا يمكن استخدام هذه البنية لاختبار وجود دور المحرّر، لأنّ "محرّر" هو جزء فقط من السلسلة الكاملة.

<Condition>returned_roles ~~ "editor"</Condition>

ومع ذلك، ستنجح هذه البنية:

<Condition>returned_roles ~~ ".*\beditor\b.*")</Condition>

يعمل هذا الإجراء لأنّه يأخذ في الاعتبار فواصل الكلمات وأي أجزاء أخرى من السلسلة التي تتضمّن البادئة واللاحقة ‎.*.

في هذا المثال، يمكنك أيضًا اختبار "المحرّر" باستخدام عامل التشغيل "يطابق":

<Condition>returned_roles ~~ "*editor*")</Condition>

ومع ذلك، في الحالات التي تحتاج فيها إلى المزيد من الدقة، يكون JavaRegex غالبًا خيارًا أفضل.

تجنُّب علامات الاقتباس المزدوجة في تعبيرات JavaRegex

 -H 'content-type:multipart/related; type="application/xop+xml"'

request.header.Content-Type ~~ "(multipart\/related)(; *type="application\/xop\+xml\")"

request.header.Content-Type ~~ "(multipart\/related)(; *type=\u0022application\/xop\+xml\u0022)"