Руководство. Использование расширения Azure Управление API для Visual Studio Code для импорта API и управления ими

Статья
10/24/2023

ОБЛАСТЬ ПРИМЕНЕНИЯ: Потребление | Разработчик | Базовый | Стандартный | Премиум

В этом руководстве описано, как использовать расширение Управление API для Visual Studio Code для распространенных операций в Управление API. Для импорта, обновления, тестирования API и управления ими вы будете использовать знакомую среду Visual Studio Code.

Узнайте следующие темы:

импорт API в Управление API;
редактирование API;
применение политик службы "Управление API";
Проверка API

Снимок экрана: API в расширении Управление API.

Общие сведения о дополнительных возможностях службы "Управление API" см. в руководствах по этой службе на портале Azure.

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

Ознакомьтесь с терминологией службы "Управление API" в Azure.
Убедитесь, что вы установили Visual Studio Code и последнее расширение Azure Управление API для Visual Studio Code.
Создание экземпляра службы управления API Azure.

Импорт API

В следующем примере спецификация OpenAPI импортируется в формате JSON в службу "Управление API". Корпорация Майкрософт предоставляет используемый в этом примере API серверной части в Azure по адресу https://conferenceapi.azurewebsites.net.

В Visual Studio Code на панели действий щелкните значок Azure.
В области проводника разверните созданный экземпляр службы "Управление API".
Щелкните элемент Интерфейсы API правой кнопкой мыши и выберите Import from OpenAPI Link (Импорт по ссылке OpenAPI).
При появлении запроса введите следующие значения:
1. Ссылка на OpenAPI для содержимого в формате JSON. В этом примере: https://conferenceapi.azurewebsites.net?format=json.
  
  Этот файл указывает серверную службу, реализующую пример API, в данном случае https://conferenceapi.azurewebsites.net. Управление API пересылает запросы к этой веб-службе.
2. Имя API (например, demo-conference-api), которое является уникальным в экземпляре службы "Управление API". Это имя может содержать только буквы, цифры и дефисы. Первый и последний знаки должны быть буквой или цифрой. Это имя используется в пути для вызова API.

После успешного импорта интерфейс API отобразится в области проводника, а доступные операции API — в узле Operations (Операции).

Снимок экрана: импортированный API в области Обозреватель.

редактирование API;

API можно редактировать в Visual Studio Code. Например, измените в окне редактора JSON-описание API для Resource Manager, удалив протокол HTTP, используемый для доступа к API.

Снимок экрана: редактирование описания JSON в Visual Studio Code.

Чтобы изменить формат OpenAPI, в области проводника щелкните имя API правой кнопкой мыши и выберите Edit OpenAPI (Изменить OpenAPI). Внесите нужные изменения и щелкните Файл>Сохранить.

Применение политик к API

Служба "Управление API" предоставляет политики, которые можно настроить для интерфейсов API. Политики — это коллекция инструкций. Эти инструкции выполняются по очереди по запросу или в ответ API. Политики могут быть глобальными (то есть применяться ко всем API в экземпляре службы "Управление API") или могут быть ограничены определенным продуктом, API или операцией API.

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

В области проводника под импортированным API demo-conference-api выберите Policy (Политика). Файл политики откроется в окне редактора. Этот файл позволяет настроить политику для всех операций в API.
Обновите файл с использованием следующего содержимого в элементе <outbound>:
```
[...]
<outbound>
    <set-header name="Custom" exists-action="override">
        <value>"My custom value"</value>
    </set-header>
    <set-header name="X-Powered-By" exists-action="delete" />
    <redirect-content-urls />
    <base />
</outbound>
[...]
```
- Первая политика set-header добавляет настраиваемый заголовок ответа для демонстрационных целей.
- Вторая политика set-header удаляет заголовок X-Powered-By, если он существует. Этот заголовок может раскрывать сведения об исполняющей среде, используемой в серверной части API, и издатели часто его удаляют.
- Политика redirect-content-urls перезаписывает (маскирует) ссылки в тексте ответа так, чтобы каждая из них указывала на эквивалентную ссылку через шлюз службы "Управление API".
Сохраните файл. При появлении запроса выберите Upload (Отправить), чтобы отправить файл в облако.

Проверка API

Чтобы протестировать API, получите ключ подписки и отправьте запрос на шлюз Управление API.

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

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

В области проводника щелкните имя экземпляра службы "Управление API" правой кнопкой мыши.
Выберите Copy Subscription Key (Копировать ключ подписки). Этот ключ предназначен для встроенной подписки доступа, созданной при создании экземпляра Управление API.

Внимание

Подписка all-access обеспечивает доступ к каждому API в этом Управление API экземпляре и должен использоваться только авторизованными пользователями. Никогда не используйте его для обычного доступа к API или внедрения ключа all-access в клиентских приложениях.

Тестирование операции API

В области проводника под импортированным API demo-conference-api разверните узел Operations (Операции).
Выберите операцию, например GetSpeakers, после чего щелкните операцию правой кнопкой мыши и выберите Тестовая операция.
В окне редактора рядом с Ocp-Apim-Subscription-Key замените {{SubscriptionKey}} ключом подписки, который вы скопировали.
Рядом с Ocp-Apim-Trace, введите false. Этот параметр отключает трассировку запросов.
Щелкните Отправить запрос.

Снимок экрана: отправка запроса API из Visual Studio Code.

При успешном выполнении запроса серверная часть вернет ответ 200 — ОК и другие данные.

Снимок экрана: ответ теста API в Visual Studio Code.

В ответе обратите внимание на следующие сведения:

В ответ добавляется заголовок Custom.
Заголовок X-Powered-By не отображается в ответе.
URL-адреса серверной части API перенаправляются в шлюз службы "Управление API", в нашем случае — https://apim-hello-world.azure-api.net/demo-conference-api.

Обработка запроса трассировки

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

Чтобы отследить обработку запросов, сначала включите параметр "Разрешить трассировку " для подписки, используемой для отладки API. Инструкции по включению этого параметра с помощью портала см. в разделе "Проверка параметра трассировки". Чтобы ограничить непреднамеренное раскрытие конфиденциальной информации, трассировка допускается только на 1 час.

После разрешения трассировки с подпиской выполните следующие действия.

В области проводника под импортированным API demo-conference-api разверните узел Operations (Операции).
Выберите операцию, например GetSpeakers, после чего щелкните операцию правой кнопкой мыши и выберите Тестовая операция.
В окне редактора рядом с Ocp-Apim-Subscription-Key замените {{SubscriptionKey}} ключ подписки, который требуется использовать.
Рядом с Ocp-Apim-Trace, введите true. Этот параметр включает трассировку для этого запроса.
Щелкните Отправить запрос.

После успешного выполнения запроса внутренний ответ включает заголовок Ocp-APIM-Trace-Location .

Снимок экрана: расположение трассировки в ответе теста API в Visual Studio Code.

Выберите ссылку рядом с Ocp-APIM-Trace-Location , чтобы просмотреть сведения о входящего трафика, серверной части и исходящей трассировки. Она помогает определить, где возникли проблемы после создания запроса.

Совет

При тестировании операций API расширение Управление API разрешает необязательную отладку политики (доступно только на уровне служб разработчика).

Очистка ресурсов

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

Кроме того, можно нажать кнопку Delete API Management (Удалить службу "Управление API"), чтобы удалить только экземпляр службы "Управление API" (без группы ресурсов).

Снимок экрана: удаление экземпляра Управление API из Visual Studio Code.

В этом руководстве представлено несколько функций расширения Управление API для Visual Studio Code. с помощью которых можно импортировать API и управлять ими. Вы научились выполнять следующие задачи:

импорт API в Управление API;
редактирование API;
применение политик службы "Управление API";
Проверка API

Расширение Управление API предоставляет дополнительные функции для работы с API. Например, политики отладки (доступные на уровне служб "Разработка") или создание именованных значений и управление ими.