チュートリアル:製品を作成して発行する

[アーティクル]
10/25/2024

適用対象: すべての API Management レベル

Azure API Management の "製品" には、少なくとも 1 つの API と、使用量クォータや利用規約が含まれています。製品が発行された後、開発者は製品をサブスクライブして、製品の API の利用を開始できます。

このチュートリアルでは、以下の内容を学習します。

製品を作成して発行する
製品に API を追加する
製品の API にアクセスする

ポータルにおける API Management の製品

前提条件

Azure API Management の用語について学習します。
次のクイックスタートを完了すること:Azure API Management インスタンスを作成する。
また、次のチュートリアルを完了すること: 最初の API のインポートと発行。

Azure portal にサインインして、API Management インスタンスに移動します。
左側のナビゲーションペインで、[製品]>[+ 追加] を選択します。

[製品の追加] ウィンドウで、以下の表に記載されている値を入力して製品を作成します。

製品ウィンドウを追加する

名前	説明
表示名	開発者ポータルで表示する名前です。
説明	製品の目的、アクセスできる API、その他の詳細など、製品に関する情報を入力します。
都道府県	開発者ポータルに製品を発行する場合は、[発行済み] を選択します。製品に含まれる API を開発者が検出できるようにするには、あらかじめ製品を発行しておく必要があります。既定では、新しい製品は発行されません。
サブスクリプションを要求する	ユーザーが製品を使用するためにサブスクライブする必要があり (製品が "保護されて" おり)、サブスクリプションキーを使用して製品の API にアクセスする必要がある場合に選択します。サブスクリプションが必要ない (製品が "オープン" である) 場合、製品の API にアクセスするためにサブスクリプションキーは必要ありません。この記事の後半の「製品の API にアクセスする」を参照してください。
承認が必要	この製品に対するサブスクリプションの申し込みを管理者の審査の下で承認または拒否する場合はオンにします。オフの場合、サブスクリプションの申し込みは自動承認されます。
サブスクリプション数の制限	必要に応じて、複数同時に利用できるサブスクリプションの数を制限します。
法的条項	サブスクライバーが製品を使用するにあたって同意する必要がある製品の使用条件を入力できます。
API	1 つまたは複数の API を選択します。製品の作成後に API を追加することもできます。詳細については、「製品への API の追加」を参照してください。製品がオープンである (サブスクリプションが必要ない) 場合は、別のオープンな製品に関連付けられていない API のみを追加できます。

[作成] を選択して新しい製品を作成します。

注意事項

サブスクリプションを必要としない製品を構成する場合は注意が必要です。この構成では制限が過度に緩められ、製品の API が特定の API セキュリティの脅威に対してより脆弱になるおそれがあります。

Azure CLI の使用を開始するには:

Azure Cloud Shell で Bash 環境を使用します。詳細については、「Azure Cloud Shell の Bash のクイックスタート」を参照してください。
CLI リファレンスコマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。
- ローカルインストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。認証プロセスを完了するには、ターミナルに表示される手順に従います。その他のサインインオプションについては、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`	サブスクライバーが製品を使用するために同意する必要がある、製品の使用条件を含めることができます。

注意事項

現在の製品を表示するには、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 Management インスタンスで、 [製品] ウィンドウから製品を選択します。次の項目を追加または更新します。

アイテム	説明
設定	製品のメタデータと状態
API	製品に関連付けられている API
ポリシー	製品の API に適用されるポリシー
アクセス制御	開発者またはゲストに向けた製品の可視性
サブスクリプション	製品のサブスクライバー

製品への API の追加

製品には、1 つまたは複数の API が関連付けられています。多数の API を組み込み、開発者ポータルを通じてそれらを開発者に提供できます。製品の作成中、既存の API を追加することができます。複数の API を追加することも可能です。製品には後から API を追加できます。 [設定] ページを使用して追加することも、API の作成時に追加することもできます。

既存の製品に API を追加する

ポータル
Azure CLI

API Management インスタンスの左側のナビゲーションで [製品] を選択します。
製品を選択してから、[API] を選択します。
[+ API の追加] を選択します。
少なくとも 1 つの API を選択してから、[選択] を選択します。

既存の製品に API を追加する

マネージド API を表示するには、az apim api list コマンドを使用します。

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

製品に 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

追加を確認するには、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 Management インスタンスを作成した場合は、既に管理者になっているため、既定ですべての製品をサブスクライブしています。詳細については、「Azure API Management のサブスクリプション」を参照してください。

クライアントが有効な製品サブスクリプションキーを使用して API 要求を作成すると、API Management では要求を処理し、製品のコンテキストでのアクセスを許可します。製品のために構成されたポリシーとアクセス制御規則を適用できます。

ヒント

REST API または PowerShell コマンドを通じてカスタムサブスクリプションキーを使用して、製品へのユーザーのサブスクリプションを作成または更新できます。
オープンな製品 - 開発者は、サブスクリプションキーを使用せずにオープンな製品の API にアクセスできます。ただし、OAuth 2.0、クライアント証明書、呼び出し元 IP アドレスの制限など、API へのクライアントアクセスをセキュリティで保護する他のメカニズムを構成することもできます。

Note

オープンな製品は、開発者が学習したりサブスクライブしたりするための開発者ポータルには表示されません。これらは、管理者グループにのみ表示されます。サブスクリプションキーなしでアクセスできる API について開発者に通知するには、別のメカニズムを使用する必要があります。

クライアントでサブスクリプションキーを使用せずに API 要求を行う場合:
- API Management では、API がオープンな製品に関連付けられているかどうかを確認します。 API は、最大 1 つのオープンな製品に関連付けることができます。
- オープンな製品が存在する場合は、そのオープンな製品のコンテキストで要求を処理します。オープンな製品のために構成されたポリシーとアクセス制御規則を適用できます。

詳細については、サブスクリプションキーを使用する場合としない場合の API Management での要求の処理方法に関する記事をご覧ください。

次の手順

このチュートリアルでは、次の作業を行う方法を学びました。

製品を作成して発行する
製品に API を追加する
製品の API にアクセスする

次のチュートリアルに進みます。

空の API とAPI のモック応答を作成する

この記事では、Terraform を使用して、Azure API Management インスタンス、API、製品、グループに加え、製品と API、製品とグループの間の関連付けを作成します。

Terraform を使用すると、クラウドインフラストラクチャの定義、プレビュー、およびデプロイを行うことができます。 Terraform を使用する際は、HCL 構文を使って構成ファイルを作成します。 HCL 構文では、Azure などのクラウドプロバイダーと、クラウドインフラストラクチャを構成する要素を指定できます。構成ファイルを作成したら、"実行プラン" を作成します。これにより、インフラストラクチャの変更をデプロイ前にプレビューすることができます。変更を確認したら、実行プランを適用してインフラストラクチャをデプロイします。

Terraform の必要なバージョンと必要なプロバイダーを指定します。
リソースグループ名のプレフィックス、リソースグループの場所、API 定義インポートのコンテンツ形式と値の変数を定義します。
ランダムな名前のリソースグループを作成します。
ランダムな名前の API Management サービスを作成します。
ランダムな名前の API を作成します。
API Management サービスでランダムな名前の製品を作成します。
ランダムな名前のグループを作成します。
API を製品に関連付けます。
グループを製品に関連付けます。
リソースグループ、API Management サービス、API、製品、グループの名前などのランダム化された値を出力します。

前提条件

アクティブなサブスクリプションが含まれる Azure アカウントを作成します。無料でアカウントを作成できます。
Terraform をインストールおよび構成します。

Terraform コードを実装する

注意

この記事のサンプルコードは、Azure Terraform GitHub リポジトリにあります。 Terraform の現在および以前のバージョンのテスト結果を含むログファイルを表示できます。

Terraform を使用して Azure リソースを管理する方法を示すその他の記事とサンプルコードを参照してください。

サンプル Terraform コードをテストして実行するディレクトリを作成し、それを現在のディレクトリにします。

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
}

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
}

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 {}
}

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     = "http://conferenceapi.azurewebsites.net/?format=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 を実行して Azure API Management を表示します。


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

リソースをクリーンアップする

Terraform を使用して作成したリソースが不要になった場合は、次の手順を実行します。

terraform plan を実行して、destroy フラグを指定します。
```
terraform plan -destroy -out main.destroy.tfplan
```
重要なポイント:
- terraform plan コマンドは、実行プランを作成しますが、実行はしません。代わりに、構成ファイルに指定された構成を作成するために必要なアクションを決定します。このパターンを使用すると、実際のリソースに変更を加える前に、実行プランが自分の想定と一致しているかどうかを確認できます。
- 省略可能な -out パラメーターを使用すると、プランの出力ファイルを指定できます。 -out パラメーターを使用すると、レビューしたプランが適用内容とまったく同じであることが確実になります。
terraform apply を実行して、実行プランを適用します。
```
terraform apply main.destroy.tfplan
```

Azure での Terraform のトラブルシューティング

Azure で Terraform を使用する場合の一般的な問題のトラブルシューティング。

次のステップ

空の API と API のモック応答を作成します。

次の方法で共有

チュートリアル:製品を作成して発行する

前提条件

製品を作成して発行する

構成をさらに追加する

製品への API の追加

既存の製品に API を追加する

製品の API にアクセスする

次の手順

前提条件

Terraform コードを実装する

Terraform を初期化する

Terraform 実行プランを作成する

Terraform 実行プランを適用する

結果を確認する

リソースをクリーンアップする

Azure での Terraform のトラブルシューティング

次のステップ

フィードバック

その他のリソース