Руководство: Импортировать и опубликовать первый API

ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни управления API

В этом руководстве показано, как импортировать внутренний API спецификации OpenAPI в формате JSON в Управление API Azure. В этом примере вы импортируете открытый исходный код API Petstore.

При импорте серверного API в систему управления API, ваше API в системе управления становится фасадом для серверного API. Вы можете настроить фасад в соответствии с вашими потребностями в службе управления API, не изменив внутренний API. Дополнительные сведения см. в статье Transform and protect your API (Преобразование и защита API).

В этом руководстве описано следующее:

После импорта API-интерфейсом можно управлять на портале Azure.

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

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

Перейдите к экземпляру управления API.

1. На портале Azure найдите и выберите службы управления API:

   

2. На странице управления API выберите ваш экземпляр службы управления API:

   

Импорт и публикация API серверной части

В этом разделе показано, как импортировать и опубликовать серверный API по спецификации OpenAPI.

1. В левой области навигации вашей службы управления API в разделе API, выберите API.

2. Выберите плитку OpenAPI.

3. В окне Создание из спецификации OpenAPI выберите Полный.

4. Введите значения из следующей таблицы.

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

   

   Настройка	значение	Описание
   Спецификация OpenAPI	https://petstore3.swagger.io/api/v3/openapi.json -Или- https://petstore.swagger.io/v2/swagger.json	Указывает серверную службу, реализующую API, и операции, поддерживаемые API. URL-адрес серверной службы появится позже в качестве URL-адреса веб-службы на странице Параметры API. После импорта можно добавить, изменить, переименовать или удалить операции в спецификации.
   Включение параметров запроса в шаблоны операций	Установлен (по умолчанию)	Указывает, следует ли импортировать необходимые параметры запроса в спецификацию в качестве параметров шаблона в Управление API.
   Отображаемое имя	После ввода URL-адреса спецификации OpenAPI Управление API заполняет это поле на основе JSON.	Это имя отображается на портале разработчика.
   Имя	После ввода URL-адреса спецификации OpenAPI Управление API заполняет это поле на основе JSON.	Уникальное имя для API.
   Description	После ввода URL-адреса спецификации OpenAPI Управление API заполняет это поле на основе JSON.	Необязательное описание API.
   Схема URL-адресов	HTTPS	Определяет, какие протоколы можно использовать для доступа к этому API.
   Суффикс URL-адреса API	petstore	Этот суффикс добавляется к основному URL-адресу службы "Управление API". Управление API различает и направляет API по суффиксу, поэтому суффикс должен быть уникальным для каждого API для данного издателя. Узнайте больше о том, как управление API маршрутизирует запросы.
   Теги		Теги для упорядочивания API для поиска, группирования или фильтрации.
   Товары	Unlimited	Ассоциация одного или нескольких API. На определенных уровнях экземпляр API Management включает два продукта-образца: Starter и Unlimited. Вы публикуете API на портале разработчика, связав API с продуктом. Вы можете включить несколько API в продукт и предложить подписки на продукты разработчикам на портале разработчиков. Чтобы добавить этот API в другой продукт, введите или выберите название продукта. Повторите этот шаг, чтобы добавить API в несколько продуктов. Вы также можете добавить API в продукты позже на странице Параметры. Дополнительные сведения о продуктах см. в статье Создание и публикация продукта.
   Шлюзы	Управляемый	Шлюзы API, которые предоставляют API. Это поле доступно только в службах уровня Разработка и Премиум. Управляемый обозначает шлюз, встроенный в службу управления API и размещенный корпорацией Майкрософт в Azure. Самостоятельно развёрнутые шлюзы доступны только в сервисах уровня "Разработчик" и "Премиум". Вы можете развернуть их локально или в других облаках. Если вы не выбираете шлюзы, API недоступен, и запросы API не выполняются.
   Версия этого API	Выберите или отмените выбор	Дополнительные сведения см. в статье Публикация нескольких версий API.

5. Щелкните Создать, чтобы создать API.

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

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

После импорта API можно просмотреть и изменить его параметры и операции на портале Azure.

1. В левой панели навигации вашего экземпляра "Управление API" в разделе API выберите API.

2. Выберите импортированный API (например, Swagger Petstore).

3. Выберите вкладку "Конструктор" , чтобы просмотреть и изменить операции API в спецификации OpenAPI, включая:

   • Сведения об операциях, такие как URL-адрес, метод и описание
   • Определения запросов и ответов
   • Политики для изменения запросов и ответов

4. Перейдите на вкладку "Параметры" , чтобы просмотреть и изменить сведения о конфигурации API, в том числе:

   • Отображаемое имя, имя и описание
   • URL-адрес веб-службы (серверная служба), схема URL-адресов и суффикс URL-адреса API
   • Продукты, теги и управление версиями
   • Более сложные параметры, такие как требования к подписке, безопасность и мониторинг

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

Проверка нового API на портале Azure

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

1. В левой панели навигации на экземпляре управления API выберите API>APIs>Swagger Petstore.

2. Выберите вкладку "Тест" и выберите " Найти домашних животных по состоянию". На странице показан параметр запроса статуса. Выберите одно из доступных значений, например ожидание. Здесь также можно добавить параметры запроса и заголовки.

   В разделе HTTP-запроса заголовок Ocp-Apim-Subscription-Key заполняется автоматически, что вы можете увидеть, если нажмете на значок "глаз".

3. Выберите Отправить.

   

   Бэкенд отвечает 200 OK и некоторыми данными.

Как управление API маршрутизирует запросы

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

URL-адрес запроса клиента:
[API Management gateway URL] + [API URL suffix] + [Operation endpoint]

Управление API перенаправляет запрос в серверную службу с помощью этого шаблона:

URL-адрес серверной службы:
[Web service URL] + [Operation endpoint]

В следующей таблице описан каждый параметр маршрутизации в контексте примера API Petstore, используемого в этом руководстве:

Пример: поиск домашних животных по состоянию

Использование API Petstore, импортированного в этом руководстве:

1. Управление API вызовов клиентов:
   https://apim-hello-world.azure-api.net/petstore/pet/findByStatus?status=pending

   • URL-адрес шлюза управления API: https://apim-hello-world.azure-api.net
   • Суффикс URL-адреса API: petstore
   • Конечная точка операции: /pet/findByStatus

2. Маршруты управления API для серверной части:
   https://petstore3.swagger.io/api/v3/pet/findByStatus?status=pending

   • URL-адрес веб-службы: https://petstore3.swagger.io/api/v3
   • Конечная точка операции: /pet/findByStatus (то же, что и в определении управления API)

Следующие шаги

Из этого руководства вы узнали, как:

Перейдите к следующему учебнику, чтобы узнать, как создать и опубликовать продукт: