チュートリアル:API の複数のバージョンを発行する

2025-06-23

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

すべての API コンシューマーが同じバージョンを使用するのは現実的でない場合があります。コンシューマーは、新しいバージョンにアップグレードする準備ができたら、シンプルでわかりやすいアプローチを好みます。このチュートリアルで示すように、Azure API Management では、このニーズに合わせて複数の API バージョンを公開できます。

背景については、「バージョンとリビジョン」をご覧ください。

ヒント

API チームは、ワークスペースでこの機能を使用できます。ワークスペースは、API と独自の API ランタイム環境への分離された管理アクセスを提供します。

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

既存の API に新しいバージョンを追加する
バージョンスキームを選択する
バージョンを製品に追加する
開発者ポータルでバージョンを表示する

前提条件

Azure API Management の用語について説明します。
クイックスタート「 Azure API Management インスタンスを作成する」を完了します。
チュートリアル「最初の API をインポートして発行する」を完了します。

新しいバージョンを追加する

Azure portal で、API Management インスタンスに移動します。
左側のメニューの [API ] セクションで、[API] を選択 します。
API リストで Swagger Petstore - OpenAPI 3.0 を見つけます。 Swagger Petstore - OpenAPI 3.0 の横にある省略記号 (...) を選択し、[バージョンの追加] を選択します。次のセクションで、結果のウィンドウに値を追加します。

ヒント

新しい API を作成するときにバージョンを有効にすることもできます。 [API の追加] 画面で、 [この API をバージョン管理しますか?] を選択します。

バージョン管理スキームを選択する

API Management では、呼び出し元が バージョン管理スキーム ( パス、 ヘッダー、または クエリ文字列) を選択して、API バージョンを指定する方法を選択します。次の例では、 バージョン 管理スキームとして Path が使用されています。

[ バージョンとして新しい API を作成 する] ウィンドウで、次の表の値を入力します。次に、 [作成] を選択してバージョンを作成します。

設定	値	説明
バージョン識別子	v1	バージョンのスキーム固有のインジケーター。 [パス] の場合、API の URL パスのサフィックスです。
バージョン管理スキーム	パス	呼び出し元が API バージョンを指定する方法。 [ヘッダー] または [クエリ文字列] を選択した場合は、ヘッダーまたはクエリ文字列パラメーターの名前という別の値を入力します。使用例が表示されます。
完全な API バージョン名	swagger-petstore-openapi-3-0-v1	API Management インスタンスでの一意の名前。バージョンは実際には API のリビジョンに基づく新しい API であるため、この値は新しい API の名前です。
製品	無制限 (一部のサービスレベルで提供)	(省略可能) API バージョンが関連付けられている 1 つ以上の製品。 API を発行するには、API を成果物に関連付ける必要があります。後でバージョンを製品に追加することもできます。

バージョンを作成すると、API リストの Swagger Petstore - OpenAPI 3.0 の下に表示されます。次の 2 つの API ( Original と v1) が表示されます。

注

バージョン管理されていない API にバージョンを追加すると、元のバージョンも自動的に作成されます。このバージョンは既定の URL で応答します。元のバージョンでは、既存の呼び出し元からの呼び出しは、バージョンの追加後も引き続き機能します。最初にバージョンが有効になっている新しい API を作成した場合、元の API は作成されません。

バージョンを編集する

バージョンを追加したら、元のバージョンとは別の API として編集および構成できます。あるバージョンに対する変更は、別のバージョンには影響しません (たとえば、API 操作を追加または削除したり、OpenAPI 仕様を編集したりする場合など)。詳細については、「API の編集」を参照してください｡

バージョンを製品に追加する

呼び出し元が新しいバージョンを表示するには、製品に追加する必要があります。製品にバージョンをまだ追加していない場合は、いつでも追加できます。

製品にバージョンを追加するには:

Azure portal で、API Management インスタンスに移動します。
左側のウィンドウの [API ] で、[ 製品] を選択します。
製品を選択し、左側のウィンドウで [API] を 選択します。
[+ 追加] を選択します。
API を選択します。
[選択] をクリックします。

バージョンセットを使用する

複数のバージョンを作成すると、Azure portal によって "バージョンセット" が作成されます。これは、1 つの論理的な API の一連のバージョンを表します。複数のバージョンを持つ API の名前を選択すると、ポータルにそのバージョンセットが表示されます。バージョンセットの名前と説明をカスタマイズできます。

Azure CLI を使用すると、バージョンセットを直接操作できます。

Azure Cloud Shell で Bash 環境を使用します。詳細については、「Azure Cloud Shell の概要」を参照してください。
CLI リファレンスコマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。
- ローカルインストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。認証プロセスを完了するには、ターミナルに表示される手順に従います。その他のサインインオプションについては、「 Azure CLI を使用した Azure への認証」を参照してください。
- 初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。拡張機能の詳細については、「Azure CLI で拡張機能を使用および管理する」を参照してください。
- az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。最新バージョンにアップグレードするには、az upgrade を実行します。

すべてのバージョンセットを表示するには、az apim api versionset list コマンドを実行します。

az apim api versionset list --resource-group <resource-group-name> \
    --service-name <API-Management-service-name> --output table

Azure portal によってバージョンセットが自動的に作成されると、英数字の名前が割り当てられ、一覧の [名前] 列に表示されます。他の Azure CLI コマンドでこの名前を使用します。

バージョンセットの詳細を表示するには、az apim api versionset show コマンドを実行します。

az apim api versionset show --resource-group <resource-group-name> \
    --service-name <API-Management-service-name> --version-set-id <ID from the Name column>

バージョンセットの詳細については、「Azure API Management のバージョン」をご覧ください。

開発者ポータルでバージョンを表示する

開発者ポータルを使用すると、そこに API のバージョンが表示されます。

ウィンドウの上部にある 開発者ポータル を選択します。
[API] を選択し、[Swagger Petstore] を選択します。
API 名の横に複数のバージョンが一覧表示されるドロップダウンが表示されます。
[v1] を選択します。
一覧で最初の操作の [要求 URL] を確認します。 API の URL パスに "v1" が含まれています。

次のステップ

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

開発者ポータルのページのスタイルをカスタマイズする