استيراد واجهات برمجة التطبيقات إلى مركز API الخاص بك من Azure API Management

توضح هذه المقالة كيفية استيراد (إضافة) واجهات برمجة التطبيقات من مثيل إدارة واجهة برمجة تطبيقات Azure إلى مركز واجهة برمجة التطبيقات باستخدام Azure CLI. تساعد إضافة واجهات برمجة التطبيقات من API Management إلى مخزون واجهة برمجة التطبيقات على جعلها قابلة للاكتشاف والوصول إليها من قبل المطورين ومديري برامج واجهة برمجة التطبيقات وأصحاب المصلحة الآخرين في مؤسستك.

تعرض هذه المقالة خيارين لاستخدام Azure CLI لإضافة واجهات برمجة التطبيقات إلى مركز API الخاص بك من APIM:

• الخيار 1: تصدير تعريف واجهة برمجة التطبيقات من مثيل إدارة واجهة برمجة التطبيقات باستخدام الأمر az apim api export ، ثم استيراد التعريف إلى مركز واجهة برمجة التطبيقات.

  تتضمن الطرق المحتملة لاستيراد تعريف واجهة برمجة التطبيقات التي تم تصديرها من APIM ما يلي:

  • قم بتشغيل az apic api register لتسجيل واجهة برمجة تطبيقات جديدة في مركز API الخاص بك.
  • قم بتشغيل az apic api definition import-specification لاستيراد تعريف واجهة برمجة التطبيقات إلى واجهة برمجة تطبيقات موجودة.

• الخيار 2: استيراد واجهات برمجة التطبيقات مباشرة من إدارة واجهة برمجة التطبيقات إلى مركز واجهة برمجة التطبيقات باستخدام الأمر az apic import-from-apim .

بعد استيراد تعريفات واجهة برمجة التطبيقات أو واجهات برمجة التطبيقات من APIM، يمكنك إضافة بيانات التعريف والوثائق في مركز واجهة برمجة التطبيقات لمساعدة المساهمين على اكتشاف واجهة برمجة التطبيقات وفهمها واستهلاكها.

تلميح

يمكنك أيضا إعداد المزامنة التلقائية لواجهات برمجة التطبيقات من APIM إلى مركز واجهة برمجة التطبيقات. لمزيد من المعلومات، راجع ربط مثيل APIM لمزامنة واجهات برمجة التطبيقات بمركز API الخاص بك.

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

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

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

• واحد أو أكثر من واجهات برمجة التطبيقات المدارة في مثيل APIM الذي تريد إضافته إلى مركز API الخاص بك.

• بالنسبة إلى 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.

  إشعار

  تتطلب الأوامر az apic إضافة apic-extension Azure CLI. يمكن تثبيت الإضافة ديناميكيا عند تشغيل أول az apic أمرة، أو يمكنك تثبيت الإضافة يدويا. لمزيد من المعلومات، راجع إدارة امتدادات Azure CLI: تثبيت، تحديث، وإزالة.

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

  إشعار

  يمكن تشغيل أمثلة أوامر Azure CLI في هذه المقالة في PowerShell أو bash shell. عند الحاجة بسبب بناء جملة متغير مختلف، يتم توفير أمثلة أوامر منفصلة للقذيفتين.

الخيار 1: تصدير تعريف واجهة برمجة التطبيقات من APIM واستيراده إلى مركز واجهة برمجة التطبيقات

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

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

يقوم الأمر المثال التالي بتصدير واجهة برمجة التطبيقات مع المعرف my-api في مثيل myAPIManagement من واجهة برمجة التطبيقات. يتم تصدير واجهة برمجة التطبيقات بتنسيق OpenApiJson إلى ملف تعريف OpenAPI محلي في المسار الذي تحدده.

#! /bin/bash
az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonFile \
    --file-path "/path/to/folder"

# Formatted for PowerShell
az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonFile `
    --file-path '/path/to/folder'

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

في المثال التالي، يصدر az apim api export API مع المعرف my-api بتنسيق OpenApiJson إلى عنوان URL في تخزين Azure. يتوفر عنوان URL لمدة خمس دقائق تقريبا. هنا، يتم تخزين قيمة عنوان URL في متغير $link .

#! /bin/bash
link=$(az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link \
    --output tsv)

# Formatted for PowerShell
$link=$(az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link `
    --output tsv)

تسجيل واجهة برمجة التطبيقات في مركز واجهة برمجة التطبيقات من تعريف واجهة برمجة التطبيقات المصدرة

يمكنك تسجيل واجهة برمجة تطبيقات جديدة في مركز API الخاص بك من التعريف المصدر باستخدام الأمر az apic api register .

يسجل المثال التالي واجهة برمجة تطبيقات في مركز myAPICenter API من ملف تعريف OpenAPI محلي يسمى definitionFile.json.

az apic api register --resource-group myResourceGroup --service-name myAPICenter --api-location "/path/to/definitionFile.json"

استيراد تعريف واجهة برمجة التطبيقات إلى واجهة برمجة تطبيقات موجودة في مركز واجهة برمجة التطبيقات

يستخدم المثال التالي الأمر az apic api definition import-specification لاستيراد تعريف API إلى واجهة برمجة تطبيقات موجودة في مركز myAPICenter API. هنا، يتم استيراد تعريف واجهة برمجة التطبيقات من عنوان URL مخزن في متغير $link .

يفترض هذا المثال أن لديك واجهة برمجة تطبيقات تسمى my-api وإصدار واجهة برمجة التطبيقات المقترن v1-0-0 وواجهة برمجة تطبيقات كيان التعريف في مركز واجهة برمجة التطبيقات الخاص بك. إذا لم تكن كذلك، فشاهد إضافة واجهات برمجة التطبيقات إلى مركز واجهة برمجة التطبيقات.

#! /bin/bash
az apic api definition import-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id my-api --version-id v1-0-0 \
    --definition-id openapi --format "link" --value '$link' \
    --specification '{"name":"openapi","version":"3.0.2"}'

# Formatted for PowerShell
az apic api definition import-specification `
    --resource-group myResourceGroup --service-name myAPICenter `
    --api-id my-api --version-id v1-0-0 `
    --definition-id openapi --format "link" --value '$link' `
    --specification '{"name":"openapi","version":"3.0.2"}'

الخيار 2: استيراد واجهات برمجة التطبيقات مباشرة من مثيل APIM

فيما يلي خطوات لاستيراد واجهات برمجة التطبيقات من مثيل APIM إلى مركز واجهة برمجة التطبيقات باستخدام الأمر az apic import-from-apim . يكون هذا الأمر مفيدا عندما تريد استيراد واجهات برمجة تطبيقات متعددة من إدارة واجهة برمجة التطبيقات إلى مركز واجهة برمجة التطبيقات الخاص بك. يمكنك أيضا استخدامه لاستيراد واجهة برمجة تطبيقات واحدة.

عند إضافة واجهات برمجة التطبيقات من مثيل APIM إلى مركز API الخاص بك باستخدام az apic import-from-apim، يحدث ما يلي تلقائيا:

• يتم نسخ إصدارات وتعريفات ومعلومات النشر الخاصة بكل واجهة برمجة تطبيقات إلى مركز API الخاص بك.
• تتلقى واجهة برمجة التطبيقات اسم واجهة برمجة تطبيقات تم إنشاؤه بواسطة النظام في مركز واجهة برمجة التطبيقات. يحتفظ باسم العرض الخاص به (العنوان) من APIM.
• يتم تعيين مرحلة دورة حياة واجهة برمجة التطبيقات إلى تصميم.
• تتم إضافة Azure API Management كبيئة.

إضافة هوية مدارة في مركز واجهة برمجة التطبيقات

بالنسبة لهذا السيناريو، يستخدم مركز API الخاص بك هوية مدارة للوصول إلى موارد Azure. بناء على احتياجاتك، قم بتمكين هوية مدارة معينة من قبل النظام أو هوية واحدة أو أكثر من الهويات المدارة المعينة من قبل المستخدم.

توضح الأمثلة التالية كيفية تمكين هوية مدارة معينة من قبل النظام باستخدام مدخل Azure أو Azure CLI. على مستوى عال، تتشابه خطوات التكوين مع الهوية المدارة المعينة من قبل المستخدم.

بوابة

1. في البوابة، اذهب إلى مركز واجهة برمجة التطبيقات الخاصة بك.
2. في قائمة الشريط الجانبي، تحت قسم الأمان، اختر الهويات المدارة.
3. حدد النظام المعين، ثم قم بتعيين الحالة إلى تشغيل.
4. حدد حفظ.

قم بتعيين الهوية المعينة من قبل النظام في مركز واجهة برمجة التطبيقات باستخدام الأمر التالي az apic update . استبدل أسماء مركز واجهة برمجة التطبيقات ومجموعة الموارد:

az apic update --name <api-center-name> --resource-group <resource-group-name> --identity '{"type": "SystemAssigned"}'

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

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

بوابة

1. في المدخل، انتقل إلى مثيل API Management.
2. على الجانب الأيسر، حدد التحكم بالوصول (IAM).
3. حدد + إضافة تعيين دور.
4. في صفحة إضافة تعيين دور، قم بتعيين القيم كما يلي:
   1. في علامة التبويب Role ، حدد API Management Service Reader.
   2. في علامة التبويب الأعضاء، في تعيين الوصول إلى - حدد الهوية> المدارة + تحديد الأعضاء.
   3. في صفحة تحديد الهويات المدارة ، حدد الهوية المدارة المعينة من قبل النظام لمركز API الذي أضفته في القسم السابق. انقر فوق تحديد.
   4. حدد مراجعة + تعيين.

1. احصل على المعرف الأساسي للهوية. للحصول على هوية معينة من قبل النظام، استخدم الأمر az apic show .

   #! /bin/bash
   apicObjID=$(az apic show --name <api-center-name> \
       --resource-group <resource-group-name> \
       --query "identity.principalId" --output tsv)
   

   # Formatted for PowerShell
   $apicObjID=$(az apic show --name <api-center-name> `
       --resource-group <resource-group-name> `
       --query "identity.principalId" --output tsv)
   

2. احصل على معرف المورد لمثيل APIM باستخدام الأمر az apim show .

   #! /bin/bash
   apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

   # Formatted for PowerShell
   $apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

3. قم بتعيين الهوية المدارة دور قارئ خدمة APIM في مثيل APIM باستخدام الأمر az role assignment create .

   #! /bin/bash
   scope="${apimID:1}"
   
   az role assignment create \
       --role "API Management Service Reader Role" \
       --assignee-object-id $apicObjID \
       --assignee-principal-type ServicePrincipal \
       --scope $scope 
   

   # Formatted for PowerShell
   $scope=$apimID.substring(1)
   
   az role assignment create `
       --role "API Management Service Reader Role" `
       --assignee-object-id $apicObjID `
       --assignee-principal-type ServicePrincipal `
       --scope $scope 
   

استيراد واجهات برمجة التطبيقات من APIM

استخدم الأمر az apic import-from-apim لاستيراد واحد أو أكثر من واجهات برمجة التطبيقات من مثيل APIM إلى مركز API الخاص بك.

إشعار

• يعتمد هذا الأمر على هوية مدارة تم تكوينها في مركز واجهة برمجة التطبيقات الذي لديه أذونات قراءة لمثيل APIM. إذا لم تقم بإضافة هوية مدارة أو تكوينها، فشاهد إضافة هوية مدارة في مركز واجهة برمجة التطبيقات في وقت سابق من هذه المقالة.

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

استيراد جميع واجهات برمجة التطبيقات من مثيل APIM

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

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis '*'  

# Formatted for PowerShell
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis '*'  

إشعار

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

استيراد واجهة برمجة تطبيقات معينة من مثيل APIM

حدد واجهة برمجة تطبيقات لاستيرادها باستخدام اسمها من مثيل APIM.

في الأمر التالي، استبدل أسماء مركز واجهة برمجة التطبيقات ومجموعة موارد مركز واجهة برمجة التطبيقات ومثيل APIM ومجموعة موارد المثيل الخاص بك. قم بتمرير اسم واجهة برمجة التطبيقات مثل petstore-api استخدام المعلمة --apim-apis .

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis 'petstore-api'        

# Formatted for PowerShell
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis 'petstore-api'    

إشعار

حدد اسم واجهة برمجة التطبيقات باستخدام اسم مورد واجهة برمجة التطبيقات في مثيل APIM، وليس اسم العرض. مثال: petstore-api بدلا من Petstore API.

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

المحتوى ذو الصلة

• مرجع Azure CLI ل Azure API Center
• مرجع Azure CLI لإدارة واجهة برمجة التطبيقات
• استخدام Azure CLI لإدارة مخزون واجهة برمجة التطبيقات
• تعيين أدوار Azure إلى هوية مدارة
• وثائق إدارة واجهات برمجة تطبيقات Azure