استكشاف نُهُج APIM

3 دقائق

في Azure API Management، تسمح النهج للناشر بتغيير سلوك واجهة برمجة التطبيقات من خلال التكوين. وهي موجودة كمجموعة من العبارات التي يتم تنفيذها بالتتابع بناءً على طلب أو استجابة لواجهة برمجة التطبيقات.

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

فهم تكوين النَهج

تعريف النهج هو مستند XML بسيط يصف سلسلة من العبارات الواردة والصادرة. يمكن تحرير XML مباشرةً في إطار التعريف.

وينقسم التكوين إلى inbound وbackend وoutbound وon-error. يتم تنفيذ سلسلة من عبارات النَهج المحددة من أجل طلب واستجابة.

<policies>
  <inbound>
    <!-- statements to be applied to the request go here -->
  </inbound>
  <backend>
    <!-- statements to be applied before the request is forwarded to 
         the backend service go here -->
  </backend>
  <outbound>
    <!-- statements to be applied to the response go here -->
  </outbound>
  <on-error>
    <!-- statements to be applied if there is an error condition go here -->
  </on-error>
</policies>

إذا كان هناك خطأ أثناء معالجة الطلب، يتم تخطي أي خطوات متبقية في inboundbackendالمقاطع أو أو outbound وينتقل التنفيذ إلى العبارات الموجودة on-error في المقطع. بوضع عبارات النَهج في المقطع on-error يمكنك مراجعة الخطأ باستخدام الخاصية context.LastError، فحص وتخصيص استجابة الخطأ باستخدام النهج set-body وتكوين ما يحدث في حالة حدوث خطأ ما.

تعبيرات النهج

ما لم تحدد النهج خلاف ذلك، يمكن استخدام تعبيرات النهج كقيم سمات أو قيم نصية في أي من نُهج APIM. يكون تعبير النهج إما:

عبارة C# واحدة مضمنة في @(expression)، أو
كتلة التعليمة البرمجية C# متعددة العبارات، المضمنة في @{expression}، تعرض قيمة

لكل تعبير حق الوصول إلى متغير context المقدم ضمنياً ومجموعة فرعية مسموح بها من أنواع .NET Framework.

توفر تعبيرات النهج وسيلة متطورة للتحكم في حركة المرور وتعديل سلوك واجهة برمجة التطبيقات دون مطالبتك بكتابة تعليمات برمجية متخصصة أو تعديل خدمات الواجهة الخلفية.

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

<policies>
    <inbound>
        <base />
        <set-header name="x-request-context-data" exists-action="override">
            <value>@(context.User.Id)</value>
            <value>@(context.Deployment.Region)</value>
      </set-header>
    </inbound>
</policies>

تطبيق النُهج المحددة في نطاقات مختلفة

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

<policies>
    <inbound>
        <cross-domain />
        <base />
        <find-and-replace from="xyz" to="abc" />
    </inbound>
</policies>

في تعريف نهج المثال السابق، سيتم تنفيذ العبارة cross-domain أولا. سيتم تنفيذ النهج find-and-replace بعد أي نهج في نطاق أوسع.

تصفية محتوى الاستجابة

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

تفترض القصاصة البرمجية أن محتوى الاستجابة منسق ك JSON ويحتوي على خصائص على مستوى الجذر تسمى دقيقة وساعة ويومية وعلامات.

<policies>
  <inbound>
    <base />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <choose>
      <when condition="@(context.Response.StatusCode == 200 && context.Product.Name.Equals("Starter"))">
        <!-- NOTE that we are not using preserveContent=true when deserializing response body stream into a JSON object since we don't intend to access it again. See details on /azure/api-management/api-management-transformation-policies#SetBody -->
        <set-body>
          @{
            var response = context.Response.Body.As<JObject>();
            foreach (var key in new [] {"minutely", "hourly", "daily", "flags"}) {
            response.Property (key).Remove ();
           }
          return response.ToString();
          }
    </set-body>
      </when>
    </choose>    
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>

استكشاف نُهُج APIM

فهم تكوين النَهج

تعبيرات النهج

تطبيق النُهج المحددة في نطاقات مختلفة

تصفية محتوى الاستجابة

الملاحظات