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

Статья
06/01/2023

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

В этой статье описаны процессы импорта веб-приложения Azure в Управление API Azure и тестирования импортированного API на портале Azure.

Примечание.

Вы можете использовать расширение управления API для кода Visual Studio, чтобы импортировать свои API и управлять ими. Следуйте руководству по расширению управления API, чтобы установить и начать работу.

Вы узнаете, как выполнять следующие задачи:

импорт веб-приложения в Службу приложений;
проверка API на портале Azure;

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

Служба приложений Azure — это служба на базе HTTP для размещения веб-приложений, интерфейсов REST API и внутренней части мобильных решений. Разработчики API могут применять произвольные стеки технологий и конвейеры для разработки API, а также публикации их серверной части в формате веб-приложений в защищенной и масштабируемой среде. Созданные веб-приложения можно зарегистрировать в службе "Управление API", чтобы предоставлять потребителям доступ к API, управлять ими и защищать их на всем протяжении жизненного цикла.

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

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

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

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

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

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

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

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

Пример

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

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

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

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

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

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

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

В следующих статьях описаны процессы создания простого веб-API и его публикации в формате веб-приложения Azure:
- Руководство по созданию веб-API с помощью ASP.NET Core
- Публикация приложения ASP.NET Core в Azure с помощью Visual Studio Code

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

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

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

Совет

Ниже объясняется, как запустить на портале Azure процесс импорта с использованием Управления API Azure. Кроме того, вы можете перейти к Управлению 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, вы автоматически становитесь его администратором. Поэтому вы по умолчанию будете подписаны на все продукты.

По умолчанию каждый экземпляр 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. Это значение будет добавляться к пути / для операций с подстановочными знаками.
Выберите Отправить.