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

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

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

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

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

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

<Condition></Condition>

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

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

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

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

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

المتغيرات

تؤدي الشروط عملها من خلال تقييم قيم variables. المتغيّر هو خاصية لمعاملة 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 عبارة مماثلة لتقييم الشروط. يقيّم المثال أعلاه القيمة true إذا كانت فعل HTTP المرتبط بالطلب هو GET. إذا كان فعل HTTP المرتبط بالطلب POST، ثم يتم تقييم العبارة إلى false.

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

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

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

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

الملخّص: "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؟ تمامًا مثل باستخدام عامل تشغيل التطابقات، يكون هناك احتمال واحد فقط في هذه الحالة.

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

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 (~~). لكن MatchPath مختلف تمامًا.

تذكَّر أنّ عامل التشغيل هذا ينظر إلى المسار على أنّه سلسلة من الأجزاء. لذلك، إذا لم يكن المسار هو: /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 الأساسي للخلفية عنوان 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 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>. لمزيد من المعلومات حول التدفقات، اطّلع على إعداد التدفقات:

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

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

سيكون بإمكانك:

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

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

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

في قسم Develop view (تطوير طريقة عرض المستكشف) لمحرر خادم وكيل واجهة برمجة التطبيقات Navigator، انقر على رمز + بجوار الإعداد الافتراضي في نقاط نهاية الخادم الوكيل.

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

  • اسم التدفق: المطوِّرون
  • نوع الشرط: المسار
  • المسار: ‎/developers

سيتم تفعيل الشرط (وسيتم تنفيذ السياسات) في حال إرسال طلب إلى الخادم الوكيل مع إضافة ‎/developers في نهاية عنوان URL.

أضف الآن تدفقًا شرطيًا لـ /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) الهرمية

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

/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/**

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

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

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

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

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

ومع ذلك، ستعمل هذه الطريقة:

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

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

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

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

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

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

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