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

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

Примечание.

В предварительной версии Центр API Azure также может автоматически настроить подсистему подстроки и все необходимые зависимости и триггеры. Подробнее.

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

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

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

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

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

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

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

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

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

Параметры развертывания подсистемы подкладок и подписки на события

В этой статье приведены два варианта развертывания обработчика подкладок и подписки на события в центре API:

• Автоматическое развертывание . Используйте интерфейс командной строки () разработчика Azure дляazd одношагового развертывания инфраструктуры подстраивание. Этот параметр рекомендуется для упрощенного процесса развертывания.

• Развертывание вручную. Выполните пошаговые инструкции по развертыванию приложения Функции Azure и настройке подписки на события. Этот параметр рекомендуется, если вы предпочитаете развертывать ресурсы и управлять ими вручную.

Ограничения

• Linting в настоящее время поддерживает только файлы спецификации JSON или YAML, такие как документы спецификации OpenAPI или AsyncAPI.
• По умолчанию подсистема подстроек использует встроенный spectral:oas набор правил. Чтобы расширить набор правил или создать пользовательские руководства по стилю API, см . репозиторий Spectral GitHub.
• Приложение-функция Azure, которое вызывает подкладку, взимается отдельно, а также управляете и поддерживаете ее.

Необходимые компоненты

• Центр API в подписке Azure. Если вы еще не создали его, см . краткое руководство. Создание центра API.

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

• При использовании Azure CLI выполните следующее:

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

    

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

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

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

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

  Примечание.

  az apic для команд требуется apic-extension расширение Azure CLI. Если вы не использовали az apic команды, расширение можно установить динамически при выполнении первой az apic команды или установить расширение вручную. Дополнительные сведения о расширениях Azure CLI.

  Дополнительные сведения о последних изменениях и обновлениях см. в заметках о выпускеapic-extension.

  Примечание.

  Примеры команд Azure CLI в этой статье могут выполняться в PowerShell или оболочке bash. Если это необходимо из-за разного синтаксиса переменной, для двух оболочк предоставляются отдельные примеры команд.

azdразвертывание подписки Функции Azure приложений и событий

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

Другие предварительные требования для этого параметра

• Azure Developer CLI (azd)

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

1. Клонируйте репозиторий GitHub и откройте его в Visual Studio Code.

2. Измените каталог на папку APICenter-Analyzer в репозитории.

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

4. Проверка подлинности с помощью Интерфейса командной строки разработчика Azure и Azure CLI с помощью следующих команд:

   azd auth login
   
   az login
   

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

   azd up
   

6. Следуйте инструкциям, чтобы указать необходимые сведения о развертывании и параметры, например имя среды и имя центра API. Дополнительные сведения см. в разделе "Запуск примера" с помощью интерфейса командной строки разработчика Azure (azd).

   Примечание.

   Развертывание может занять несколько минут.

7. После завершения развертывания перейдите в центр API в портал Azure. В меню слева выберите подписки "События">, чтобы просмотреть созданную подписку на события.

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

Инструкции по настройке Функции Azure приложения и подписки на события

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

Другие предварительные требования для этого параметра

• Visual Studio Code с расширением Функции Azure версии 1.10.4 или более поздней версии.

Шаг 1. Развертывание приложения Функции Azure

Чтобы развернуть приложение Функции Azure, которое запускает функцию подкладки в определениях API:

1. Клонируйте репозиторий GitHub и откройте его в Visual Studio Code.

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

3. При необходимости запустите приложение-функцию локально, чтобы протестировать его. Дополнительные сведения см . в файле README в репозитории.

4. Разверните приложение-функцию в Azure. Инструкции см . в кратком руководстве. Создание функции в Azure с помощью TypeScript с помощью Visual Studio Code.

   Примечание.

   Развертывание приложения-функции может занять несколько минут.

5. Войдите в портал Azure и перейдите в приложение-функцию.

6. На странице обзора проверьте следующие сведения:

   • Убедитесь, что состояние приложения-функции запущено.
   • В разделе "Функции" убедитесь, что состояние функции apicenter-analyzer включено.

   

Шаг 2. Настройка управляемого удостоверения в приложении-функции

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

Портал

1. В портал Azure перейдите к приложению-функции и выберите "Удостоверение" в разделе "Параметры".
2. На вкладке "Назначаемая системой" установите значение "Состояние включено", а затем нажмите кнопку "Сохранить".

Теперь, когда управляемое удостоверение включено, назначьте ему роль диспетчера соответствия Центра API Azure для доступа к центру API.

1. В портал Azure перейдите в центр API и выберите элемент управления доступом (IAM).
2. Выберите + Добавить > назначение ролей.
3. Выберите роли функции задания и выберите диспетчер соответствия требованиям Центра API Azure. Выберите Далее.
4. На странице "Участники" в разделе "Назначение доступа" выберите "Управляемое удостоверение > " и "Выбрать участников".
5. На странице "Выбор управляемых удостоверений" найдите и выберите управляемое удостоверение приложения-функции. Нажмите кнопку "Выбрать" и "Далее".
6. Просмотрите назначение роли и нажмите кнопку "Проверить и назначить".

Azure CLI

1. Включите назначаемое системой удостоверение приложения-функции с помощью команды az functionapp identity assign . <resource-group-name> Замените и на <function-app-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)
   

2. Получите идентификатор ресурса центра API. <resource-group-name> Замените <apic-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)
   

3. Назначьте управляемое удостоверение приложения-функции роль диспетчера соответствия требованиям Центра API Azure в центре 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. Настройка подписки на события в центре API

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

Портал

1. В портал Azure перейдите в центр API и выберите "События".

2. На вкладке "Начало работы" выберите функцию Azure.

3. На странице "Создание подписки на события" сделайте следующее:

   1. Введите описательное имя подписки на событие и выберите схему сетки событий.

   2. В разделе "Сведения о разделе" введите имя раздела системы по вашему выбору.

   3. В типах событий выберите следующие события:

      • Добавлено определение API
      • Обновлено определение API

   4. В разделе "Сведения о конечной точке" выберите "Настройка конечной точки" функции > Azure.

   5. На странице "Выбор функции Azure" выберите приложение-функцию и настроенную функцию apicenter-linter. Нажмите кнопку " Подтвердить выбор".

   6. Нажмите кнопку создания.

      

4. Перейдите на вкладку "Подписки на события" и нажмите кнопку "Обновить". Убедитесь, что состояние подготовки подписки на событие выполнено успешно.

   

Azure CLI

1. Получите идентификатор ресурса центра API. <resource-group-name> Замените <apic-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. <resource-group-name> Замените <function-app-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"
   

Примечание.

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

Событие триггера в центре API

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

• Подробные инструкции по добавлению API, версии API и определения API в центр API см. в руководстве по регистрации API в центре API.
• Сведения о создании API путем отправки файла определения API с помощью Azure CLI см. в разделе "Регистрация API" из файла спецификации.

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

1. Перейдите в центр API и выберите "События " в меню слева.

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

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

   

   Примечание.

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

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

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

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

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

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

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

1. На портале перейдите к версии API в центре API, где вы добавили или обновили определение API.
2. В меню слева в разделе "Сведения" выберите "Определения".
3. Выберите определение API, которое вы загрузили или обновили.
4. Выберите вкладку "Анализ ".

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

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

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

1. На портале перейдите в центр API.

2. В меню слева в разделе "Управление" выберите "Анализ API". Появится сводка.

   

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

Дополнительные сведения о сетке событий:

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