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

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

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

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

للحصول على معلومات أساسية، يرجى مراجعة Versions & revisions وAPI Versioning with Azure API Management.

في هذا البرنامج التعليمي، تتعلم كيفية:

• إضافة إصدار جديد
• إجراء تغييرات غير منقطعة على مراجعتك
• عمل المراجعة الحالية الخاصة بك وإضافة إدخال سجل التغيير
• تصفح بوابة المطور لرؤية التغييرات وسجل التغيير

المتطلبات الأساسية

• التعرف على Azure API Management terminology.
• أكمل التشغيل السريع التالي:إنشاء مثيل لـ Azure API Management.
• كما يلزم إتمام البرنامج التعليمي التالي: استيراد ونشر واجهة برمجة التطبيقات الأولى الخاصة بك.

إضافة إصدار جديد

1. سجل الدخول إلى مدخل Azure، وانتقل إلى مثيل إدارة واجهة برمجة التطبيقات الخاصة بك.

2. تحديد APIs.

3. تحديد Demo Conference API من قائمة API (أو API أخرى تريد إضافة مراجعات إليها).

4. تحديد علامة تبويب "Revisions".

5. تحديد + Add revision.

   

   تلميح

   يمكن أيضاً تحديد Add revision في قائمة السياق (...) لـ API.

6. تقديم وصفاً لمراجعتك الجديدة، للمساعدة في تذكر الغرض الذي سيتم استخدامه من أجله.

7. حدد إنشاء.

8. أُنشئت الآن نسختك الجديدة.

   إشعار

   تظل API الأصلية الخاصة بك في Revision 1. هذه هي المراجعة التي يستمر المستخدمون في الاتصال بها، حتى اختيار إجراء مراجعة مختلفة حالياً.

إجراء تغييرات غير منقطعة على مراجعتك

1. تحديد Demo Conference API من قائمة واجهة برمجة التطبيقات.

2. تحديد علامة تبويب "Design" بالقرب من أعلى الشاشة.

3. ملاحظة أن revision selector (أعلى علامة تبويب التصميم مباشرةً) يعرض Revision 2 كما هو محدد حالياً.

   تلميح

   استخدام محدد المراجعة للتبديل بين المراجعات المراد العمل عليها.

4. تحديد + Add Operation.

5. تعيين عمليتك الجديدة لتكون POST، والاسم واسم العرض وعنوان "URL" للعملية على أنها test.

6. احفظ العملية الجديدة.

   

7. لقد أجريت الآن تغييراً على Revision 2. استخدام revision selector بالقرب من أعلى الصفحة للرجوع إلى Revision 1.

8. يرجى الملاحظة أن العملية الجديدة لا تظهر في Revision 1.

عمل المراجعة الحالية الخاصة بك وإضافة إدخال سجل التغيير

المدخل

1. تحديد علامة تبويب "Revisions" من القائمة بالقرب من أعلى الصفحة.

2. فتح قائمة السياق (...) لـ Revision 2.

3. تحديد Make current.

4. تحديد مربع الاختيار Post to Public Change log for this API، عند الرغبة في نشر ملاحظات حول هذا التغيير. تقديم وصف للتغيير الذي يظهر للمطورين، على سبيل المثال: Testing revisions. Added new "test" operation.

5. تسري Revision 2 الآن.

   

Azure CLI

للبدء في استخدام Azure CLI:

• استخدم بيئة Bash في Azure Cloud Shell. لمزيد من المعلومات، راجع التشغيل السريع ل Bash في Azure Cloud Shell.

  

• إذا كنت تفضل تشغيل أوامر مرجع CLI محلياً قم بتثبيت CLI Azure. إذا كنت تعمل على نظام تشغيل Windows أو macOS، ففكر في تشغيل Azure CLI في حاوية Docker. لمزيد من المعلومات، راجع كيفية تشغيل Azure CLI في حاوية Docker.

  • إذا كنت تستخدم تثبيت محلي، يُرجى تسجيل الدخول إلى Azure CLI مستخدمًا أمر az login. لإنهاء عملية المصادقة، اتبع الخطوات المعروضة في جهازك. للحصول على خيارات أخرى لتسجيل دخول، راجع تسجيل الدخول باستخدام Azure CLI.

  • عندما يُطلب منك، قم بتثبيت ملحق Azure CLI عند الاستخدام لأول مرة. لمزيد من المعلومات بشأن الامتدادات، راجع استخدام امتدادات مع Azure CLI.

  • يُرجى تشغيل إصدار az للوصول إلى الإصدار والمكتبات التابعة التي تم تثبيتها. للتحديث لآخر إصدار، يُرجى تشغيل تحديث az.

استخدم هذا الإجراء لإنشاء إصدار وتحديثه.

1. تشغيل الأمر az apim api list لمشاهدة API IDs الخاصة بك:

   az apim api list --resource-group apim-hello-word-resource-group \
       --service-name apim-hello-world --output table
   

   معرف API المراد استخدامه في الأمر التالي هو قيمة Name. مراجعة API موجودة في عمود ApiRevision.

2. لإنشاء الإصدار، مع ملاحظة الإصدار، يجب تشغيل الأمر az apim api release create:

   az apim api release create --resource-group apim-hello-word-resource-group \
       --api-id demo-conference-api --api-revision 2 --service-name apim-hello-world \
       --notes 'Testing revisions. Added new "test" operation.'
   

   تصبح المراجعة التي تحررها هي المراجعة الحالية.

3. لمشاهدة إصداراتك، يمكن استخدام الأمر az apim api release list command:

   az apim api release list --resource-group apim-hello-word-resource-group \
       --api-id echo-api --service-name apim-hello-world --output table
   

   تظهر الملاحظات التي تحددها في سجل التغيير. يمكن رؤيتها في مخرج الأمر السابق.

4. عند إنشاء إصدار، تكون المعلمة --notes اختيارية. يمكن إضافة الملاحظات أو تغييرها لاحقاً باستخدام الأمر az apim api release update:

   az apim api release update --resource-group apim-hello-word-resource-group \
       --api-id demo-conference-api --release-id 00000000000000000000000000000000 \
       --service-name apim-hello-world --notes "Revised notes."
   

   نتائج الترجمة استخدام القيمة الموجودة في العمود Name لمعرف الإصدار.

يمكن إزالة أي إصدار بتشغيل الأمر az apim api release delete :

az apim api release delete --resource-group apim-hello-word-resource-group \
    --api-id demo-conference-api --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

تصفح بوابة المطور لرؤية التغييرات وسجل التغيير

في حالة تجربة developer portal، فيمكن مراجعة تغييرات API وتغيير السجل هناك.

1. في مدخل Microsoft Azure، تحديد APIs.
2. تحديد Developer portal من القائمة العلوية.
3. في بوابة المطور، تحديد APIs، ثم تحديد Demo Conference API.
4. يرجى ملاحظة أن عملية test الجديدة متاحة الآن.
5. تحديد "Changelog" بالقرب من اسم API.
6. يرجى ملاحظة أن إدخال سجل التغيير يظهر في هذه القائمة.

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

في هذا البرنامج التعليمي، نتعلم طريقة القيام بما يأتي:

• إضافة إصدار جديد
• إجراء تغييرات غير منقطعة على مراجعتك
• عمل المراجعة الحالية الخاصة بك وإضافة إدخال سجل التغيير
• تصفح بوابة المطور لرؤية التغييرات وسجل التغيير

تقدم إلى البرنامج التعليمي الآتي:

Publish multiple versions of your API