Импорт спецификации OpenAPI

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

В этой статье показано, как импортировать внутренний API OpenAPI в Azure Управление API с помощью различных средств. Также здесь показано, как протестировать программный интерфейс в службе "Управление API".

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

• Импорт спецификации OpenAPI с помощью портал Azure, Azure CLI или Azure PowerShell
• проверка API на портале Azure;

Примечание.

Ограничения импорта API описаны в ограничениях импорта API и известных проблемах.

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

• Экземпляр управления API. Если у вас еще нет одного, выполните следующее краткое руководство. Создайте экземпляр Azure Управление API.

• Azure CLI

  • Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см . в кратком руководстве по Bash в Azure Cloud Shell.

    

  • Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.

    • Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других возможностях, доступных при входе, см. в статье Вход с помощью Azure CLI.

    • Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений с Azure CLI.

    • Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

• Azure PowerShell

  • Если вы решили использовать Azure PowerShell локально:
    • Установите последнюю версию модуля Az PowerShell.
    • Подключитесь к учетной записи Azure с помощью командлета Connect-AzAccount.
  • Если вы решили использовать Azure Cloud Shell:
    • Дополнительные сведения см. в статье Общие сведения об Azure Cloud Shell.

Импорт внутреннего API

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

Портал

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

2. В меню слева выберите API>+ Добавить API.

3. В разделе Создание из определения выберите OpenAPI.

   

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

5. Нажмите кнопку создания.

Azure CLI

В следующем примере используется команда импорта apim api az для импорта спецификации OpenAPI из указанного URL-адреса в экземпляр Управление API с именем apim-hello-world. Чтобы импортировать путь к спецификации вместо URL-адреса, используйте --specification-path параметр.

# API Management service-specific details
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details
APIId="swagger-petstore"
APIPath="store"
SpecificationFormat="OpenAPI"
SpecificationURL="https://petstore3.swagger.io/api/v3/openapi.json"

# Import API
az apim api import --path $APIPath --resource-group $ResourceGroupName \
    --service-name $APIMServiceName --api-id $APIId \
    --specification-format $SpecificationFormat --specification-url $SpecificationURL

После импорта API при необходимости можно обновить параметры с помощью команды az apim api update .

PowerShell

В следующем примере используется командлет Import-AzApiManagementApi Azure PowerShell для импорта спецификации OpenAPI из указанного URL-адреса в экземпляр Управление API с именем apim-hello-world. Чтобы импортировать путь к спецификации вместо URL-адреса, используйте -SpecificationPath параметр.

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific details
$apiId = "swagger-petstore"
$apiPath = "store"
$specificationFormat = "OpenAPI"
$specificationUrl = "https://petstore3.swagger.io/api/v3/openapi.json"

# Get context of the API Management instance. 
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName

# Import API
Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath

После импорта API при необходимости можно обновить параметры с помощью командлета Set-AzApiManagementApi .

Просмотр и изменение спецификации OpenAPI

На портале используйте редактор спецификаций OpenAPI для просмотра, проверки или изменения спецификации для импортированного API.

Чтобы использовать редактор спецификаций OpenAPI, выполните следующие действия.

1. Перейдите к экземпляру Управления API на портале Azure.
2. В меню слева в разделе API выберите API<>>>All operations.
3. На вкладке "Конструктор " в интерфейсе выберите редактор спецификаций OpenAPI (значок карандаша). Спецификацию можно открыть в формате JSON или YAML.
4. Просмотрите или измените спецификацию по мере необходимости. Сохраните свои изменения.

Проверка схемы спецификации OpenAPI

Политики проверки Управление API можно настроить для проверки запросов и ответов (или элементов) в схеме в спецификации OpenAPI. Например, используйте политику проверки содержимого для проверки размера или содержимого текста запроса или ответа.

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

Операции можно вызывать непосредственно на портале, что позволяет администраторам просматривать и тестировать операции API.

1. Выберите API, созданный на предыдущем шаге.

2. Откройте вкладку Тест.

3. Выберите операцию. На странице отобразятся поля для параметров запроса и для заголовков.

   Примечание.

   В тестовой консоли Управление API автоматически заполняет заголовок Ocp-Apim-Subscription-Key и настраивает ключ подписки встроенной подписки. Этот ключ обеспечивает доступ к каждому API в Управление API экземпляре. При необходимости отобразится заголовок Ocp-Apim-Subscription-Key, щелкнув значок "глаз" рядом с HTTP-запросом.

4. В зависимости от операции введите значения параметров запроса, значения заголовков или текст запроса. Выберите Отправить.

   При успешном выполнении теста серверная часть отвечает с помощью успешного кода ОТВЕТА HTTP и некоторых данных.

   Совет

   По умолчанию тестовая консоль отправляет запрос на прокси-сервер CORS Управление API, который перенаправляет запрос в экземпляр Управление API, который затем перенаправляет его в серверную часть. Этот прокси-сервер использует общедоступный IP-адрес 13.91.254.72 и может получать доступ только к общедоступным конечным точкам. Если вы хотите отправить запрос непосредственно из браузера в службу Управление API, выберите "Обход прокси CORS". Используйте этот параметр, если вы хотите использовать тестовую консоль, а шлюз Управление API изолирован от сети или не разрешает трафик из прокси-сервера CORS.

Сведения об отладке API см. в руководстве по отладке API с помощью трассировки запросов.

Добавление других интерфейсов API

Вы можете составить API из API, предоставляемых различными службами, включая:

• Спецификация OpenAPI
• A SOAP API
• A GraphQL API
• Веб-приложение, размещенное в Службе приложений Azure
• Приложение-функция Azure
• Приложения логики Azure
• Azure Service Fabric

Добавьте другой API к уже существующему API, выполнив следующие действия.

Примечание.

После импорта другого API операции добавляются к текущему API.

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

   

2. Выберите API на странице Обзор или в меню слева.

   

3. Щелкните ...рядом с API, к которому нужно добавить другой API.

4. В раскрывающемся меню выберите Импорт.

   

5. Выберите службу, из которой следует импортировать API.

   

См. также

• Ограничения импорта API
• Импорт спецификации OpenAPI
• Импорт SOAP API
• Импорт SOAP API и его преобразование в REST
• Импорт API Службы приложений
• Импорт API контейнерного приложения
• Импорт API WebSocket
• Импорт API GraphQL
• Импорт схемы GraphQL и настройка сопоставителей полей
• Импорт приложения-функции Azure
• Импорт приложения логики Azure
• Импорт службы Service Fabric
• Импорт API OpenAI Azure
• Импорт API OData
• Импорт метаданных SAP OData
• Импорт API gRPC
• Изменение API

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

• Создание и публикация продукта
• Преобразование и защита опубликованного API