تمكين تحليل واجهة برمجة التطبيقات في مركز واجهة برمجة التطبيقات - المدار ذاتيا

مقالة
12/03/2024

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

إشعار

في المعاينة، يقوم Azure API Center تلقائيا بتكوين محرك تحليل افتراضي وتبعيات لتحليل واجهة برمجة التطبيقات. إذا قمت بتمكين التحليل المدار ذاتيا كما هو موضح في هذه المقالة، يمكنك تجاوز هذه الميزات المضمنة.

نظرة عامة على السيناريو

في هذا السيناريو، يمكنك تحليل تعريفات واجهة برمجة التطبيقات في مركز واجهة برمجة التطبيقات باستخدام محرك التحليل مصدر مفتوح الطيفي. يقوم تطبيق Azure Functions بتشغيل محرك التحليل استجابة للأحداث في مركز واجهة برمجة التطبيقات. يتحقق الطيف من أن واجهات برمجة التطبيقات المعرفة في مستند مواصفات JSON أو YAML تتوافق مع القواعد في دليل نمط واجهة برمجة التطبيقات القابل للتخصيص. يتم إنشاء تقرير تحليل يمكنك عرضه في مركز واجهة برمجة التطبيقات.

يوضح الرسم التخطيطي التالي الخطوات لتمكين التحليل والتحليل في مركز واجهة برمجة التطبيقات.

نشر تطبيق Azure Functions الذي يقوم بتشغيل محرك التحليل الطيفي على تعريف واجهة برمجة التطبيقات.
تكوين اشتراك حدث في مركز Azure API لتشغيل تطبيق الوظائف.
يتم تشغيل حدث عن طريق إضافة تعريف واجهة برمجة التطبيقات أو استبداله في مركز واجهة برمجة التطبيقات.
عند تلقي الحدث، يستدعي تطبيق الدالة محرك التحليل الطيفي.
يتحقق محرك التحليل من أن واجهات برمجة التطبيقات المحددة في التعريف تتوافق مع دليل نمط واجهة برمجة التطبيقات للمؤسسة وتنشئ تقريرا.
عرض تقرير التحليل في مركز واجهة برمجة التطبيقات.

خيارات لنشر محرك التحليل والاشتراك في الحدث

توفر هذه المقالة خيارين لنشر محرك التحليل والاشتراك في الحدث في مركز API الخاص بك:

النشر التلقائي - استخدم Azure developer CLI (azd) لنشر البنية الأساسية للlinting على خطوة واحدة. يوصى بهذا الخيار لعملية نشر مبسطة.
النشر اليدوي - اتبع الإرشادات خطوة بخطوة لنشر تطبيق Azure Functions وتكوين اشتراك الحدث. يوصى بهذا الخيار إذا كنت تفضل نشر الموارد وإدارتها يدويا.

القيود

يدعم Linting حاليا ملفات مواصفات JSON أو YAML فقط، مثل مستندات مواصفات OpenAPI أو AsyncAPI.
بشكل افتراضي، يستخدم محرك التحليل مجموعة القواعد المضمنة.spectral:oas لتوسيع مجموعة القواعد أو إنشاء إرشادات نمط واجهة برمجة التطبيقات المخصصة، راجع مستودع GitHub الطيفي.
يتم فرض رسوم على تطبيق وظائف Azure الذي يستدعي التحليل بشكل منفصل، ويمكنك إدارته وصيانته.

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

مركز API في اشتراك Azure الخاص بك. إذا لم تكن قد أنشأت واحدا بالفعل، فشاهد التشغيل السريع: إنشاء مركز واجهة برمجة التطبيقات.
موفر موارد Event Grid المسجل في اشتراكك. إذا كنت بحاجة إلى تسجيل موفر موارد Event Grid، فشاهد الاشتراك في الأحداث التي نشرها شريك مع Azure Event Grid.
بالنسبة إلى 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.
إشعار

az apic تتطلب apic-extension الأوامر ملحق Azure CLI. إذا لم تكن قد استخدمت az apic الأوامر، يمكن تثبيت الملحق ديناميكيا عند تشغيل الأمر الأول az apic ، أو يمكنك تثبيت الملحق يدويا. تعرف على المزيد حول ملحقات Azure CLI.

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

إشعار

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

`azd` نشر تطبيق Azure Functions والاشتراك في الحدث

يوفر هذا القسم خطوات تلقائية باستخدام Azure Developer CLI لتكوين تطبيق Azure Functions واشتراك الحدث الذي يمكن التحليل والتحليل في مركز واجهة برمجة التطبيقات. يمكنك أيضا تكوين الموارد يدويا.

المتطلبات الأساسية الأخرى لهذا الخيار

Azure Developer CLI (azd)

تشغيل العينة باستخدام `azd`

استنساخ مستودع GitHub وفتحه في Visual Studio Code.
تغيير الدليل إلى APICenter-Analyzer المجلد في المستودع.
في resources/rulesets المجلد، يمكنك العثور على oas.yaml ملف. يعكس هذا الملف دليل نمط واجهة برمجة التطبيقات الحالي ويمكن تعديله استنادا إلى احتياجاتك ومتطلباتك التنظيمية.
المصادقة باستخدام Azure Developer CLI وAzure CLI باستخدام الأوامر التالية:
```
azd auth login

az login
```
قم بتشغيل الأمر التالي لنشر البنية الأساسية للlinting إلى اشتراك Azure الخاص بك.
```
azd up
```
اتبع المطالبات لتوفير معلومات النشر والإعدادات المطلوبة، مثل اسم البيئة واسم مركز واجهة برمجة التطبيقات. للحصول على التفاصيل، راجع تشغيل العينة باستخدام Azure Developer CLI (azd).

إشعار

قد يستغرق انتهاء الإعداد بضع دقائق.
بعد اكتمال النشر، انتقل إلى مركز واجهة برمجة التطبيقات في مدخل Microsoft Azure. في القائمة اليسرى، حدد Events>Event subscriptions لعرض اشتراك الحدث الذي تم إنشاؤه.

يمكنك الآن تحميل ملف تعريف واجهة برمجة التطبيقات إلى مركز واجهة برمجة التطبيقات لتشغيل اشتراك الحدث وتشغيل محرك التحليل.

الخطوات اليدوية لتكوين تطبيق Azure Functions والاشتراك في الحدث

يوفر هذا القسم خطوات النشر اليدوي لتكوين تطبيق Azure Functions والاشتراك في الحدث لتمكين التحليل والتحليل في مركز واجهة برمجة التطبيقات. يمكنك أيضا استخدام Azure Developer CLI للتوزيع التلقائي.

المتطلبات الأساسية الأخرى لهذا الخيار

Visual Studio Code مع ملحق Azure Functions v1.10.4 أو أحدث.

الخطوة 1. نشر تطبيق Azure Functions

لنشر تطبيق Azure Functions الذي يقوم بتشغيل دالة التحليل على تعريفات واجهة برمجة التطبيقات:

استنساخ مستودع GitHub وفتحه في Visual Studio Code.
في resources/rulesets المجلد، يمكنك العثور على oas.yaml ملف. يعكس هذا الملف دليل نمط واجهة برمجة التطبيقات الحالي ويمكن تعديله استنادا إلى احتياجاتك ومتطلباتك التنظيمية.
اختياريا، قم بتشغيل تطبيق الوظائف محليا لاختباره. للحصول على التفاصيل، راجع ملف README في المستودع.
نشر تطبيق الدالة إلى Azure. للحصول على خطوات، راجع التشغيل السريع: إنشاء دالة في Azure باستخدام TypeScript باستخدام Visual Studio Code.

إشعار

قد يستغرق نشر تطبيق الوظائف بضع دقائق.
سجل الدخول إلى مدخل Microsoft Azure، وانتقل إلى تطبيق الوظائف.
في صفحة نظرة عامة ، تحقق من التفاصيل التالية:
- تأكد من أن حالة تطبيق الوظائف قيد التشغيل.
- ضمن Functions، تأكد من تمكين حالة دالة apicenter-analyzer.

الخطوة 2. تكوين الهوية المدارة في تطبيق الوظائف

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

بوابة
Azure CLI

في مدخل Microsoft Azure، انتقل إلى تطبيق الوظائف وحدد الهوية ضمن قسم الإعدادات .
في علامة التبويب تعيين النظام، قم بتعيين الحالة إلى تشغيل ثم حدد حفظ.

الآن بعد تمكين الهوية المدارة، قم بتعيين دور Azure API Center Compliance Manager للوصول إلى مركز API.

في مدخل Microsoft Azure، انتقل إلى مركز API وحدد Access control (IAM).
حدد + إضافة > تعيين دور.
حدد Job function roles ثم حدد Azure API Center Compliance Manager. حدد التالي.
في صفحة الأعضاء ، في تعيين الوصول إلى، حدد الهوية > المدارة + تحديد الأعضاء.
في صفحة تحديد الهويات المدارة ، ابحث عن الهوية المدارة لتطبيق الوظائف وحددها. انقر فوق تحديد ثم التالي.
راجع تعيين الدور، وحدد Review + assign.

قم بتمكين الهوية المعينة من قبل النظام لتطبيق الوظائف باستخدام الأمر az functionapp identity assign . استبدل <function-app-name> و <resource-group-name> باسم تطبيق الوظائف واسم مجموعة الموارد. يخزن الأمر التالي المعرف الأساسي للهوية المدارة المعينة من قبل النظام في principalID المتغير .
```
#! /bin/bash
principalID=$(az functionapp identity assign --name <function-app-name> \
    --resource-group <resource-group-name> --identities [system] \
    --query "principalId" --output tsv)
```
```
# PowerShell syntax
$principalID=$(az functionapp identity assign --name <function-app-name> `
    --resource-group <resource-group-name> --identities [system] `
    --query "principalId" --output tsv)
```

احصل على معرف المورد لمركز API الخاص بك. استبدل <apic-name> و <resource-group-name> باسم مركز واجهة برمجة التطبيقات واسم مجموعة الموارد.

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

# PowerShell syntax
$apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> `
    --query "id" --output tsv)

تعيين الهوية المدارة لتطبيق الوظيفة دور Azure API Center Compliance Manager في مركز API باستخدام الأمر az role assignment create .

#! /bin/bash
az role assignment create \
    --role "Azure API Center Compliance Manager" \
    --assignee-object-id $principalID \
    --assignee-principal-type ServicePrincipal \
    --scope $apicID

# PowerShell syntax
az role assignment create `
    --role "Azure API Center Compliance Manager" `
    --assignee-object-id $principalID `
    --assignee-principal-type ServicePrincipal `
    --scope $apicID

الخطوة 3. تكوين اشتراك الحدث في مركز واجهة برمجة التطبيقات

الآن قم بإنشاء اشتراك حدث في مركز واجهة برمجة التطبيقات لتشغيل تطبيق الوظائف عند تحميل ملف تعريف واجهة برمجة التطبيقات أو تحديثه. توضح الخطوات التالية كيفية إنشاء اشتراك الحدث باستخدام مدخل Azure أو Azure CLI.

بوابة
Azure CLI

في مدخل Microsoft Azure، انتقل إلى مركز واجهة برمجة التطبيقات وحدد الأحداث.
في علامة التبويب Get started ، حدد Azure Function.
في صفحة إنشاء اشتراك حدث، قم بما يلي:
1. أدخل اسما وصفيا لاشتراك الحدث، وحدد مخطط شبكة الأحداث.
2. في تفاصيل الموضوع، أدخل اسم موضوع النظام الذي تختاره.
3. في أنواع الأحداث، حدد الأحداث التالية:
  - تمت إضافة تعريف واجهة برمجة التطبيقات
  - تم تحديث تعريف واجهة برمجة التطبيقات
4. في تفاصيل نقطة النهاية، حدد Azure Function > Configure an endpoint.
5. في صفحة Select Azure Function ، حدد تطبيق الدالة ودالة apicenter-linter التي قمت بتكوينها. انقر فوق تأكيد التحديد.
6. حدد إنشاء.
حدد علامة التبويب Event subscriptions وحدد Refresh. تأكد من نجاح حالة التوفير لاشتراك الحدث.

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

# PowerShell syntax
$apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> `
    --query "id" --output tsv)

احصل على معرف المورد للدالة في تطبيق الوظائف. في هذا المثال، اسم الدالة هو apicenter-analyzer. استبدل <function-app-name> و <resource-group-name> باسم تطبيق الوظائف واسم مجموعة الموارد.

#! /bin/bash
functionID=$(az functionapp function show --name <function-app-name> \
    --function-name apicenter-analyzer --resource-group <resource-group-name> \
    --query "id" --output tsv)

# PowerShell syntax
$functionID=$(az functionapp function show --name <function-app-name> `
    --function-name apicenter-analyzer --resource-group <resource-group-name> `
    --query "id" --output tsv)

إنشاء اشتراك حدث باستخدام الأمر az eventgrid event-subscription create . يتضمن الاشتراك الذي تم إنشاؤه أحداثا لإضافة تعريفات واجهة برمجة التطبيقات أو تحديثها.

#! /bin/bash
az eventgrid event-subscription create --name MyEventSubscription \
    --source-resource-id "$apicID" --endpoint "$functionID" \
    --endpoint-type azurefunction --included-event-types \
    Microsoft.ApiCenter.ApiDefinitionAdded Microsoft.ApiCenter.ApiDefinitionUpdated

# PowerShell syntax
az eventgrid event-subscription create --name MyEventSubscription `
    --source-resource-id "$apicID" --endpoint "$functionID" `
    --endpoint-type azurefunction --included-event-types `
    Microsoft.ApiCenter.ApiDefinitionAdded Microsoft.ApiCenter.ApiDefinitionUpdated

يعرض إخراج الأمر تفاصيل اشتراك الحدث. يمكنك أيضا الحصول على التفاصيل باستخدام الأمر az eventgrid event-subscription show . على سبيل المثال:

az eventgrid event-subscription show --name MyEventSubscription --source-resource-id "$apicID"

إشعار

قد يستغرق نشر اشتراك الحدث إلى تطبيق الوظائف وقتا قصيرا.

تشغيل الحدث في مركز واجهة برمجة التطبيقات

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

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

للتأكد من تشغيل اشتراك الحدث:

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

إشعار

قد يستغرق ظهور المقاييس بضع دقائق.

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

عرض تقارير تحليل واجهة برمجة التطبيقات

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

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

تقرير تحليل لتعريف واجهة برمجة التطبيقات

لعرض تقرير التحليل لتعريف واجهة برمجة التطبيقات في مركز واجهة برمجة التطبيقات:

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

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

ملخص تحليل واجهة برمجة التطبيقات

لعرض ملخص لتقارير التحليل لجميع تعريفات واجهة برمجة التطبيقات في مركز واجهة برمجة التطبيقات:

في المدخل، انتقل إلى مركز API الخاص بك.
في القائمة اليسرى، ضمن Governance، حدد API Analysis. يظهر الملخص.

تعرف على المزيد حول Event Grid:

مشاركة عبر

تمكين تحليل واجهة برمجة التطبيقات في مركز واجهة برمجة التطبيقات - المدار ذاتيا

نظرة عامة على السيناريو

خيارات لنشر محرك التحليل والاشتراك في الحدث

القيود

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

`azd` نشر تطبيق Azure Functions والاشتراك في الحدث

المتطلبات الأساسية الأخرى لهذا الخيار

تشغيل العينة باستخدام `azd`

الخطوات اليدوية لتكوين تطبيق Azure Functions والاشتراك في الحدث

المتطلبات الأساسية الأخرى لهذا الخيار

الخطوة 1. نشر تطبيق Azure Functions

الخطوة 2. تكوين الهوية المدارة في تطبيق الوظائف

الخطوة 3. تكوين اشتراك الحدث في مركز واجهة برمجة التطبيقات

تشغيل الحدث في مركز واجهة برمجة التطبيقات

عرض تقارير تحليل واجهة برمجة التطبيقات

تقرير تحليل لتعريف واجهة برمجة التطبيقات

ملخص تحليل واجهة برمجة التطبيقات

الملاحظات

الموارد الإضافية

مشاركة عبر

تمكين تحليل واجهة برمجة التطبيقات في مركز واجهة برمجة التطبيقات - المدار ذاتيا

نظرة عامة على السيناريو

خيارات لنشر محرك التحليل والاشتراك في الحدث

القيود

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

azd نشر تطبيق Azure Functions والاشتراك في الحدث

المتطلبات الأساسية الأخرى لهذا الخيار

تشغيل العينة باستخدام azd

الخطوات اليدوية لتكوين تطبيق Azure Functions والاشتراك في الحدث

المتطلبات الأساسية الأخرى لهذا الخيار

الخطوة 1. نشر تطبيق Azure Functions

الخطوة 2. تكوين الهوية المدارة في تطبيق الوظائف

الخطوة 3. تكوين اشتراك الحدث في مركز واجهة برمجة التطبيقات

تشغيل الحدث في مركز واجهة برمجة التطبيقات

عرض تقارير تحليل واجهة برمجة التطبيقات

تقرير تحليل لتعريف واجهة برمجة التطبيقات

ملخص تحليل واجهة برمجة التطبيقات

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

الملاحظات

الموارد الإضافية

`azd` نشر تطبيق Azure Functions والاشتراك في الحدث

تشغيل العينة باستخدام `azd`