استيراد مواصفة OpenAPI

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

توضح هذه المقالة كيفية استيراد واجهة برمجة تطبيقات خلفية لمواصفة OpenAPI إلى Azure API Management باستخدام أدوات متنوعة. توضح المقالة أيضاً كيفية اختبار واجهة برمجة التطبيقات في APIM. للحصول على معلومات حول دعم إصدار OpenAPI، راجع قيود استيراد API والمشاكل المعروفة.

في هذه المقالة، ستتعرف على كيفية:

• استيراد مواصفات OpenAPI باستخدام مدخل Azure أو Azure CLI أو Azure PowerShell
• حدد التطبيق في مدخل Microsoft Azure

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

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

• 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.

• Azure PowerShell

  • إذا اخترت استخدام Azure PowerShell محليا:
    • تثبيت أحدث إصدار من الوحدة النمطية Az PowerShell.
    • اتصل بحساب Azure الخاص بك باستخدامConnect-AzAccount cmdlet.
  • إذا اخترت استخدام Azure Cloud Shell:
    • لمزيد من المعلومات، راجع نظرة عامة على Azure Cloud Shell.

استيراد واجهة برمجة تطبيقات خلفية

في هذا المثال، تقوم باستيراد مواصفة OpenAPIلواجهة برمجة التطبيقات Petstore مفتوحة المصدر. يمكنك استبدال مواصفة OpenAPI التي تختارها.

بوابة

1. في مدخل Azure، انتقل إلى مثيل API Management الخاص بك.

2. في القائمة اليسرى، حدد APIs>+ Add API.

3. ضمن Create from definition، حدد OpenAPI.

   

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

5. حدد إنشاء.

يستخدم المثال التالي الأمر az apim api import لاستيراد مواصفات OpenAPI من عنوان URL المحدد إلى مثيل APIM المسمى apim-hello-world. للاستيراد باستخدام مسار إلى مواصفات بدلا من عنوان URL، استخدم المعلمة --specification-path .

# API Management service-specific details
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details
APIId="swagger-petstore"
APIPath="store"
SpecificationFormat="OpenAPI"
SpecificationURL="https://petstore3.swagger.io/api/v3/openapi.json"

# Import API
az apim api import --path $APIPath --resource-group $ResourceGroupName \
    --service-name $APIMServiceName --api-id $APIId \
    --specification-format $SpecificationFormat --specification-url $SpecificationURL

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

بوويرشيل

يستخدم المثال التالي Import-AzApiManagementApi Azure PowerShell cmdlet لاستيراد مواصفات OpenAPI من عنوان URL المحدد إلى مثيل APIM المسمى apim-hello-world. للاستيراد باستخدام مسار إلى مواصفات بدلا من عنوان URL، استخدم المعلمة -SpecificationPath .

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific details
$apiId = "swagger-petstore"
$apiPath = "store"
$specificationFormat = "OpenAPI"
$specificationUrl = "https://petstore3.swagger.io/api/v3/openapi.json"

# Get context of the API Management instance. 
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName

# Import API
Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath

بعد استيراد واجهة برمجة التطبيقات، يمكنك تحديث الإعدادات باستخدام ملف Set-AzApiManagementApi .

عرض مواصفات OpenAPI وتحريرها

في بوابة Azure، استخدم محرر مواصفات OpenAPI لعرض أو التحقق أو تعديل المواصفات الخاصة بواجهة البرمجة التي قمت باسيرادها.

لاستخدام محرر مواصفات OpenAPI:

1. في مدخل Azure، انتقل إلى مثيل API Management.
2. في القائمة اليسرى، ضمن ><
3. في علامة التبويب تصميم ، في الواجهة الأمامية، حدد محرر مواصفات OpenAPI (أيقونة القلم الرصاص). يمكنك فتح المواصفات بتنسيق JSON أو YAML.
4. مراجعة المواصفات أو تحريرها حسب الحاجة. احفظ تغييراتك.

التحقق من الصحة مقابل مخطط مواصفات OpenAPI

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

اختبر واجهة برمجة التطبيقات الجديدة في المدخل

يمكنك استدعاء العمليات مباشرة من بوابة Azure، التي توفر طريقة مريحة لعرض واختبار عمليات واجهة برمجة التطبيقات.

1. تحديد واجهة برمجة التطبيقات التي أنشأتها في الخطوة السابقة.

2. حدد علامة التبويب الاختبار.

3. حدد عملية.

   تعرض الصفحة الحقول لمعلمات الاستعلام وحقول الرؤوس.

   إشعار

   في وحدة تحكم الاختبار، تقوم APIM تلقائيا بتعبئة عنوان Ocp-Apim-Subscription-Key، وتكوين مفتاح الاشتراك للاشتراك المضمن في الوصول بالكامل. يتيح هذا المفتاح الوصول إلى كل واجهة برمجة تطبيقات في مثيل APIM. عرض رأس Ocp-Apim-Subscription-Key اختياريا عن طريق تحديد أيقونة "العين" بجوار طلب HTTP.

4. اعتمادا على العملية، أدخل قيم معلمات الاستعلام أو قيم الرأس أو نص الطلب. حدد إرسال.

   عند نجاح الاختبار، تستجيب الخلفية برمز استجابة HTTP ناجح وبعض البيانات.

   تلميح

   بشكل افتراضي، ترسل وحدة التحكم في الاختبار طلبا إلى وكيل CORS الخاص بإدارة واجهة برمجة التطبيقات، والذي يعيد توجيه الطلب إلى مثيل APIM، والذي يعيد توجيهه بعد ذلك إلى الخلفية. يستخدم هذا الوكيل عنوان IP العام 13.91.254.72 ويمكنه الوصول إلى نقاط النهاية العامة فقط.

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

لتصحيح أخطاء واجهة برمجة التطبيقات، راجع البرنامج التعليمي: تصحيح واجهات برمجة التطبيقات باستخدام تتبع الطلب.

إلحاق واجهات برمجة تطبيقات أخرى

يمكنك إنشاء واجهة برمجة تطبيقات من واجهات برمجة التطبيقات التي يتم كشفها بواسطة خدمات مختلفة، بما في ذلك:

• مواصفات OpenAPI
• واجهة برمجة تطبيقات SOAP
• واجهة برمجة تطبيقات GraphQL
• تطبيق ويب مستضاف في Azure App Service
• دالات Azure
• تطبيقات Azure Logic
• نسيج خدمة Azure

إشعار

عند استيراد واجهة برمجة تطبيقات، يتم إلحاق العمليات بواجهة برمجة التطبيقات الحالية.

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

1. انتقل إلى مثيل Azure API Management في مدخل Microsoft Azure:

   

2. اختر واجهات برمجة التطبيقات في صفحة النظرة العامة، أو اخترواجهات برمجةالتطبيقات> في قائمة الشريط الجانبي.

   

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

4. اختر الاستيراد من قائمة السياق:

   

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

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

• قيود استيراد API
• استيراد مواصفة OpenAPI
• استيراد واجهة برمجة تطبيقات SOAP
• استيراد واجهة برمجة تطبيقات SOAP وتحويلها إلى REST
• استيراد واجهة برمجة تطبيقات App Service
• استيراد واجهة برمجة تطبيقات تطبيق حاوية
• استيراد واجهة برمجة تطبيقات WebSocket
• استيراد واجهة برمجة تطبيقات GraphQL
• استيراد مخطط GraphQL وإعداد محللات الحقول
• استيراد واجهة برمجة تطبيقات تطبيق دالة
• استيراد واجهة برمجة تطبيقات تطبيق منطقي
• استيراد خدمة Service Fabric
• استيراد واجهة برمجة تطبيقات Microsoft Foundry
• استيراد واجهة برمجة تطبيقات Azure OpenAI
• استيراد واجهة برمجة تطبيقات LLM
• استيراد واجهة برمجة تطبيقات OData
• تصدير واجهة برمجة تطبيقات REST كخادم MCP
• كشف خادم MCP موجود
• استيراد واجهة برمجة تطبيقات وكيل A2A
• استيراد بيانات التعريف لـ SAP OData
• استيراد واجهة برمجة تطبيقات gRPC
• تحرير واجهة برمجة تطبيقات