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

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

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

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

مع الإصدارات يمكنك:

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

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

مخططات تعيين الإصدار

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

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

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

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

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

تنسيق عنوان 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.

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

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

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

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

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

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

إشعار

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

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

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

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

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

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

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

مدخل المطور

يسرد مدخل المطور كل إصدار من إصدارات API بشكل منفصل.

تُظهر تفاصيل واجهة برمجة التطبيقات أيضًا قائمة بجميع إصدارات واجهة برمجة التطبيقات هذه. يتم عرض إصدار Original بدون معرف الإصدار.

تلميح

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