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

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

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

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

إعداد العبارات الشرطية

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

<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، سيتم تقييم العبارة إلى false.

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

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

على سبيل المثال، لإنشاء تدفق لا يتم تنفيذه إلا عندما يكون فعل الطلب هو 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>

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

<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 لمعرفة ما إذا كان يتم تقييم الشرط على "صحيح".

إذا تم تقييم الشرط إلى 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 باستخدام الإعدادات التلقائية، ثم كتابة النتيجة على رسالة الردّ الجديدة. (إذا كنت تحوّل رسالة request من 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، ما يؤدي إلى تقييم العبارة الشرطية إلى true ويتم تنفيذ التدفق الشرطي 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" احتمالين. ويجب أن تكون هذه السلسلة مطابقة حرفيًا أو أن يتطابق حرف بدل مع "*". وكما يحدث، لا يتطابق حرف البدل مع أي حرف أو أكثر. لنرى كيف يعمل ذلك.

يعرض ملف XML التالي شرط الخطوة. تنفِّذ سياسة somePolicy عندما يتم تقييم الشرط إلى true. في هذا المثال، نختبر المتغيّر 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

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

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

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

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

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

JavaRegex

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

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

يعرض الرمز التالي شرط الخطوة. وتنفِّذ سياسة somePolicy إذا تم تقييم الشرط إلى true. في هذا المثال، نختبر المتغيّر 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"، وبالتالي يتم تقييم الشرط إلى true.

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

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

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

بعد ذلك، نستخدم النمط "[abc]" أو النمط "grouping" للتعبير عن التعبير العادي. ويتطابق مع الحرفين "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

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

خدمات REST هي مجموعات من موارد واجهة برمجة التطبيقات. مورد واجهة برمجة التطبيقات هو جزء من مسار عنوان 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 في جمعها عند استخدام الخادم الوكيل لواجهة برمجة التطبيقات، تتيح لك الخوادم الوكيلة أيضًا تحديد التدفقات الشرطية التي ترتبط بالموارد في الخلفية. وخلاصة القول هي "إذا تم إرسال استدعاء GET إلى المورد /reports, ، يجب أن يفعل Edge شيئًا ما".

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

كيفية تعيين الخوادم الوكيلة لواجهة برمجة التطبيقات إلى موارد خلفية معيّنة

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

لنفترض أنّك أردت أن تطلب من Edge "تنفيذ إجراء" عندما تردُّ المكالمات إلى المورد /reports أو /forecasts. في هذه المرحلة، لا يتم إعلام Edge بما يجب فعله، ولكن من المفترض أن تستمع إلى المكالمات الواردة إلى هذه الموارد. ويمكنك إجراء ذلك بشروط. في الخادم الوكيل لواجهة برمجة تطبيقات Edge، يمكنك إنشاء تدفقات شرطية لـ /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>. لمزيد من المعلومات عن المسارات، راجِع ضبط المسارات.

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

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

ستكون قادرًا على:

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

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

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

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

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

  • اسم التدفق: المطوّرون
  • نوع الشرط: مسار
  • المسار: /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) للطلب الوارد. (يحدد متغيّر client.pathsuffix معرّف الموارد المنتظم (URI) للطلب الذي يلي مسار BasePath الذي تم إعداده في إعداد ProxyEndpoint).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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