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

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

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

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

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

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

<Condition></Condition>

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

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

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

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

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

المتغيّرات

تؤدي الشروط عملها من خلال تقييم قيم المتغيّرات. المتغيّر هو سمة لمعاملة 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، فسيتم تقييم العبارة على أنها خطأ.

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

عند إرفاق شرط بـ Flow، يتم إنشاء "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.

Given the ProxyEndpoint configuration above, Edge checks the value of the request.header.User-Agent variable to see whether the condition evaluates to true.

إذا تم تقييم الشرط على أنّه صحيح، أي أنّ قيمة المتغيّر request.header.User-Agent تساوي Mozilla، يتم تنفيذ التدفق الشرطي ويتم فرض سياسة XMLtoJSON التي تحمل الاسم ConvertToJSON. وإذا لم يكن الأمر كذلك، لن يتم تنفيذ التدفق، وسيتم عرض استجابة 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.

المشغِّلون

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

أعواد ثقاب

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

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

.

يعرض ملف XML التالي شرط Step. وتنفّذ سياسة 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

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

السؤال: كيف يمكنني إلغاء الرموز باستخدام عامل التشغيل "Matches"؟

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

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

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

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

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

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

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

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

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

JavaRegex

كما ترى، فإنّ عامل التشغيل "Matches" (مطابقات) رائع للحالات البسيطة. ولكن يمكنك استخدام عامل تشغيل آخر، وهو عامل التشغيل "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؟ كما هو الحال مع عامل التشغيل "يطابق"، هناك احتمال واحد فقط في هذه الحالة.

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

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 جديد/مكافئ للخادم الوكيل لواجهة برمجة التطبيقات
http://mygreatweatherforecast.com http://{your_org}-{environment}.apigee.net/mygreatweatherforecast

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

بالإضافة إلى إحصاءات واجهة برمجة التطبيقات التي تبدأ Edge في جمعها عند استخدام الخادم الوكيل لواجهة برمجة التطبيقات، تتيح لك الخوادم الوكيلة أيضًا تحديد التدفقات الشرطية التي يتم ربطها بالموارد في الخلفية. In essence, "If a GET call comes in to the /reports resource, Edge should do something."

توضّح الصورة التالية الفرق في السلوك بين عنوانَي URL يصلان في النهاية إلى الخلفية نفسها. أحدهما هو عنوان URL للمورد غير الوكيل، والآخر هو وكيل Edge 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 في الخلفية.

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

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

في نافذة "New Conditional Flow" (تدفق شرطي جديد)، عليك إدخال الإعدادات الرئيسية التالية:

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

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

أضِف الآن مسارًا شرطيًا لـ ‎/apps، وافترض أنّك تريد تفعيل الشرط على كلّ من معرّف الموارد المنتظم (URI) وفعل POST في الطلب. تتضمّن عملية الضبط إعداد ما يلي:

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

سيتم تفعيل الشرط (وسيتم تنفيذ السياسات) إذا تم إرسال طلب إلى الخادم الوكيل باستخدام ‎/apps في نهاية معرّف الموارد المنتظم (URI) وفعل 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) الهرمية

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

/developers/{developer_email}/apps

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

/genus/:id/species

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

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

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

/developers/*/apps
/developers/*example.com/apps
/genus/*/species

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

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

هذا خيار جيد. أن تكون واضحة ومقروءة

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

<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}.

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

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

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

ومع ذلك، ستعمل هذه الصيغة:

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

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

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

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

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

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

تتطلّب بنية الشرط تضمين تعبير JavaRegex بين علامتَي اقتباس مزدوجتَين، لذا إذا كان لديك تعبير نمطي يتضمّن علامتَي اقتباس مزدوجتَين، عليك استخدام طريقة بديلة لمطابقتهما. الإجابة هي Unicode. على سبيل المثال، لنفترض أنّك أدخلت عنوانًا يتضمّن علامات اقتباس مزدوجة، مثل ما يلي:
 -H 'content-type:multipart/related; type="application/xop+xml"'
إذا حاولت مطابقة هذا العنوان في شرط تعبير نمطي، سيظهر لك خطأ "شرط غير صالح" لأنّ التعبير يتضمّن علامات الاقتباس المزدوجة:
request.header.Content-Type ~~ "(multipart\/related)(; *type="application\/xop\+xml\")"
الحل هو استبدال علامات الاقتباس المزدوجة المستندة إلى ASCII بما يعادلها في Unicode، أي \u0022. على سبيل المثال، التعبير التالي صالح وينتج عنه النتيجة المتوقعة:
request.header.Content-Type ~~ "(multipart\/related)(; *type=\u0022application\/xop\+xml\u0022)"