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

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

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

إشعار

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

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

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

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

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

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

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

تلميح

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

• OAuth2.0
• شهادة العميل
• تقييد عناوين IP للمتصل

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

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

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

إشعار

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

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

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

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

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

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

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

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

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

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

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

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

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

تحذير

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

إشعار

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

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

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

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

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

إشعار

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

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

ناشرو واجهات برمجة التطبيقات (المسؤولون أو المطورون الذين لديهم أذونات مناسبة) يمكنهم إنشاء اشتراكات مباشرة في بوابة Azure عن طريق تسجيل الدخول إلى نسخة إدارة واجهة برمجة التطبيقات الخاصة بهم. لا يمكن لمستهلكي واجهات برمجة التطبيقات إنشاء اشتراكات عبر بوابة Azure؛ عادة ما يطلبون الاشتراكات عبر بوابة المطورين أو يتلقونها من ناشري API.

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

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

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

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

تلميح

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

إشعار

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

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

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

تنبيه

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

إشعار

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

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

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

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

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

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

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

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

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

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

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

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

3. وإلا، ترفض إدارة API الوصول (خطأ 401 Access مرفوض).

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

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

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

جدول الملخص

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

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

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

الاعتبارات

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

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

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

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