Включение анализа API в центре API — самостоятельное управление

В этой статье объясняется, как включить анализ API в Azure API Center для настройки средства линтинга и триггеров. Эти возможности анализируют определения API для соблюдения правил стиля организации, создавая как отдельные, так и сводные отчеты. Анализ API помогает выявлять и исправлять распространенные ошибки и несоответствия в определениях API.

Следующие процедуры поддерживают автоматическое развертывание линтингового механизма и подписки на события в вашем центре API. Используйте Azure Developer CLI (azd) для одношагового развертывания инфраструктуры проверки кода для упрощенного процесса развертывания. Примеры команд Azure CLI могут выполняться в PowerShell или оболочке bash. По мере необходимости предоставляются отдельные примеры команд.

Если вы предпочитаете настроить движок и ресурсы вручную, ознакомьтесь с репозиторием GitHub Azure API Center Analyzer, чтобы развернуть приложение-функцию и настроить подписки на события.

Примечание.

Центр API Azure также автоматически настраивает средство проверки стиля и зависимости по умолчанию для анализа API. Если включить самоуправляемый анализ, как описано в этой статье, вы переопределяете эти встроенные функции.

Обзор сценария

В этом сценарии вы анализируете определения API в центре API с помощью инструмента Spectral с открытым исходным кодом. Приложение-функция, созданное с помощью Azure Functions, запускает линтинг-движок в ответ на события в вашем центре API. Spectral проверяет, соответствуют ли API, определенные в документе спецификации JSON или YAML, правилам в настраиваемом руководстве по стилю API. Создается отчет анализа, который можно просмотреть в центре API.

На следующей схеме показаны шаги по включению линтинга и анализа в вашем центре API.

1. Разверните функциональное приложение, которое запускает инструмент анализа кода Spectral в определении API.

2. Настройте подписку на события в центре API Azure, который активирует приложение-функцию.

3. Событие активируется путем добавления или замены определения API в центре API.

4. При получении события функциональное приложение вызывает линтинговый движок Spectral.

5. Инструмент линтинга проверяет, соответствуют ли API, указанные в спецификации, руководству по стилю API организации и создает отчет.

6. Просмотрите отчет по анализу в центре API.

Ограничения

• Linting в настоящее время поддерживает только файлы спецификации JSON или YAML, такие как документы спецификации OpenAPI или AsyncAPI.

• По умолчанию линтинговый движок использует встроенный набор правил. Сведения о расширении набора правил или создании пользовательского руководства по стилю API см. в репозитории Spectral repository на GitHub.

• Приложение-функция, которое вызывает линтинг, оплачивается отдельно, и вы управляете и обслуживаете его.

Предварительные условия

• Центр API в подписке Azure. Для создания подписки см. Краткое руководство: Создание вашего центра API.

• Поставщик ресурсов Сетки событий, зарегистрированный в вашей подписке. Если необходимо зарегистрировать поставщик ресурсов Azure Event Grid, см. раздел Подписка на события, опубликованные партнёром с помощью Azure Event Grid.

• Azure CLI для разработчиков (azd) Установите azd на вашем компьютере в среду, которую вы планируете использовать для следующей процедуры.

• Azure Functions Core Tools. Установите основные инструменты на вашем компьютере в среду, которую вы планируете использовать для следующей процедуры. Убедитесь, что инструменты доступны с помощью ваших настроек PATH.

• Для Azure CLI:

  • Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см. в разделе Начало работы с помощью Azure Cloud Shell.

    

  • Если вы предпочитаете локально запускать команды справки CLI, установите Azure CLI. Если вы работаете в Windows или macOS, попробуйте запустить Azure CLI в контейнере Docker. Дополнительные сведения см. в разделе Как запустить Azure CLI в контейнере Docker.

    • Если вы используете локальную установку, войдите в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Дополнительные параметры входа см. в разделе Аутентификация в Azure с использованием Azure CLI.

    • При появлении запроса установите расширение Azure CLI при первом использовании. Дополнительные сведения о расширениях см. в разделе Использование расширений и управление ими с помощью Azure CLI.

    • Запустите версию az version, чтобы найти установленную версию и зависимые библиотеки. Чтобы обновить последнюю версию, выполните обновление az.

  Примечание.

  Для команд az apic требуется расширение apic-extension Azure CLI. Расширение можно установить динамически при выполнении первой az apic команды или вручную установить расширение. Дополнительные сведения см. в разделе Manage Azure CLI Extensions: Install, Update и Remove.

  Последние изменения и обновления в см. в заметках о выпуске . Для некоторых функций может потребоваться предварительная версия или определенная версия расширения.

Используйте azd deployment для функционального приложения и подписки на события.

В следующих процедурах описаны автоматизированные шаги для использования интерфейса командной строки разработчика Azure (azd) для настройки приложения-функции и подписки на события, которые обеспечивают проверку кода и анализ в вашем центре API.

Примечание.

Если вы предпочитаете настроить движок и ресурсы с помощью ручного развертывания, обратитесь к репозиторию GitHub Azure API Center Analyzer для получения рекомендаций по развертыванию приложения-функции и настройке подписки на события.

Запустите пример с помощью azd

1. Клонируйте репозиторий GitHub Azure API Center Analyzer на вашу локальную машину.

2. Запустите Visual Studio Code и выберите ФайлОткрыть папку (CtrlK, CtrlO). Перейдите к папке APICenter-Analyzer клонированного репозитория и выберите "Выбрать папку".

3. В строке Visual Studio Code Activity Bar Выберите Explorer (Ctrl+Shift+E), чтобы просмотреть структуру папок репозитория.

   • Разверните папку resources/rulesets и обратите внимание на файл oas.yaml. Этот файл отражает текущее руководство по стилю API. Этот файл можно изменить, чтобы удовлетворить потребности организации.

   • Разверните папку src/functions и обратите внимание на файл ApiAnalyzerFunction.ts. Этот файл предоставляет код функции для функционального приложения. Этот файл можно изменить, чтобы настроить поведение функции в соответствии с требованиями приложения.

4. Откройте терминал в коде Visual Studio и выполните проверку подлинности с помощью интерфейса командной строки разработчика 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>.

5. Затем войдите в Azure portal с помощью Azure CLI:

   az login
   

   Вам будет предложено ввести учетные данные для входа в Azure.

   Окно браузера подтверждает успешный вход. Закройте окно и вернитесь к этой процедуре.

6. Выполните следующую команду, чтобы развернуть инфраструктуру линтинга в вашей подписке Azure.

   Для этой команды вам потребуется следующая информация. Большинство этих значений доступны на странице Overview для ресурса центра API в Azure portal.

   • Имя и идентификатор подписки
   • Имя центра API
   • Имя группы ресурсов для центра API
   • Регион развертывания для приложения-функции (может отличаться от региона центра API)

   azd up
   

7. Следуйте инструкциям, чтобы предоставить необходимые сведения о развертывании и параметры. Дополнительные сведения смотрите в разделе Запуск примера с помощью 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.

8. После завершения подготовки процесс развертывает новое приложение-функцию в 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
   

9. После завершения развертывания убедитесь, что новое приложение-функция присутствует и функция опубликована.

   Если функция apicenter-analyer не указана или Status не Enabled, опубликуйте функцию с помощью Основных инструментов Azure Functions.

10. Настройка подписки на события с помощью PowerShell или оболочки bash в коде Visual Studio.

Подтверждение функции, опубликованной в Azure portal

По завершении развертывания убедитесь, что новое приложение-функция присутствует в Azure portal и функция публикуется.

1. Войдите в раздел Azure portal, перейдите к разделу Function App и выберите новое приложение-функцию в списке.

2. На странице «Обзор» для нового функционального приложения убедитесь, что состояние функционального приложения — «Запущено».

3. В разделе "Функции " убедитесь apicenter-analyer , что функция указана, а состояниевключено.

   

Публикация функции apicenter-analyzer с помощью основных средств Azure Functions

Если процесс развертывания не публикует функцию apicenter-analyer в приложении-функции в Azure portal, можно выполнить следующие команды в терминале кода Visual Studio и завершить процесс.

1. Выполните следующую команду, чтобы подтвердить, что функция не опубликована в приложении-функции:

   Примечание.

   Эта команда использует новую группу ресурсов, созданную процессом развертывания для приложения-функции, а не группу ресурсов для центра API. Замените <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
   

   Выходные данные команды должны быть пустыми.

2. В обозревателе разверните папку src/functionsApiAnalyzerFunction.ts и откройте файл. Это действие подтверждает, что среда настроена для поиска содержимого в правильном расположении.

3. Убедитесь, что ваша среда включает менеджер пакетов npm и среду выполнения Node.js, и установите любые средства при необходимости.

   node --version
   npm --version
   

4. При необходимости установите средства кода Azure Functions в среду:

   npm install -g azure-functions-core-tools@4 --unsafe-perm true
   

5. Выполните следующую команду, чтобы опубликовать код функции в приложении-функции в 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]
   

6. В Azure portal убедитесь, что функция apicenter-analyzer теперь опубликована и включена для приложения-функции.

Настройка подписки на события

После успешной публикации функции в приложении-функции в Azure portal можно создать подписку на события в центре API, чтобы активировать приложение-функцию при отправке или обновлении файла определения API.

1. Получите идентификатор ресурса центра API. Замените <apic-name> названием вашего центра API и <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)
   

2. Получите идентификатор ресурса функции в функциональном приложении. В этом примере имя функции — 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)
   

3. Создайте подписку на события с помощью команды az eventgrid event-subscription create. Созданная подписка включает события для добавления или обновления определений API.

   #! /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"
   

   Примечание.

   Для распространения подписки на события в приложение-функцию может потребоваться некоторое время.

4. Перейдите в центр API в Azure portal и подтвердите новую подписку на события в разделе Events>Event Subscriptions.

Триггерное событие в API-центре

Чтобы проверить подписку на события, попробуйте отправить или обновить файл определения API, связанный с версией API в центре API. Например, отправьте документ OpenAPI или AsyncAPI. После активации подписки на событие функциональное приложение вызывает инструмент анализа API для анализа определения API.

• Подробные инструкции по добавлению API, версии API и определения API в центр API см. в руководстве по регистрации API в центре API.

• Сведения о создании API путем отправки файла определения API с Azure CLI см. в разделе Register API из файла спецификации.

Чтобы убедиться, что подписка на события активируется:

1. Перейдите в центр API и выберите "События".

2. Перейдите на вкладку "Подписки на события" и выберите подписку на события для приложения-функции.

3. Просмотрите метрики, чтобы убедиться, что подписка на событие запускается и линтинг вызывается успешно.

   

   Примечание.

   Для отображения метрик может потребоваться несколько минут.

После анализа определения API подсистема подстроек создает отчет на основе настроенного руководства по стилю API.

Просмотр отчетов по анализу API

Отчет анализа для определения API можно просмотреть в Azure portal. После анализа определения API отчет выводит список ошибок, предупреждений и сведений на основе настроенного руководства по стилю API.

На портале также можно просмотреть сводку отчетов по анализу для всех определений API в центре API.

Отчет анализа для определения API

Чтобы просмотреть отчет по анализу определения API в центре API, выполните следующие действия.

1. На портале перейдите в ваш центр API, разверните Inventory и выберите Assets.

2. В списке активов выберите API, для которого вы добавили или обновили определение API.

3. Выберите версии и разверните строку для проверки API.

4. В разделе "Определение" выберите имя определения, которое вы добавили или обновили.

5. Выберите вкладку "Анализ ".

   

Откроется отчет по анализу API, который отображает определение и ошибки API, предупреждения и сведения на основе настроенного руководства по стилю API. На следующем снимке экрана показан пример отчета по анализу API.

Сводка по анализу API

Вы можете просмотреть сводку отчетов по анализу для всех определений API в центре API.

• На портале перейдите к центру API, разверните узел управления и выберите "Анализ API".

  

• Значок справа от каждой строки открывает отчет анализа API для определения.

Связанный контент

• Включите анализ API в Центре API — под управлением Microsoft
• Системные темы в Azure Event Grid
• Отправка push-уведомлений сетки событий — основные понятия
• схема Event Grid для центра API Azure