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

На первый взгляд
Цель: Убедитесь, что приложение использует готовые к работе API
Время: 20 минут
Подключаемые модули:ApiCenterProductionVersionPlugin
Предварительные требования:настройка прокси-сервера разработки, Центра API Azure

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

Чтобы проверить, использует ли ваше приложение API промышленного уровня, вы можете использовать плагин ApiCenterProductionVersionPlugin. Этот подключаемый модуль сравнивает информацию о запросах API из вашего приложения с информацией из Центра API Azure и сообщает о любых непроизводственных API-запросах. Он также рекомендует рабочую версию api, которую вы используете.

Снимок экрана: консоль с проверкой прокси-сервера разработки, если записанные запросы API соответствуют API рабочей версии, зарегистрированным в Центре API Azure.

Перед началом работы

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

Создание экземпляра Центра API Azure

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

Снимок экрана Центра API Azure, показывающий API с разными версиями

Эти ApiCenterProductionVersionPlugin сведения используются для проверки того, относятся ли API, используемые вашим приложением, к продуктовым или тестовым API.

Скопировать информацию Центра API

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

Снимок экрана: страница обзора Центра API Azure с выделенными свойствами

Настройка прокси-сервера разработки

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

Включите ApiCenterProductionVersionPlugin

devproxyrc.json В файле добавьте следующую конфигурацию:

Файл: devproxyrc.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.1.0/rc.schema.json",
  "plugins": [
    {
      "name": "ApiCenterProductionVersionPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
      "configSection": "apiCenterProductionVersionPlugin"
    }
  ],
  "urlsToWatch": [
    "https://jsonplaceholder.typicode.com/*"
  ],
  "apiCenterProductionVersionPlugin": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.1.0/apicenterproductionversionplugin.schema.json",
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default"
  }
}

В свойствах subscriptionId, resourceGroupName и serviceName укажите сведения о вашем экземпляре Azure API Center.

В свойстве urlsToWatch укажите URL-адреса, которые использует приложение.

Совет

Используйте расширение Visual Studio Code Dev Proxy Toolkit для легкого управления конфигурацией Dev Proxy.

Добавление репортера

Эта функция создает отчет API, которые использует ваше приложение. Чтобы просмотреть этот отчет, добавьте репортера в файл конфигурации прокси-сервера разработки. Dev Proxy предлагает несколько репортеров. В этом примере используется репортер обычного текста.

Обновите devproxyrc.json файл, добавив ссылку на текстовый отчётчик:

Файл: devproxyrc.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.1.0/rc.schema.json",
  "plugins": [
    {
      "name": "ApiCenterProductionVersionPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
      "configSection": "apiCenterProductionVersionPlugin"
    },
    {
      "name": "PlainTextReporter",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll"
    }
  ],
  "urlsToWatch": [
    "https://jsonplaceholder.typicode.com/*"
  ],
  "apiCenterProductionVersionPlugin": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.1.0/apicenterproductionversionplugin.schema.json",
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default"
  }
}

Проверьте, использует ли ваше приложение API уровня рабочей среды

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

Подключение к подписке Azure

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

Запуск прокси-сервера разработки

После подключения к подписке Azure запустите Dev Proxy. Если вы запускаете Dev Proxy из той же папки, где находится ваш файл devproxyrc.json, он автоматически загружает конфигурацию. В противном случае укажите путь к файлу конфигурации с помощью --config-file параметра.

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

 info    Plugin ApiCenterProductionVersionPlugin connecting to Azure...
 info    Listening on 127.0.0.1:8000...

Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
Press CTRL+C to stop Dev Proxy

Нажмите клавишу R , чтобы начать запись запросов API из приложения.

Используйте ваше приложение

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

 info    Plugin ApiCenterProductionVersionPlugin connecting to Azure...
 info    Listening on 127.0.0.1:8000...

Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
Press CTRL+C to stop Dev Proxy

◉ Recording... 

 req   ╭ GET https://jsonplaceholder.typicode.com/posts?api-version=v1.0
 api   ╰ Passed through

 req   ╭ GET https://jsonplaceholder.typicode.com/users?api-version=beta
 api   ╰ Passed through

Проверка версий API

Остановите запись, нажав клавишу S. Прокси-сервер разработки подключается к экземпляру Центра API и сравнивает сведения о запросах с информацией из Центра API.

 info    Plugin ApiCenterProductionVersionPlugin connecting to Azure...
 info    Listening on 127.0.0.1:8000...

Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
Press CTRL+C to stop Dev Proxy

◉ Recording... 

 req   ╭ GET https://jsonplaceholder.typicode.com/posts?api-version=v1.0
 api   ╰ Passed through

 req   ╭ GET https://jsonplaceholder.typicode.com/users?api-version=beta
 api   ╰ Passed through
○ Stopped recording
 info    Checking if recorded API requests use production APIs as defined in API Center...
 info    Loading APIs from API Center...
 info    Analyzing recorded requests...
 warn    Request GET https://jsonplaceholder.typicode.com/users?api-version=beta uses API version beta which is defined as Preview. Upgrade to a production version of the API. Recommended versions: v1.0
 info    DONE

Когда прокси-сервер разработки завершит анализ, он создает отчет в файле с именем ApiCenterProductionVersionPlugin_PlainTextReporter.txt со следующим содержимым:

Non-production APIs:

  GET https://jsonplaceholder.typicode.com/users?api-version=beta
  
Production APIs:

  GET https://jsonplaceholder.typicode.com/posts?api-version=v1.0

Итоги

С помощью ApiCenterProductionVersionPlugin вы можете проверить, использует ли ваше приложение API промышленного уровня. Подключаемый модуль сравнивает сведения о запросах API вашего приложения с информацией из Центра API Azure и создает отчеты о любых тестовых запросах API. Он также рекомендует рабочую версию api, которую вы используете. Проверка того, какие API использует приложение, помогает убедиться, что ваше приложение использует стабильные API, которые поддерживаются и охватываются соглашениями об уровне обслуживания, что делает приложение более надежным. Эту проверку можно выполнить вручную или интегрировать с конвейером CI/CD, чтобы убедиться, что приложение использует API уровня рабочей среды перед выпуском в рабочую среду.

Дополнительные сведения

  • Last updated on