Поделиться через

Обнаружение теневых API с помощью прокси-сервера разработки

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

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

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

Снимок экрана командной строки, показывающий, как Dev Proxy проверяет, зарегистрированы ли записанные API-запросы в Центре API Azure.

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

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

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

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

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

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

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

Включите ApiCenterOnboardingPlugin

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

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
  "plugins": [
    {
      "name": "ApiCenterOnboardingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
      "configSection": "apiCenterOnboardingPlugin"
    }
  ],
  "urlsToWatch": [
    "https://jsonplaceholder.typicode.com/*"
  ],
  "apiCenterOnboardingPlugin": {
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": false
  }
}

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

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

Подсказка

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

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

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

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

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
  "plugins": [
    {
      "name": "ApiCenterOnboardingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
      "configSection": "apiCenterOnboardingPlugin"
    },
    {
      "name": "PlainTextReporter",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
    }
  ],
  "urlsToWatch": [
    "https://jsonplaceholder.typicode.com/*"
  ],
  "apiCenterOnboardingPlugin": {
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": false
  }
}

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

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

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

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

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

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

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

 info    Plugin ApiCenterOnboardingPlugin 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 ApiCenterOnboardingPlugin 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   ╰ Passed through

 req   ╭ DELETE https://jsonplaceholder.typicode.com/posts/1
 api   ╰ Passed through

Проверка теневых API

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

 info    Plugin ApiCenterOnboardingPlugin 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   ╰ Passed through

 req   ╭ DELETE https://jsonplaceholder.typicode.com/posts/1
 api   ╰ Passed through
○ Stopped recording
 info    Checking if recorded API requests belong to APIs in API Center...
 info    Loading APIs from API Center...
 info    Loading API definitions from API Center...

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

New APIs that aren't registered in Azure API Center:

https://jsonplaceholder.typicode.com:
  DELETE https://jsonplaceholder.typicode.com/posts/1

APIs that are already registered in Azure API Center:

GET https://jsonplaceholder.typicode.com/posts

Автоматическая интеграция теневых API

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

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
  "plugins": [
    {
      "name": "ApiCenterOnboardingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
      "configSection": "apiCenterOnboardingPlugin"
    },
    {
      "name": "PlainTextReporter",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
    }
  ],
  "urlsToWatch": [
    "https://jsonplaceholder.typicode.com/*"
  ],
  "apiCenterOnboardingPlugin": {
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": true
  }
}

При запуске прокси-сервера разработки с параметром createApicEntryForNewApis, установленным в true, он автоматически создает новые записи API в Центре API Azure для теневых API, которые он обнаруживает.

Снимок экрана: Центр API, показывающий только что подключенный API.

Автоматическое подключение теневых API с помощью спецификации OpenAPI

При выборе автоматического подключения теневых API в Центр API Dev Proxy может сгенерировать спецификацию OpenAPI для API. Подключение API с спецификациями OpenAPI ускоряет подключение отсутствующих конечных точек и предоставляет необходимые сведения об API. Когда ApiCenterOnboardingPlugin обнаруживает, что Dev Proxy создал новую спецификацию OpenAPI, он связывает её с соответствующим подключенным API в API-центре.

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

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
  "plugins": [
    {
      "name": "OpenApiSpecGeneratorPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
    },
    {
      "name": "ApiCenterOnboardingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
      "configSection": "apiCenterOnboardingPlugin"
    },
    {
      "name": "PlainTextReporter",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
    }
  ],
  "urlsToWatch": [
    "https://jsonplaceholder.typicode.com/*"
  ],
  "apiCenterOnboardingPlugin": {
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": true
  }
}

Это важно

Прокси для разработки выполняет плагины в том порядке, в котором они зарегистрированы в конфигурации. Сначала необходимо зарегистрировать OpenApiSpecGeneratorPlugin, чтобы он смог создать спецификации OpenAPI перед тем, как ApiCenterOnboardingPlugin подключать новые API.

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

 info    Plugin ApiCenterOnboardingPlugin 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   ╰ Passed through

 req   ╭ DELETE https://jsonplaceholder.typicode.com/posts/1
 api   ╰ Passed through
○ Stopped recording
 info    Creating OpenAPI spec from recorded requests...
 info    Created OpenAPI spec file jsonplaceholder.typicode.com-20240614104931.json
 info    Checking if recorded API requests belong to APIs in API Center...
 info    Loading APIs from API Center...
 info    Loading API definitions from API Center...
 info    New APIs that aren't registered in Azure API Center:

https://jsonplaceholder.typicode.com:
  DELETE https://jsonplaceholder.typicode.com/posts/1
 info    Creating new API entries in API Center...
 info      Creating API new-jsonplaceholder-typicode-com-1718354977 for https://jsonplaceholder.typicode.com...
 info    DONE

Снимок экрана: Центр API Azure, показывающий недавно подключенный API с спецификацией OpenAPI.

Сводка

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

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

  • Last updated on