مشاركة عبر

النُهج في Azure API Management

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

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

النُهج هي مجموعة من العبارات التي يتم تشغيلها بشكل تسلسلي بناءً على طلب أو استجابة واجهة برمجة التطبيقات. توفر APIM أكثر من 75 نهج خارج المربع الذي يمكنك تكوينه لمعالجة سيناريوهات واجهة برمجة التطبيقات الشائعة مثل المصادقة، والحد من المعدل، والتخزين المؤقت، وتحويل الطلبات أو الاستجابات. للحصول على قائمة كاملة، راجع مرجع نهج APIM.

تتضمن النهج الشائعة ما يلي:

  • تنسيق التحويل من XML إلى JSON.
  • تحديد معدل المكالمات لتقييد عدد المكالمات الواردة من مطور.
  • تصفية الطلبات التي تأتي من عناوين IP معينة.

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

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

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

  • محرر إرشادي مستند إلى النموذج لتبسيط تكوين النُهج الشائعة دون ترميز XML
  • محرر تعليمات برمجية حيث يمكنك إدراج مقتطفات XML أو تحرير XML مباشرة

لمزيد من المعلومات حول تكوين النُهج، راجع تعيين النُهج أو تحريرها.

تنقسم تكوين XML للنهج إلى أقسام inboundو backendoutboundon-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's an error condition go here -->
  </on-error>
</policies>

للحصول على أمثلة XML للنهج، راجع API Management policy snippets repo.

معالجة الخطأ

في حالة حدوث خطأ أثناء معالجة الطلب:

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

عن طريق وضع عبارات النهج في قسم on-error، يمكنك:

  • راجع الخطأ باستخدام الخاصية context.LastError .
  • فحص استجابة الخطأ وتخصيصها باستخدام النهج set-body .
  • تكوين ما يحدث في حالة حدوث خطأ.

لمزيد من المعلومات، راجع معالجة الأخطاء في نهج APIM.

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

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

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

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

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

النطاقات

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

  • عالمي (جميع واجهات برمجة التطبيقات)
  • مساحة العمل (جميع واجهات برمجة التطبيقات المقترنة بمساحة عمل محددة)
  • المنتج (جميع واجهات برمجة التطبيقات المقترنة بمنتج محدد)
  • API (كل العمليات في API)
  • العملية (عملية واحدة في واجهة برمجة التطبيقات)

عند تكوين نهج، يجب عليك أولاً تحديد النطاق الذي تنطبق عليه النهج.

رسم تخطيطي يوضح نطاقات النهج الخمسة.

الأشياء التي يجب معرفتها

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

  • لا يتم دعم كافة النهج في كل قسم من أقسام النطاق والنهج.

  • عند تكوين تعريفات النهج في أكثر من نطاق واحد، يمكنك التحكم في توريث النهج وترتيب تقييم النهج في كل قسم نهج حسب موضع base العنصر.

    مهم

    كأفضل ممارسة، قم بتضمين base عنصر في بداية كل قسم نهج لتوريث النهج من النطاق الأصل. وهذا يضمن عدم تجاوز أو تجاهل أي نهج محددة على مستوى أعلى عن غير قصد. يتوفر تعريف نهج Azure المضمن (API Management policies should inherit parent scope policies using <base/>) لتدقيق أفضل الممارسات هذه أو فرضها.

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

    إشعار

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

لمزيد من المعلومات، راجع:

نهج محلل GraphQL

في APIM، يتم تكوين محلل GraphQL مع نهج محددة النطاق لنوع عملية وحقل معين في مخطط GraphQL.

  • حاليا، تدعم APIM محللات GraphQL التي تحدد إما HTTP API أو Azure Cosmos DB أو مصادر بيانات Azure SQL. على سبيل المثال، يمكنك تكوين نهج واحد http-data-source مع عناصر لتحديد طلب إلى (والاستجابة اختياريا من) مصدر بيانات HTTP.
  • لا يمكنك تضمين نهج محلل في تعريفات النهج في نطاقات أخرى، مثل واجهة برمجة التطبيقات أو المنتج أو جميع واجهات برمجة التطبيقات. كما لا يرث النهج النهج التي تم تكوينها في نطاقات أخرى.
  • تقوم البوابة بتقييم نهج محدد النطاق للمحلل بعد أي نهج تم تكوينها inbound و backend في مسار تنفيذ النهج.

لمزيد من المعلومات، راجع تكوين محلل GraphQL.

الحصول على مساعدة Copilot

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

مثال المطالبة:

Generate a policy that adds an Authorization header to the request with a Bearer token.

يتم تشغيل Copilot بواسطة الذكاء الاصطناعي، لذلك من الممكن حدوث مفاجآت وأخطاء. لمزيد من المعلومات، راجع الأسئلة المتداولة حول استخدام Copilot العام.

الأمثلة

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

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

مثال على تعريف النهج في نطاق واجهة برمجة التطبيقات:

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

في مثال تعريف النهج السابق:

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

إشعار

إذا قمت بإزالة عنصر base في نطاق واجهة برمجة التطبيقات، فسيتم تطبيق النُهج التي تم تكوينها في نطاق واجهة برمجة التطبيقات فقط. لن يتم تطبيق النهج التي تم تكوينها في المنتج والنطاقات الأوسع.

استخدم تعبيرات النهج لتعديل الطلبات

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

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

المحتوى ذو الصلة

لمزيد من المعلومات حول العمل مع النُهج، راجع:

  • Last updated on