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

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

تدعم الإجراءات التالية النشر التلقائي لمحرك الواش والاشتراك في الحدث في مركز واجهة برمجة التطبيقات الخاصة بك. استخدم واجهة المطور Azure (azd) لنشر بنية تحتية للوبر على خطوة واحدة لعملية نشر مبسطة. يمكن تشغيل أمثلة أوامر Azure CLI في PowerShell أو bash shell. يتم توفير أمثلة أوامر منفصلة حسب الحاجة.

إذا كنت تفضل إعداد المحرك والموارد عبر manual deployment، راجع مستودع مركز API Analyzer GitHub Azure للحصول على إرشادات لنشر تطبيق الدالة وتكوين اشتراك الحدث.

إشعار

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

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

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

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

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

القيود

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

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

مركز API في اشتراكك في Azure. لإنشاء اشتراك، راجع البدء السريع: إنشاء مركز واجهة برمجة التطبيقات الخاصة بك.
موفر موارد Event Grid المسجل في اشتراكك. إذا كنت بحاجة إلى تسجيل مزود موارد شبكة الفعاليات، راجع الاشتراك في الأحداث التي ينشرها شريك في Azure Event Grid.
Azure المطور CLI (azd). قم بتثبيته azd على جهازك في البيئة التي تخطط لاستخدامها في العملية التالية.
Azure Functions أدوات النواة. قم بتثبيت الأدوات الأساسية على جهازك في البيئة التي تخطط لاستخدامها للإجراء التالي. تأكد من أن الأدوات متاحة حسب إعداداتك PATH .
For Azure CLI:
- استخدم بيئة باش في Azure Cloud Shell. لمزيد من المعلومات، راجع Get started مع Azure Cloud Shell.
- إذا كنت تفضل تشغيل أوامر مرجعية لواجهة الواجهة محليا، install Azure CLI. إذا كنت تعمل على ويندوز أو macOS، فكر في تشغيل Azure CLI في حاوية Docker. لمزيد من المعلومات، راجع كيفية تشغيل Azure CLI في حاوية Docker.
  - إذا كنت تستخدم تثبيتا محليا، سجل الدخول إلى Azure CLI باستخدام أمر az login. لإنهاء عملية المصادقة، اتبع الخطوات المعروضة في جهازك. لخيارات تسجيل الدخول الأخرى، راجع المصادقة إلى Azure باستخدام Azure CLI.
  - عندما يطلب منك ذلك، قم بتثبيت إضافة Azure CLI عند الاستخدام الأول. لمزيد من المعلومات حول الإضافات، راجع استخدم وإدارة الإضافات باستخدام Azure CLI.
  - شغل az version للعثور على الإصدار والمكتبات التابعة التي تم تثبيتها. للترقية إلى أحدث إصدار، شغل az upgrade.
إشعار

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

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

استخدم نشر azd لتطبيق الوظائف واشتراك الأحداث

توفر الإجراءات التالية خطوات آلية لواجهة برمجة التطبيقات (azd) من Azure لتكوين تطبيق الوظائف واشتراك الأحداث التي تتيح الإضاءة والتحليل في مركز واجهة برمجة التطبيقات الخاصة بك.

إشعار

إذا كنت تفضل إعداد المحرك والموارد باستخدام manual deployment، راجع مستودع مركز API Azure لتحليل الوظائف GitHub للحصول على إرشادات لنشر تطبيق الوظائف وتكوين اشتراك الحدث.

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

قم باستنساخ المستودع Azure API Center Analyzer GitHub إلى جهازك المحلي.
اطلق Visual Studio Code، واختر File>Open Folder (Ctrl+K, Ctrl+O). تصفح المجلد APICenter-Analyzer الخاص بالمستودع المستنسخ واختر مجلد الاختيار.
في رمز Visual Studio Activity Bar، اختر Explorer (Ctrl+Shift+E) حتى تتمكن من عرض هيكل المجلد الخاص بالمستودع.
- قم بتوسيع المجلد resources/rulesets ولاحظ الملف oas.yaml . هذا الملف يعكس دليل أنماط واجهة برمجة التطبيقات الحالي الخاص بك. يمكنك تعديل هذا الملف ليلبي احتياجاتك التنظيمية.
- قم بتوسيع المجلد src/functions ولاحظ الملف ApiAnalyzerFunction.ts . يوفر هذا الملف رمز الدالة لتطبيق الدالة. يمكنك تعديل هذا الملف لضبط سلوك الدالة ليتوافق مع متطلبات تطبيقك.
افتح طرفية في Visual Studio Code وتحقق من المصادقة باستخدام واجهة المطور Azure (azd):
```
azd auth login
```
نصيحة

يمكنك تجنب مشاكل المصادقة عبر بيئات التطوير من خلال تشغيل الأوامر التالية:
1. إنشاء بيئة تطوير جديدة: azd env new
2. احصل على معرف المستأجر الخاص بك: az account show --query tenantId -o tsv (انسخ معرف الإخراج لاحقا)
3. تسجيل الخروج: azd auth logout أمر
4. سجل الدخول azd بقيمتك tenantId من الخطوة 2: azd auth login --tenant-id <tenant_ID>
عندما تنجح في المصادقة، يظهر مخرج الأمر أنك مسجل الدخول إلى Azure ك <your_user_alias>.
بعد ذلك، قم بتسجيل الدخول إلى Azure portal باستخدام Azure CLI:
```
az login
```
يطلب منك إدخال بيانات الدخول الخاصة بك لتسجيل الدخول إلى Azure.

نافذة المتصفح تؤكد تسجيل دخولك الناجح. أغلق النافذة وارجع إلى هذا الإجراء.
شغل الأمر التالي لنشر بنية الوبر التحتية على اشتراكك في Azure.

لهذا الأمر، تحتاج إلى المعلومات التالية. معظم هذه القيم متاحة في صفحة نظرة عامة لمورد مركز واجهة برمجة التطبيقات في Azure portal.
- اسم الاشتراك ومعرف
- اسم مركز API
- اسم مجموعة الموارد لمركز واجهة برمجة التطبيقات
- منطقة النشر لتطبيق الوظائف (قد تختلف عن منطقة مركز واجهة برمجة التطبيقات الخاصة بك)
```
azd up
```

اتبع التعليمات لتوفير معلومات النشر والإعدادات المطلوبة. لمزيد من المعلومات، راجع تشغيل العينة باستخدام Azure Developer CLI (azd).

مع تقدم النشر، يظهر الناتج مهام التوفير المكتملة:

إشعار

قد يستغرق إعداد تطبيق الوظائف ونشره على Azure عدة دقائق.

Packaging services (azd package)

(✓) Done: Packaging service function
- Build Output: C:\GitHub\APICenter-Analyzer
- Package Output: C:\Users\<user>\AppData\Local\Temp\api-center-analyzer-function-azddeploy-0123456789.zip

Loading azd .env file from current environment

Provisioning Azure resources (azd provision)
Provisioning Azure resources can take some time.

Subscription: <your_selected_subscription>
Location: <your_selected_region_for_this_process>

You can view detailed progress in the Azure Portal:

https://portal.azure.com/#view/HubsExtension/DeploymentDetailsBlade/~/overview/id/%2Fsubscriptions%2F00001111-a2a2-b3b3-c4c4-dddddd555555%2Fproviders%2FMicrosoft.Resources%2Fdeployments%2F<your_azd_environment_name-0123456789>

(✓) Done: Resource group: <new_resource_group_for_function_app> (5.494s)
(✓) Done: App Service plan: <new_app_service_plan> (5.414s)
(✓) Done: Storage account: <new_storage_account> (25.918s)
(✓) Done: Log Analytics workspace: <new_workspace> (25.25s)
(✓) Done: Application Insights: <new_application_insights> (5.628s)
(✓) Done: Portal dashboard: <new_dashboard> (1.63s)
(✓) Done: Function App: <new_function_app> (39.402s)

يتضمن المخرج رابطا لمراقبة تقدم النشر في Azure portal.

بعد اكتمال التجهيز، تقوم العملية بنشر تطبيق الوظائف الجديد على Azure portal:

Deploying services (azd deploy)

(✓) Done: Deploying service function
- Endpoint: https://<new_function_app>.azurewebsites.net/

Configuring EventGrid subscription for API Center

Examples from AI knowledge base

عند اكتمال النشر، تأكد من وجود تطبيق الوظيفة الجديدة ونشر الدالة.

إذا لم تكن دالة apicenter-analyer مدرجة أو لم تكن دالة StatusEnabled، نشر الدالة باستخدام أدوات Azure Functions الأساسية.
تكوين اشتراك حدث باستخدام PowerShell أو bash shell في Visual Studio Code.

Confirm function published in Azure portal

عند اكتمال النشر، تأكد من وجود تطبيق الوظيفة الجديدة في Azure portal ويتم نشر الدالة.

سجل الدخول إلى Azure portal، وتصفح إلى قسم Function App، واختر تطبيق الوظيفة الجديدة في القائمة.
في صفحة النظرة العامة لتطبيق الوظيفة الجديد، تأكد من أن تطبيق الوظيفة حالة الوظيفة.
في قسم الوظائف ، تأكد من أن الدالة apicenter-analyer مدرجة وأن الحالةمفعلة.

Publish apicenter-analyzer function with Azure Functions Core Tools

إذا لم تنشر عملية النشر دالة apicenter-analyer إلى تطبيق الدالة في Azure portal، يمكنك تشغيل الأوامر التالية في محطة كود Visual Studio وإكمال العملية.

شغل الأمر التالي للتأكد من أن الوظيفة لم تنشر في تطبيق الدالة:

إشعار

يستخدم هذا الأمر مجموعة الموارد الجديدة التي أنشأتها عملية النشر لتطبيق الدالة وليس مجموعة الموارد لمركز واجهة برمجة التطبيقات الخاصة بك. استبدل <function-app-name> وبذلك <new_resource_group_for_function_app> باسم تطبيق الوظيفة واسم مجموعة الموارد الخاصة بتطبيق الدالة.
```
az functionapp function list --name <function_app_name> --resource-group <new_resource_group_for_function_app> --query "[].name" -o tsv
```
يجب أن يكون مخرج الأمر فارغا.
في Explorer، قم بتوسيع المجلد src/functions وافتح ApiAnalyzerFunction.ts الملف. هذا الإجراء يؤكد أن البيئة مضبوطة للبحث عن المحتوى في الموقع الصحيح.
تأكد من أن بيئتك تتضمن npm package manager وبيئة node runtime، وقم بتثبيت أي أدوات حسب الحاجة:
```
node --version
npm --version
```
عند الحاجة، قم بتثبيت أدوات Azure Functions Code Tools في البيئة:
```
npm install -g azure-functions-core-tools@4 --unsafe-perm true
```

شغل الأمر التالي لنشر كود الدالة في تطبيق الدالة في Azure portal. استبدل <function-app-name> باسم تطبيق الوظائف.

func azure functionapp publish <function_app_name> --typescript

يعرض الأمر الناتج التالي:

Getting site publishing info...
[2026-02-26T19:58:38.779Z] Starting the function app deployment...
Uploading package...
Uploading 33.8 MB [###############################################################################]
Upload completed successfully.
Deployment completed successfully.
apicenter-analyzer - [eventGridTrigger]

في Azure portal، تأكد من أن دالة apicenter-analyzer الآن published ومفعلة لخاصتك app.

تكوين اشتراك الأحداث

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

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

#! /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-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 --name MyEventSubscription --source-resource-id "$apicID"

إشعار

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

تصفح إلى مركز واجهة برمجة التطبيقات الخاصة بك في Azure portal، وأكد اشتراك الحدث الجديد تحت Events>Event Subscriptions.

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

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

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

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

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

إشعار

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

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

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

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

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

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

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

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

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

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

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

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

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2026-03-11

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

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

القيود

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

استخدم نشر azd لتطبيق الوظائف واشتراك الأحداث

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

Confirm function published in Azure portal

Publish apicenter-analyzer function with Azure Functions Core Tools

تكوين اشتراك الأحداث

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

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

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

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

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

الملاحظات

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