チュートリアル:API の複数のバージョンを発行する
適用対象: すべての API Management レベル
API のすべての呼び出し元がまったく同じバージョンを使用するのは実用的ではない場合があります。 呼び出し元は、新しいバージョンにアップグレードするときに、わかりやすいアプローチを求めています。 このチュートリアルで示すように、Azure API Management で複数の "バージョン" を指定できます。
背景については、バージョンとリビジョンに関する記事をご覧ください。
このチュートリアルでは、以下の内容を学習します。
- 既存の API に新しいバージョンを追加する
- バージョン スキームを選択する
- バージョンを製品に追加する
- 開発者ポータルを参照してバージョンを確認する
前提条件
- Azure API Management の用語について学習します。
- 次のクイック スタートを完了すること:Azure API Management インスタンスを作成する。
- また、「Import and publish your first API (最初の API をインポートして発行する)」のチュートリアルも完了します。
新しいバージョンを追加する
- Azure portal で、API Management インスタンスに移動します。
- [API] を選択します。
- API の一覧で [Demo Conference API](デモ会議 API) を選択します。
- [Demo Conference API] の横のコンテキスト メニュー ( [...] ) を選択します。
- [バージョンの追加] を選択します。
![API コンテキスト メニュー - [バージョンの追加]](media/api-management-getstarted-publish-versions/add-version-menu.png)
ヒント
新しい API を作成するときに、複数のバージョンを有効にすることもできます。 [API の追加] 画面で、 [この API をバージョン管理しますか?] を選択します。
バージョン管理スキームを選択する
Azure API Management では、"バージョン管理スキーム" (パス、ヘッダー、またはクエリ文字列) を選択して、呼び出し元が API バージョンを指定する方法を選択します。 次の例では、バージョン管理スキームとして "パス" を使用しています。
以下の表の値を入力します。 次に、 [作成] を選択してバージョンを作成します。
| 設定 | 値 | 内容 |
|---|---|---|
| 名前 | demo-conference-api-v1 | API Management インスタンスでの一意の名前。 バージョンは、実際には API のリビジョンに基づく新しい API であるため、この設定は新しい API の名前になります。 |
| バージョン管理スキーム | パス | 呼び出し元が API バージョンを指定する方法。 |
| バージョン識別子 | v1 | バージョンのスキーム固有のインジケーター。 [パス] の場合、API の URL パスのサフィックスです。 [ヘッダー] または [クエリ文字列] を選択した場合は、追加の値 (ヘッダーの名前またはクエリ文字列パラメーター) を入力します。 使用例が表示されます。 |
| 成果物 | 無制限 | (省略可能) API バージョンが関連付けられている 1 つ以上の製品。 API を発行するには、API を成果物に関連付ける必要があります。 後でバージョンを製品に追加することもできます。 |
バージョンを作成すると、API 一覧の [Demo Conference API] の下に表示されます。 2 つの API (オリジナルと v1) が表示されています。
Note
バージョン管理されていない API にバージョンを追加すると、オリジナルも自動的に作成されます。 このバージョンは既定の URL で応答します。 オリジナル バージョンを作成することで、バージョンを追加するプロセスによって、既存のどの呼び出し元も中断されなくなります。 最初に複数のバージョンを有効にして新しい API を作成した場合には、オリジナルは作成されません。
バージョンを編集する
バージョンを追加した後、元のバージョンとは別の API としてバージョンを編集して構成できるようになりました。 あるバージョンの変更が別のバージョンに影響することはありません。 たとえば、API 操作を追加または削除し、OpenAPI 仕様を編集できます。 詳細については、「API の編集」を参照してください｡
バージョンを製品に追加する
呼び出し元が新しいバージョンを表示するためには、それが製品に追加されている必要があります。 バージョンを製品にまだ追加していない場合は、いつでも製品に追加できます。
たとえば、バージョンを無制限の製品に追加するには、次の手順に従います。
- Azure portal で、API Management インスタンスに移動します。
- [製品]>[無制限]>[API]>[+ 追加] の順に選択します。
- Demo Conference API のバージョン v1 を選択します。
- [選択] をクリックします。
バージョン セットを使用する
複数のバージョンを作成すると、Azure portal によって "バージョン セット" が作成されます。これは、1 つの論理的な API の一連のバージョンを表します。 複数のバージョンがある API の名前を選択します。 Azure portal に、そのバージョン セットが表示されます。 バージョン セットの名前と説明はカスタマイズできます。
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 api versionset list コマンドを実行します。
az apim api versionset list --resource-group apim-hello-world-resource-group \
--service-name apim-hello-world --output table
Azure portal によってバージョン セットが自動的に作成されると、英数字の名前が割り当てられ、一覧の [名前] 列に表示されます。 他の Azure CLI コマンドでこの名前を使用します。
バージョン セットの詳細を表示するには、az apim api versionset show コマンドを実行します。
az apim api versionset show --resource-group apim-hello-world-resource-group \
--service-name apim-hello-world --version-set-id 00000000000000000000000
バージョン セットの詳細については、「Azure API Management のバージョン」をご覧ください。
開発者ポータルを参照してバージョンを確認する
開発者ポータルを試したことがあれば、そこで API バージョンを確認できます。
- 上部のメニューから [開発者ポータル] を選択します。
- [API] を選択してから、[Demo Conference API](デモ会議 API) を選択します。
- API 名の横に複数のバージョンのドロップダウンが表示されます。
- [v1] を選択します。
- 一覧で最初の操作の [要求 URL] を確認します。 API の URL パスに "v1" が含まれています。
次の手順
このチュートリアルでは、以下の内容を学習しました。
- 既存の API に新しいバージョンを追加する
- バージョン スキームを選択する
- バージョンを製品に追加する
- 開発者ポータルを参照してバージョンを確認する
次のチュートリアルに進みます。