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

API のすべての呼び出し元がまったく同じバージョンを使用するのは実用的ではない場合があります。 呼び出し元は、新しいバージョンにアップグレードするときに、わかりやすいアプローチを求めています。 このチュートリアルで示すように、Azure API Management で複数の "バージョン" を提供できます。

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

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

  • 既存の API に新しいバージョンを追加する
  • バージョン スキームを選択する
  • バージョンを製品に追加する
  • 開発者ポータルを参照してバージョンを確認する

Azure portal に表示されたバージョン

前提条件

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

  1. Azure portal で、API Management インスタンスに移動します。
  2. [API] を選択します。
  3. API の一覧で [Demo Conference API](デモ会議 API) を選択します。
  4. [Demo Conference API] の横のコンテキスト メニュー ( [...] ) を選択します。
  5. [バージョンの追加] を選択します。

API コンテキスト メニュー - [バージョンの追加]

ヒント

新しい 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) が表示されています。

Azure Portal の API の下に表示された複数のバージョン

オリジナル とは別の API として、v1 を編集し、構成できます。 あるバージョンの変更が別のバージョンに影響することはありません。

注意

バージョン管理されていない API にバージョンを追加すると、オリジナル も自動的に作成されます。 このバージョンは既定の URL で応答します。 オリジナル バージョンを作成することで、バージョンを追加するプロセスによって、既存のどの呼び出し元も中断されなくなります。 最初に複数のバージョンを有効にして新しい API を作成した場合には、オリジナルは作成されません。

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

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

たとえば、バージョンを 無制限 の製品に追加するには、次の手順に従います。

  1. Azure portal で、API Management インスタンスに移動します。
  2. [製品] > [無制限] > [API] > [+ 追加] の順に選択します。
  3. Demo Conference API のバージョン v1 を選択します。
  4. [選択] をクリックします。

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

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

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

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

  • Azure Cloud Shell で Bash 環境を使用します。

    新しいウィンドウで Cloud Shell を起動する

  • 必要に応じて、Azure CLI をインストールして、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-word-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-word-resource-group \
    --service-name apim-hello-world --version-set-id 00000000000000000000000

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

開発者ポータルを参照してバージョンを確認する

開発者ポータルを試したことがあれば、そこで API バージョンを確認できます。

  1. 上部のメニューから [開発者ポータル] を選択します。
  2. [API] を選択してから、[Demo Conference API](デモ会議 API) を選択します。
  3. API 名の横に複数のバージョンのドロップダウンが表示されます。
  4. [v1] を選択します。
  5. 一覧で最初の操作の [要求 URL] を確認します。 API の URL パスに "v1" が含まれています。

次の手順

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

  • 既存の API に新しいバージョンを追加する
  • バージョン スキームを選択する
  • バージョンを製品に追加する
  • 開発者ポータルを参照してバージョンを確認する

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