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

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

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

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

لمزيد من المعلومات، راجع الإصداراتوالمراجعات.

تلميح

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

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

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

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

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

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

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

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

3. اختر Swagger Petstore من قائمة API، أو API آخر تريد إضافة تعديلات إليه.

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

5. تحديد + Add revision.

   

   تلميح

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

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

7. حدد إنشاء.

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

   إشعار

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

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

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

2. اختر التصميم بالقرب من أعلى الشاشة.

   محدد المراجعة فوق تبويب التصميم يظهر النسخة الثانية كما هي المحددة حاليا.

   تلميح

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

3. تحديد + Add Operation.

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

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

   

   لقد أجريت الآن تغييراً على Revision 2.

6. استخدام revision selector بالقرب من أعلى الصفحة للرجوع إلى Revision 1.

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

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

بوابة

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

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

3. تحديد Make current.

4. إذا أردت نشر ملاحظات حول هذا التغيير، اختر سجل النشر إلى التغيير العام لهذه الواجهة. تقديم وصف للتغيير الذي يظهر للمطورين، على سبيل المثال: Testing revisions. Added new "test" operation.

   تسري Revision 2 الآن.

   

Azure CLI

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

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

  

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

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

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

إذا جربت بوابة المطورين، يمكنك مراجعة تغييرات واجهة برمجة التطبيقات وتسجيل التغييرات هناك.

1. في مدخل Azure، انتقل إلى مثيل API Management.
2. في القائمة اليسرى، ضمن واجهات برمجة التطبيقات، حدد واجهات برمجة التطبيقات.
3. تحديد Developer portal من القائمة العلوية.
4. في مدخل المطور، حدد واجهات برمجة التطبيقات، ثم حدد Swagger Petstore.
5. يرجى ملاحظة أن عملية test الجديدة متاحة الآن.
6. اختر تغيير سجل البرمجة بالقرب من اسم واجهة برمجة التطبيقات.
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} بمسار واجهة برمجة التطبيقات الخاص بك.

الملخص

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

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

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

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

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