Subscriptions in Azure API Management

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

في Azure APIM، الاشتراكات هي الطريقة الأكثر شيوعاً لمستهلكي API للوصول إلى واجهات برمجة التطبيقات المنشورة من خلال مثيل APIM. توفر هذه المقالة نظرة عامة على المفهوم.

إشعار

يتم استخدام اشتراك APIM خصيصا لاستدعاء واجهات برمجة التطبيقات من خلال APIM باستخدام مفتاح اشتراك. إنه ليس نفس اشتراك Azure.

ماذا تكون الاشتراكات؟

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

• يتم رفضها فوراً من قبل بوابة APIM.
• لا يتم إعادة توجيهها إلى خدمات النهاية الخلفية.

للوصول إلى واجهات برمجة التطبيقات، يحتاج المطورون إلى اشتراك ومفتاح اشتراك. الاشتراك عبارة عن حاوية مسماة لزوج من مفاتيح الاشتراك.

وعلاوة على ذلك،

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

تلميح

تدعم APIM أيضا آليات أخرى لتأمين الوصول إلى واجهات برمجة التطبيقات، بما في ذلك الأمثلة التالية:

• OAuth2.0
• شهادة العميل
• Restrict caller IPs

إدارة مفاتيح الاشتراك

يعد إعادة إنشاء المفاتيح بانتظام إجراءً وقائياً أمنياً شائعاً. مثل معظم خدمات Azure التي تتطلب مفتاح اشتراك، تقوم APIM بإنشاء مفاتيح في هيئة أزواج. يمكن لكل تطبيق يستخدم الخدمة التبديل من المفتاح A إلى المفتاح B وإعادة إنشاء المفتاح A بأقل قدر من الانقطاع، والعكس صحيح.

يمكن تنفيذ تعيين مفاتيح معينة بدلا من إعادة إنشاءها عن طريق استدعاء اشتراك إدارة واجهة برمجة تطبيقات Azure - إنشاء أو تحديث Azure REST API. على وجه التحديد، properties.primaryKey يجب تعيين و/أو properties.secondaryKey في نص طلب HTTP.

إشعار

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

النطاق للاشتراكات

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

الاشتراكات للمنتج

تقليدياً، كانت الاشتراكات في APIM مقترنة بنطاق منتج واجهة برمجة التطبيقات واحد. المطورون:

• العثور على قائمة المنتجات خلال مدخل المطور.
• تقديم طلبات الاشتراك للمنتجات التي يريدون استخدامها.
• استخدم المفاتيح في تلك الاشتراكات (المعتمدة إما تلقائيًا أو بواسطة ناشري واجهة برمجة التطبيقات) للوصول إلى جميع واجهات برمجة التطبيقات في المنتج.

حاليًا، يعرض مدخل المطور اشتراكات النطاق للمنتج فقط ضمن قسم ملف تعريف المستخدم.

الاشتراكات لكافة واجهات برمجة التطبيقات أو واجهة برمجة التطبيقات الفردية

يمكنك أيضاً إنشاء مفاتيح تمنح حق الوصول إلى إما:

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

في هذه الحالات، لا تحتاج إلى إنشاء منتج وإضافة واجهات برمجة التطبيقات إليه أولاً.

اشتراك الوصول بالكامل

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

تحذير

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

إشعار

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

الاشتراكات المستقلة

تسمح API Management أيضا بالاشتراكات المستقلة ، والتي لا ترتبط بحساب مطور. تثبت هذه الميزة أنها مفيدة في سيناريوهات مشابهة للعديد من المطورين أو الفرق التي تشترك في الاشتراك.

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

• يدويًا مشاركة مفتاح الاشتراك.
• استخدم نظامًا مخصصًا لإتاحة مفتاح الاشتراك لفريقك.

إنشاء الاشتراكات وإدارتها في مدخل Microsoft Azure

يمكن لناشري واجهة برمجة التطبيقات الآن إنشاء اشتراكات مباشرة في مدخل Microsoft Azure.

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

استخدام مفتاح اشتراك

يمكن للمشترك استخدام مفتاح اشتراك APIM بإحدى طريقتين:

• أضف عنوان HTTP Ocp-Apim-Subscription-Key إلى الطلب، مع تمرير قيمة مفتاح اشتراك صالح.

• قم بتضمين معلمة استعلام مفتاح الاشتراك وقيمة صالحة في عنوان URL. يتم تحديد معلمة الاستعلام فقط إذا لم يكن العنوان موجودا.

تلميح

Ocp-Apim-Subscription-Key هو الاسم الافتراضي لعنوان مفتاح الاشتراك، ومفتاح الاشتراك هو الاسم الافتراضي لمعلمة الاستعلام. إذا رغبت في ذلك، يمكنك تعديل هذه الأسماء في الإعدادات لكل واجهة برمجة تطبيقات. على سبيل المثال، في المدخل، قم بتحديث هذه الأسماء في علامة التبويب الإعدادات لواجهة برمجة التطبيقات.

إشعار

عند تضمينه في عنوان طلب أو معلمة استعلام، يتم تمرير مفتاح الاشتراك بشكل افتراضي إلى الخلفية وقد يتم كشفه في سجلات المراقبة الخلفية أو الأنظمة الأخرى. إذا كانت هذه البيانات تعتبر بيانات حساسة، يمكنك تكوين نهج في نهاية inbound القسم لإزالة عنوان مفتاح الاشتراك (set-header) أو معلمة الاستعلام (set-query-parameter).

تمكين متطلبات الاشتراك أو تعطيلها لواجهة برمجة التطبيقات أو الوصول إلى المنتج

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

تنبيه

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

إشعار

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

يمكنك تعطيل متطلبات الاشتراك في الوقت الذي تقوم فيه بإنشاء واجهة برمجة تطبيقات أو منتج، أو في تاريخ لاحق.

لتعطيل متطلبات الاشتراك باستخدام المدخل:

• تعطيل متطلبات المنتج - في صفحة الإعدادات للمنتج، قم بتعطيل Requires subscription
• تعطيل متطلبات واجهة برمجة التطبيقات - في صفحة الإعدادات لواجهة برمجة التطبيقات، قم بتعطيل الاشتراك المطلوب.

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

كيف تتعامل APIM مع الطلبات باستخدام مفاتيح الاشتراك أو بدونها

طلب واجهة برمجة التطبيقات باستخدام مفتاح اشتراك

عندما تتلقى APIM طلب واجهة برمجة التطبيقات من عميل بمفتاح اشتراك، فإنه يعالج الطلب وفقا لهذه القواعد:

1. تحقق أولا مما إذا كان مفتاحا صالحا مقترنا باشتراك نشط، إما:

   • اشتراك تم تحديد نطاقه لواجهة برمجة التطبيقات
   • اشتراك محدد النطاق لمنتج تم تعيينه إلى واجهة برمجة التطبيقات
   • اشتراك محدد النطاق لجميع واجهات برمجة التطبيقات
   • الاشتراك في نطاق الخدمة (اشتراك الوصول المضمن)

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

2. إذا لم يكن المفتاح صالحا ولكن يوجد منتج يتضمن واجهة برمجة التطبيقات ولكنه لا يتطلب اشتراكا (منتج مفتوح)، فتجاهل المفتاح واتعامل معه كطلب واجهة برمجة تطبيقات بدون مفتاح اشتراك (انظر أدناه).

3. وإلا، يتم رفض الوصول (خطأ 401 رفض الوصول).

طلب واجهة برمجة التطبيقات بدون مفتاح اشتراك

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

1. تحقق أولاً من وجود منتج يتضمن واجهة برمجة التطبيقات ولكنه لا يتطلب اشتراكاً (منتج مفتوح). إذا كان المنتج المفتوح موجودا، فتعامل مع الطلب في سياق واجهات برمجة التطبيقات والنهج وقواعد الوصول المكونة للمنتج المفتوح. يمكن ربط واجهة برمجة التطبيقات بمنتج مفتوح واحد على الأكثر.
2. إذا لم يتم العثور على منتج مفتوح بما في ذلك واجهة برمجة التطبيقات، فتحقق مما إذا كانت واجهة برمجة التطبيقات تتطلب اشتراكاً أم لا. إذا لم يكن الاشتراك مطلوباً، فتعامل مع الطلب في سياق واجهة برمجة التطبيقات هذه والعملية.
3. إذا لم يتم العثور على منتج أو واجهة برمجة تطبيقات مكونة، رفض الوصول (خطأ 401 رفض الوصول).

جدول الملخص

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

تتطلب جميع المنتجات المعينة لواجهة برمجة التطبيقات اشتراكا	تتطلب واجهة برمجة التطبيقات الاشتراك	استدعاء واجهة برمجة التطبيقات مع مفتاح الاشتراك	استدعاء واجهة برمجة التطبيقات بدون مفتاح اشتراك	السيناريوهات المعتادة
✔️	✔️	الوصول المسموح به: • مفتاح نطاق المنتج • مفتاح نطاق واجهة برمجة التطبيقات • جميع مفاتيح نطاق واجهات برمجة التطبيقات • مفتاح نطاق الخدمة تم رفض الوصول: • مفتاح آخر غير محدد النطاق للمنتج أو واجهة برمجة التطبيقات القابلة للتطبيق	تم رفض الوصول	الوصول المحمي إلى واجهة برمجة التطبيقات باستخدام اشتراك نطاق المنتج أو اشتراك نطاق واجهة برمجة التطبيقات
✔️	❌	الوصول المسموح به: • مفتاح نطاق المنتج • مفتاح نطاق واجهة برمجة التطبيقات • جميع مفاتيح نطاق واجهات برمجة التطبيقات • مفتاح نطاق الخدمة • مفتاح آخر غير محدد النطاق للمنتج أو واجهة برمجة التطبيقات القابلة للتطبيق	الوصول المسموح به (سياق واجهة برمجة التطبيقات)	• الوصول المحمي إلى واجهة برمجة التطبيقات مع اشتراك نطاق المنتج • وصول مجهول إلى واجهة برمجة التطبيقات. إذا لم يكن الوصول المجهول مقصودا، فكون نهج على مستوى واجهة برمجة التطبيقات لفرض المصادقة والتخويل.
❌1	✔️	الوصول المسموح به: • مفتاح نطاق المنتج • مفتاح نطاق واجهة برمجة التطبيقات • جميع مفاتيح نطاق واجهات برمجة التطبيقات • مفتاح نطاق الخدمة تم رفض الوصول: • مفتاح آخر غير محدد النطاق للمنتج أو واجهة برمجة التطبيقات القابلة للتطبيق	الوصول المسموح به (سياق المنتج المفتوح)	• الوصول المحمي إلى واجهة برمجة التطبيقات مع اشتراك نطاق واجهة برمجة التطبيقات • وصول مجهول إلى واجهة برمجة التطبيقات. إذا لم يكن الوصول المجهول مقصودا، فكون باستخدام نهج المنتج لفرض المصادقة والتخويل
❌1	❌	الوصول المسموح به: • مفتاح نطاق المنتج • مفتاح نطاق واجهة برمجة التطبيقات • جميع مفاتيح نطاق واجهات برمجة التطبيقات • مفتاح نطاق الخدمة • مفتاح آخر غير محدد النطاق للمنتج أو واجهة برمجة التطبيقات القابلة للتطبيق	الوصول المسموح به (سياق المنتج المفتوح)	وصول مجهول إلى واجهة برمجة التطبيقات. إذا لم يكن الوصول المجهول مقصودا، فكون باستخدام نهج المنتج لفرض المصادقة والتخويل

¹ يوجد منتج مفتوح مقترن بواجهة برمجة التطبيقات.

الاعتبارات

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

الخطوات التالية

الحصول على مزيد من المعلومات حول APIM:

• تعرف على كيفية تطبيق نهج APIM في نطاقات مختلفة.
• Microsoft Learnمفاهيم أخرى في APIM.
• اتبع برنامج تعليمي لمعرفة المزيد عن APIM.
• تحقق من صفحة الأسئلة المتداولة الخاصة بنا للاطلاع على الأسئلة الشائعة.