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

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

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

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

للحصول على الخلفية، راجع الإصدارات والمراجعات.

تلميح

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

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

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

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

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

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

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

2. في القائمة اليسرى، ضمن واجهات برمجة التطبيقات، حدد واجهات برمجة التطبيقات.

3. حدد Swagger Petstore من قائمة واجهة برمجة التطبيقات (أو واجهة برمجة تطبيقات أخرى تريد إضافة مراجعات إليها).

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

5. تحديد + Add revision.

   

   تلميح

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

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

7. حدد إنشاء.

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

   إشعار

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

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

1. حدد Swagger Petstore من قائمة واجهة برمجة التطبيقات.

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

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

   تلميح

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

4. تحديد + Add Operation.

5. قم بتعيين العملية الجديدة إلى POST واسم العرض والاسم وعنوان URL للعملية كاختبار.

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 api list لمشاهدة معرفات واجهة برمجة التطبيقات الخاصة بك:

   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 swagger-petstore --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 swagger-petstore --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 swagger-petstore --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 swagger-petstore --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

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

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

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

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

يمكن الوصول إلى كل مراجعة لواجهة برمجة التطبيقات الخاصة بك باستخدام عنوان URL تم تكوينه بشكل خاص. أضف ;rev={revisionNumber} في نهاية مسار عنوان URL لواجهة برمجة التطبيقات، ولكن قبل سلسلة الاستعلام، للوصول إلى مراجعة محددة لواجهة برمجة التطبيقات هذه. على سبيل المثال، قد تستخدم عنوان URL مشابها لما يلي للوصول إلى المراجعة 2 من واجهة برمجة تطبيقات Swagger Petstore:

https://apim-hello-world.azure-api.net/store/pet/1;rev=2/

يمكنك العثور على مسارات عنوان URL لمراجعات واجهة برمجة التطبيقات في علامة التبويب "Revisions " في مدخل Microsoft Azure.

تلميح

يمكنك الوصول إلى المراجعة الحالية لواجهة برمجة التطبيقات الخاصة بك باستخدام مسار واجهة برمجة التطبيقات بدون ;rev السلسلة، بالإضافة إلى عنوان URL الكامل الذي إلحاق ;rev={revisionNumber} بمسار واجهة برمجة التطبيقات الخاص بك.

الملخص

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

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

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

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

Publish multiple versions of your API