Share via

النُهج في Azure API Management

  • مقالة

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

في APIM Azure، يمكن لناشري واجهة برمجة التطبيقات تغيير سلوك واجهة برمجة التطبيقات من خلال التكوين باستخدام النُهج. النُهج هي مجموعة من العبارات التي يتم تشغيلها بشكل تسلسلي بناءً على طلب أو استجابة واجهة برمجة التطبيقات. توفر APIM أكثر من 50 نهج خارج المربع الذي يمكنك تكوينه لمعالجة سيناريوهات واجهة برمجة التطبيقات الشائعة مثل المصادقة، والحد من المعدل، والتخزين المؤقت، وتحويل الطلبات أو الاستجابات. للحصول على قائمة كاملة، راجع مرجع نهج 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 is 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.

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

النطاقات

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

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

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

نطاقات النهج

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

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

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

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

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

    إشعار

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

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

نهج محلل GraphQL

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

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

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

الحصول على المساعدة في إنشاء النهج باستخدام Microsoft Copilot ل Azure (معاينة)

يوفر Microsoft Copilot ل Azure (معاينة) إمكانات تأليف النهج لإدارة واجهة برمجة تطبيقات Azure. استخدم Copilot ل Azure في سياق محرر نهج APIM لإنشاء نهج تطابق متطلباتك المحددة دون معرفة بناء الجملة، أو قد كونت نهج مفسرة لك بالفعل.

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

هام

يتطلب Microsoft Copilot ل Azure (معاينة) التسجيل وهو متاح حاليا فقط لعملاء وشركاء المؤسسات المعتمدين. لمزيد من المعلومات، راجع وصول محدود إلى Microsoft Copilot ل Azure (معاينة).

الأمثلة

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

إذا كان لديك نهج على المستوى العالمي ونهج مكون لواجهة برمجة تطبيقات، فيمكن تطبيق كلا السياستين كلما تم استخدام واجهة برمجة التطبيقات المحددة. تسمح 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>

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

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