Руководство по создавать и публиковать продукт;

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

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

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

• Создание и публикация продукта
• добавлять API к продукту.
• Доступ к API продукта

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

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

Создание и публикация продукта

Портал

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

2. На панели навигации слева выберите Продукты>+ Добавить.

   

3. В окне Добавить продукт введите значения, описанные в следующей таблице, чтобы создать продукт.

   

   Имя	Описание
   Показать имя	Имя, которое будет отображаться на портале разработчика.
   Description	Укажите подробные сведения о продукте, например его назначение, интерфейсы API, к которым он предоставляет доступ, и другую информацию.
   Штат	Выберите "Опубликовано" , если вы хотите опубликовать продукт на портале разработчика. Прежде чем API-интерфейсы в продукте могут быть обнаружены разработчиками, продукт должен быть опубликован. По умолчанию новые продукты не публикуются.
   Требуется подписка	Выберите, требуется ли пользователю подписаться на продукт (продукт защищен), а ключ подписки должен использоваться для доступа к API продукта. Если подписка не требуется (продукт открыт), ключ подписки не требуется для доступа к API продукта. См. раздел Доступ к API продукта далее в этой статье.
   Запрос утверждения	Укажите, требуется ли, чтобы администратор рассматривал и принимал или отклонял попытки подписаться на этот продукт. Если флажок не установлен, попытки подписаться будут утверждаться автоматически.
   Ограничение числа подписок	При необходимости ограничьте число одновременных подписок.
   Юридические условия	Можно указать условия использования продукта, которые должны принимать подписчики, если они хотят использовать этот продукт.
   Программные интерфейсы	Выберите один или несколько API. Вы также можете добавить API после создания продукта. Дополнительные сведения см. в разделе Добавление API к продукту далее в этой статье. Если продукт открыт (не требует подписки), можно добавить только API, который не связан с другим открытым продуктом.

4. Щелкните Создать, чтобы создать новый продукт.

Внимание

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

Azure CLI

Чтобы начать работу с 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.

Чтобы создать продукт, выполните команду az apim product create.

az apim product create --resource-group apim-hello-word-resource-group \
    --product-name "Contoso product" --product-id contoso-product \
    --service-name apim-hello-world --subscription-required true \
    --state published --description "This is a test."

Вы можете указать разные значения для этого продукта:

Параметр	Описание
--product-name	Имя, которое будет отображаться на портале разработчика.
--description	Укажите подробные сведения о продукте, например его назначение, интерфейсы API, к которым он предоставляет доступ, и другую информацию.
--state	Выберите публикацию, если вы хотите опубликовать продукт на портале разработчика. Прежде чем API-интерфейсы в продукте могут быть обнаружены разработчиками, продукт должен быть опубликован. По умолчанию новые продукты не публикуются.
--subscription-required	Выберите, требуется ли пользователю подписаться на продукт (продукт защищен) или подписка не требуется (продукт открыт). См. раздел Доступ к API продукта далее в этой статье.
--approval-required	Укажите, требуется ли, чтобы администратор рассматривал и принимал или отклонял попытки подписаться на этот продукт. Если флажок не установлен, попытки подписаться будут утверждаться автоматически.
--subscriptions-limit	При необходимости ограничьте число одновременных подписок.
--legal-terms	Можно указать условия использования продукта, которые должны принимать подписчики, если они хотят использовать этот продукт.

Внимание

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

Чтобы просмотреть текущие продукты, выполните команду az apim product list.

az apim product list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table

Чтобы удалить продукт, выполните команду az apim product delete:

az apim product delete --product-id contoso-product \
    --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --delete-subscriptions true

Добавление дополнительных конфигураций

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

Позиция	Description
Настройки	Метаданные и состояние продукта
Программные интерфейсы	API, связанные с продуктом
Политики	Политики, применяемые к API продукта
Управление доступом	Видимость продукта для разработчиков или гостей
Подписки	Подписчики продукта

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

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

Добавление API к существующему продукту

Портал

1. В области навигации экземпляра управления API слева выберите Продукты.
2. Выберите продукт, а затем выберите API.
3. Выберите Add API Key (Добавить ключ API).
4. Выберите один или несколько API, а затем нажмите Выбрать.

Azure CLI

1. Чтобы просмотреть управляемые API, выполните команду az apim api list:

   az apim api list --resource-group apim-hello-word-resource-group \
       --service-name apim-hello-world --output table
   

2. Чтобы добавить API в продукт, выполните команду az apim product api add:

   az apim product api add --resource-group apim-hello-word-resource-group \
       --api-id demo-conference-api --product-id contoso-product \
       --service-name apim-hello-world
   

3. Чтобы проверить добавление, выполните команду az apim product api list:

   az apim product api list --resource-group apim-hello-word-resource-group \
       --product-id contoso-product --service-name apim-hello-world --output table
   

Чтобы удалить API из продукта, выполните команду az apim product api delete :

az apim product api delete --resource-group apim-hello-word-resource-group \
    --api-id demo-conference-api --product-id contoso-product \
    --service-name apim-hello-world

Доступ к API продукта

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

• Защищенный продукт — разработчики должны сначала подписаться на защищенный продукт, чтобы получить доступ к API продукта. После этого они получат ключ подписки, который подходит для доступа к любому API в этом продукте. Создавая экземпляр Управления API, вы автоматически становитесь его администратором. Поэтому вы по умолчанию будете подписаны на все соответствующие продукты. См. дополнительные сведения о Подписках в службе Управления API Azure.

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

  Совет

  Подписку пользователя на продукт с индивидуальными ключами подписки можно создать или обновить с помощью REST API или команды PowerShell.

• Открыть продукт — разработчики могут получить доступ к API открытого продукта без ключа подписки. Однако вы можете настроить другие механизмы для защиты клиентского доступа к API, включая OAuth 2.0, сертификаты клиента и ограничение IP-адресов вызывающего абонента.

  Примечание.

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

  Когда клиент выполняет запрос API без ключа подписки:

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

  • Если открытый продукт существует, он обрабатывает запрос в контексте открытого продукта. Политики и правила управления доступом, настроенные для продукта, можно применить.

Дополнительные сведения см. в статье о том, как Управление API обрабатывает запросы с ключами подписки или без нее.

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

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

• Создание и публикация продукта
• добавлять API к продукту.
• Доступ к API продукта

Перейдите к следующему руководству:

Create blank API and mock API responses (Создание пустого API и имитация ответов API)

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

Terraform поддерживает определение, предварительный просмотр и развертывание облачной инфраструктуры. С помощью Terraform можно создавать файлы конфигурации с применением синтаксиса HCL. Синтаксис HCL позволяет указать поставщика облачных служб, например Azure, и элементы, составляющие облачную инфраструктуру. После создания файлов конфигурации создается план выполнения, который позволяет предварительно просматривать изменения инфраструктуры до их развертывания. После проверки изменений примените план выполнения для развертывания инфраструктуры.

• Укажите требуемую версию Terraform и необходимые поставщики.
• Определите переменные для префикса имени группы ресурсов, расположения группы ресурсов и формата содержимого и значения импорта определения API.
• Создайте группу ресурсов со случайным именем.
• Создайте службу Управление API со случайным именем.
• Создайте API со случайным именем.
• Создайте продукт со случайным именем в службе Управление API.
• Создайте группу со случайным именем.
• Свяжите API с продуктом.
• Свяжите группу с продуктом.
• Выводит случайные значения, такие как имена группы ресурсов, Управление API службы, API, продукта и группы.

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

• Создайте учетную запись Azure с активной подпиской. Вы можете создать учетную запись бесплатно.

• Установите и настройте Terraform.

Реализация кода Terraform

Примечание.

Пример кода для этой статьи находится в репозитории Azure Terraform GitHub. Вы можете просмотреть файл журнала, содержащий результаты теста из текущих и предыдущих версий Terraform.

Дополнительные статьи и пример кода, демонстрирующие использование Terraform для управления ресурсами Azure.

1. Создайте каталог для тестирования и выполнения примера кода Terraform и сделайте его текущим каталогом.

2. Создайте файл с именем main.tfи вставьте следующий код:

   resource "random_pet" "rg_name" {
     prefix = var.resource_group_name_prefix
   }
   
   resource "azurerm_resource_group" "rg" {
     location = var.resource_group_location
     name     = random_pet.rg_name.id
   }
   
   resource "random_string" "apim_service_name" {
     length  = 8
     lower   = true
     numeric = false
     special = false
     upper   = false
   }
   
   resource "azurerm_api_management" "apim_service" {
     name                = "${random_string.apim_service_name.result}-apim-service"
     location            = azurerm_resource_group.rg.location
     resource_group_name = azurerm_resource_group.rg.name
     publisher_name      = "Example Publisher"
     publisher_email     = "publisher@example.com"
     sku_name            = "Developer_1"
     tags = {
       Environment = "Example"
     }
     policy {
       xml_content = <<XML
       <policies>
         <inbound />
         <backend />
         <outbound />
         <on-error />
       </policies>
   XML
     }
   }
   
   resource "random_string" "api_name" {
     length  = 8
     lower   = true
     numeric = false
     special = false
     upper   = false
   }
   
   resource "random_string" "content_value" {
     length  = 8
     lower   = true
     numeric = false
     special = false
     upper   = false
   }
   
   resource "azurerm_api_management_api" "api" {
     name                = "${random_string.api_name.result}-api"
     resource_group_name = azurerm_resource_group.rg.name
     api_management_name = azurerm_api_management.apim_service.name
     revision            = "1"
     display_name        = "${random_string.api_name.result}-api"
     path                = "example"
     protocols           = ["https", "http"]
     description         = "An example API"
     import {
       content_format = var.open_api_spec_content_format
       content_value  = var.open_api_spec_content_value
     }
   }
   
   resource "random_string" "product_name" {
     length  = 8
     lower   = true
     numeric = false
     special = false
     upper   = false
   }
   
   resource "azurerm_api_management_product" "product" {
     product_id            = "${random_string.product_name.result}-product"
     resource_group_name   = azurerm_resource_group.rg.name
     api_management_name   = azurerm_api_management.apim_service.name
     display_name          = "${random_string.product_name.result}-product"
     subscription_required = true
     approval_required     = false
     published             = true
     description           = "An example Product"
   }
   
   resource "random_string" "group_name" {
     length  = 8
     lower   = true
     numeric = false
     special = false
     upper   = false
   }
   
   resource "azurerm_api_management_group" "group" {
     name                = "${random_string.group_name.result}-group"
     resource_group_name = azurerm_resource_group.rg.name
     api_management_name = azurerm_api_management.apim_service.name
     display_name        = "${random_string.group_name.result}-group"
     description         = "An example group"
   }
   
   resource "azurerm_api_management_product_api" "product_api" {
     resource_group_name = azurerm_resource_group.rg.name
     api_management_name = azurerm_api_management.apim_service.name
     product_id          = azurerm_api_management_product.product.product_id
     api_name            = azurerm_api_management_api.api.name
   }
   
   resource "azurerm_api_management_product_group" "product_group" {
     resource_group_name = azurerm_resource_group.rg.name
     api_management_name = azurerm_api_management.apim_service.name
     product_id          = azurerm_api_management_product.product.product_id
     group_name          = azurerm_api_management_group.group.name
   }
   

3. Создайте файл с именем outputs.tfи вставьте следующий код:

   output "resource_group_name" {
     value = azurerm_resource_group.rg.name
   }
   
   output "apim_service_name" {
     value = azurerm_api_management.apim_service.name
   }
   
   output "api_name" {
     value = azurerm_api_management_api.api.name
   }
   
   output "product_name" {
     value = azurerm_api_management_product.product.product_id
   }
   
   output "group_name" {
     value = azurerm_api_management_group.group.name
   }
   
   output "service_id" {
     description = "The ID of the API Management Service created"
     value       = azurerm_api_management.apim_service.id
   }
   
   output "gateway_url" {
     description = "The URL of the Gateway for the API Management Service"
     value       = azurerm_api_management.apim_service.gateway_url
   }
   
   output "service_public_ip_addresses" {
     description = "The Public IP addresses of the API Management Service"
     value       = azurerm_api_management.apim_service.public_ip_addresses
   }
   
   output "api_outputs" {
     description = "The IDs, state, and version outputs of the APIs created"
     value = {
       id             = azurerm_api_management_api.api.id
       is_current     = azurerm_api_management_api.api.is_current
       is_online      = azurerm_api_management_api.api.is_online
       version        = azurerm_api_management_api.api.version
       version_set_id = azurerm_api_management_api.api.version_set_id
     }
   }
   
   output "product_id" {
     description = "The ID of the Product created"
     value       = azurerm_api_management_product.product.id
   }
   
   output "product_api_id" {
     description = "The ID of the Product/API association created"
     value       = azurerm_api_management_product_api.product_api.id
   }
   
   output "product_group_id" {
     description = "The ID of the Product/Group association created"
     value       = azurerm_api_management_product_group.product_group.id
   }
   

4. Создайте файл с именем providers.tfи вставьте следующий код:

   terraform {
     required_version = ">=1.0"
     
     required_providers {
       azurerm = {
         source  = "hashicorp/azurerm"
         version = "~>3.0"
       }
       random = {
         source  = "hashicorp/random"
         version = "~>3.0"
       }
     }
   }
   
   provider "azurerm" {
     features {}
   }
   

5. Создайте файл с именем variables.tfи вставьте следующий код:

   variable "resource_group_name_prefix" {
     type        = string
     default     = "rg"
     description = "Prefix of the resource group name that's combined with a random ID so name is unique in your Azure subscription."
   }
   
   variable "resource_group_location" {
     type        = string
     default     = "eastus"
     description = "Location of the resource group."
   }
   
   variable "open_api_spec_content_format" {
     type        = string
     default     = "swagger-link-json"
     description = "The format of the content from which the API Definition should be imported. Possible values are: openapi, openapi+json, openapi+json-link, openapi-link, swagger-json, swagger-link-json, wadl-link-json, wadl-xml, wsdl and wsdl-link."
     validation {
       condition     = contains(["openapi", "openapi+json", "openapi+json-link", "openapi-link", "swagger-json", "swagger-link-json", "wadl-link-json", "wadl-xml", "wsdl", "wsdl-link"], var.open_api_spec_content_format)
       error_message = "open_api_spec_content_format must be one of the following: openapi, openapi+json, openapi+json-link, openapi-link, swagger-json, swagger-link-json, wadl-link-json, wadl-xml, wsdl and wsdl-link."
     }
   }
   
   variable "open_api_spec_content_value" {
     type        = string
     default     = "https://petstore3.swagger.io/api/v3/openapi.json"
     description = "The Content from which the API Definition should be imported. When a content_format of *-link-* is specified this must be a URL, otherwise this must be defined inline."
   }
   

Инициализация Terraform

Запустите terraform init, чтобы инициализировать развертывание Terraform. Эта команда скачивает поставщик Azure, необходимый для управления ресурсами Azure.

terraform init -upgrade

Основные моменты:

• Параметр -upgrade обновляет необходимые подключаемые модули поставщика до последней версии, которая соответствует ограничениям версии конфигурации.

Создание плана выполнения Terraform

Чтобы создать план выполнения, выполните terraform plan.

terraform plan -out main.tfplan

Основные моменты:

• Команда terraform plan создает план выполнения, но не выполняет его. Вместо этого она определяет, какие действия необходимы для создания конфигурации, заданной в файлах конфигурации. Этот шаблон позволяет проверить, соответствует ли план выполнения вашим ожиданиям, прежде чем вы начнете вносить изменения в фактические ресурсы.
• Необязательный параметр -out позволяет указать выходной файл для плана. Использование параметра -out гарантирует, что проверяемый план полностью соответствует применяемому.

Применение плана выполнения Terraform

Выполните terraform apply, чтобы применить план выполнения к вашей облачной инфраструктуре.

terraform apply main.tfplan

Основные моменты:

• В примере terraform apply команды предполагается, что вы ранее выполнили.terraform plan -out main.tfplan
• Если для параметра -out указано другое имя файла, используйте то же имя в вызове к terraform apply.
• Если вы не использовали параметр -out, вызовите terraform apply без параметров.

Проверка результатов

Выполните командуaz apim show, чтобы просмотреть Управление API Azure:

az apim show --<apim_service_name> --<resource_group_name>

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

Если вам больше не нужны ресурсы, созданные через Terraform, выполните следующие действия:

1. Выполните команду terraform plan и укажите флаг destroy.

   terraform plan -destroy -out main.destroy.tfplan
   

   Основные моменты:

   • Команда terraform plan создает план выполнения, но не выполняет его. Вместо этого она определяет, какие действия необходимы для создания конфигурации, заданной в файлах конфигурации. Этот шаблон позволяет проверить, соответствует ли план выполнения вашим ожиданиям, прежде чем вы начнете вносить изменения в фактические ресурсы.
   • Необязательный параметр -out позволяет указать выходной файл для плана. Использование параметра -out гарантирует, что проверяемый план полностью соответствует применяемому.

2. Выполните команду terraform apply, чтобы применить план выполнения.

   terraform apply main.destroy.tfplan
   

Устранение неполадок с Terraform в Azure

Устранение распространенных проблем при использовании Terraform в Azure.

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

Создайте пустые ответы API и макеты API.