Импорт приложения-контейнера Azure в формате API

Статья
06/01/2023

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

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

Импорт приложения-контейнера, предоставляющего веб-API
проверка API на портале Azure;

Предоставление приложения-контейнера через Управление API

Контейнеры приложений Azure позволяет развертывать контейнерные приложения без управления сложной инфраструктурой. Разработчики API могут писать код с помощью предпочитаемого языка программирования или платформы, создавать микрослужбы с полной поддержкой распределенной среды выполнения приложений (Dapr) и выполнять масштабирование на основе HTTP-трафика или других событий.

Мы рекомендуем использовать Управление API в качестве среды управления для всех веб-API, размещенных в Контейнерах приложений. Для этого есть несколько причин:

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

Дополнительные сведения см. в статье Сведения об Управлении API.

Спецификация OpenAPI или подстановочные знаки

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

Если приложение-контейнер предоставляет спецификацию OpenAPI, Управление API создает операции API, которые сопоставляются напрямую с определением. Управление API будет выполнять поиск в нескольких расположениях для спецификации OpenAPI

Конфигурация приложения-контейнера.
/openapi.json
/openapi.yml
/swagger/v1/swagger.json

Если спецификация OpenAPI не предоставлена, Управление API создает операции с подстановочными знаками для типичных HTTP-команд (GET, PUT и т. п.). Вы можете использовать все возможности Управления API, но они не настраиваются с той же степенью детализации.

В любом случае вы всегда можете изменять операции в импортированном API и (или) добавлять их.

Пример

Предположим, что приложение-контейнер серверной части поддерживает две операции GET:

https://myappservice.azurewebsites.net/customer/{id}
https://myappservice.azurewebsites.net/customers

Вы импортируете это приложение-контейнер в службу "Управление API" с путем, подобным https://contosoapi.azure-api.net/store. В приведенной ниже таблице перечислены операции, которые импортируются в Управление API при наличии и при отсутствии спецификации OpenAPI.

Тип	Импортируемые операции	Примеры запросов
Спецификация OpenAPI	`GET /customer/{id}` `GET /customers`	`GET https://contosoapi.azure-api.net/store/customer/1` `GET https://contosoapi.azure-api.net/store/customers`
Подстановочный знак	`GET /*`	`GET https://contosoapi.azure-api.net/store/customer/1` `GET https://contosoapi.azure-api.net/store/customers`

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

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

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

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

На портале Azure найдите и выберите службы Управление API.
На странице Службы Управления API выберите экземпляр Управления API.

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

На портале Azure перейдите к службе "Управление API" и в меню выберите Интерфейсы API.
Выберите приложение-контейнер из списка.
Выберите Обзор, чтобы просмотреть список приложений-контейнеров в подписке.
Выберите приложение-контейнер. Если с выбранным приложением-контейнером связано определение OpenAPI, Управление API извлечет его и импортирует. Если определения OpenAPI в нем нет, Управление API будет использовать для предоставления этого API операции с подстановочными знаками для самых распространенных HTTP-команд.
Добавьте суффикс URL-адреса API. Суффиксом называется имя, которое идентифицирует конкретный API в экземпляре службы "Управление API". Он должен быть уникальным в этом экземпляре Управления API.
Чтобы опубликовать API, его нужно связать с определенным продуктом. В нашем случае используется продукт Без ограничений. Если вы планируете опубликовать API и предоставить разработчикам доступ к нему, добавьте его в продукт.
Примечание.

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

Каждый экземпляр Управление API поставляется с двумя примерами продуктов при создании:
- Starter
- Unlimited
Введите другие параметры API. Вы можете задать значения во время создания или настроить их позже, перейдя на вкладку Параметры. Параметры описаны в руководстве по импорту и публикации первого руководства по API.
Нажмите кнопку создания.

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

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

Выберите API, созданный на предыдущем шаге.
Откройте вкладку Тест.
Выберите операцию.

На странице отобразятся поля для параметров запроса и для заголовков. Один из заголовков, Ocp-Apim-Subscription-Key, содержит ключ подписки для продукта, связанного с этим API. Как создатель экземпляра службы "Управление API", вы автоматически являетесь администратором, поэтому сведения о ключе будут заполнены автоматически.
Нажмите кнопку Отправить.

Если тест пройдет успешно, приложение серверной части передаст код ответа 200 — OK и некоторые данные.

Тестирование операций с подстановочными знаками на портале

Если создаются операции с подстановочными знаками, они не всегда будут напрямую сопоставляться с API серверной части. Например, в импортированных через Управление API операциях GET с подстановочными знаками по умолчанию используется путь /. Но API серверной части может поддерживать операции GET и с таким путем:

/api/TodoItems

Чтобы протестировать путь /api/TodoItems, выполните описанные ниже действия.

Выберите созданный API и нужную операцию.
Откройте вкладку Тест.
В разделе Параметры шаблона измените значение рядом с именем подстановочного знака (*). Например, введите api/TodoItems. Это значение будет добавляться к пути / для операций с подстановочными знаками.
Выберите Отправить.