الإصدارات في Azure API Management

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

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

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

باستخدام الإصدارات، يمكنك:

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

ابدأ بالإصدارات من خلال إكمال معاينة.

أنظمة تعيين الإصدار

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

تعيين الإصدار المستند إلى المسار

عند استخدام نظام تعيين إصدار المسار، يجب تضمين معرف الإصدار في مسار URL لأي طلبات API.

على سبيل المثال، https://apis.contoso.com/products/v1 ويمكن أن يشير إلى https://apis.contoso.com/products/v2 نفس products واجهة برمجة التطبيقات ولكن إلى الإصدارات v1 و v2.

تنسيق عنوان URL لطلب واجهة برمجة التطبيقات عند استخدام تعيين الإصدار المستند إلى المسار هو https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}.

تعيين الإصدار المستند إلى العنوان

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

على سبيل المثال، قد تقوم بإنشاء عنوان مخصص يسمى Api-Version، ويمكن للعملاء تحديد v1 أو v2 في قيمة هذا العنوان.

تعيين الإصدار المستند إلى سلسلة الاستعلام

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

تنسيق عنوان URL لطلب واجهة برمجة التطبيقات عند استخدام تعيين الإصدار المستند إلى سلسلة الاستعلام هو https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}.

على سبيل المثال، https://apis.contoso.com/products?api-version=v1 ويمكن أن يشير إلى https://apis.contoso.com/products?api-version=v2 نفس products واجهة برمجة التطبيقات ولكن إلى الإصدارات v1 و v2.

ملاحظة

لا يسمح بمعلمات الاستعلام في servers خاصية مواصفات OpenAPI. إذا قمت بتصدير مواصفات OpenAPI من إصدار واجهة برمجة التطبيقات، فلن تظهر سلسلة استعلام في عنوان URL للخادم.

الإصدارات الأصلية

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

كيفية تمثيل الإصدارات

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

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

ينشئ مدخل Microsoft Azure مجموعات إصدارات لك. يمكنك تعديل الاسم والوصف لإصدار معين في مدخل Microsoft Azure.

يتم حذف مجموعة إصدارات تلقائيا عند حذف الإصدار النهائي.

يمكنك عرض مجموعات الإصدارات وإدارتها مباشرة باستخدام Azure CLI أو Azure PowerShell أو قوالب Resource Manager أو واجهة برمجة تطبيقات Azure Resource Manager.

ملاحظة

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

ترحيل واجهة برمجة تطبيقات غير إصدار إلى واجهة برمجة تطبيقات تم إصدارها

عند استخدام مدخل Microsoft Azure لتمكين تعيين الإصدار على واجهة برمجة تطبيقات موجودة، يتم إجراء التغييرات التالية على موارد APIM:

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

الإصدارات والمراجعات

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

إذا وجدت أن مراجعتك تحتوي على تغييرات فاصلة، أو إذا كنت تريد تحويل مراجعتك رسميا إلى إصدار بيتا/اختبار، يمكنك إنشاء إصدار من مراجعة. في مدخل Microsoft Azure، حدد Create Version من هذه المراجعة في قائمة سياق المراجعة (...) في علامة التبويب Revisions .

مدخل المطور

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

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

تلميح

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