Azure API Management のバージョン

  • [アーティクル]

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

バージョンを使用すると、関連する API のグループを開発者に示すことができます。 バージョンを使用すると API の重大な変更を安全に処理できます。 クライアントは、準備ができたら新しい API バージョンを使用することを選択できます。その一方で、既存のクライアントは以前のバージョンを引き続き使用します。 バージョンは (ユーザーが選択する任意の文字列値である) バージョン識別子で区別されるため、バージョン管理スキームにより、クライアントは使用する API のバージョンを識別できます。

ほとんどの場合、各 API バージョンは独自の独立した API と見なすことができます。 2 つの異なる API バージョンが、異なる一連の操作と異なるポリシーを持っていることがあります。

バージョンを使用すると、次のことが可能になります。

  • API の複数のバージョンを同時に公開する。
  • パス、クエリ文字列、またはヘッダーを使用してバージョンを区別する。
  • 任意の文字列値を使用してバージョンを識別する。これには、番号、日付、または名前を使用できます。
  • 開発者ポータルにグループ化された API バージョンを表示する。
  • 既存の (バージョン管理されていない) API を取得し、既存のクライアントを中断することなく、その新しいバージョンを作成する。

このチュートリアルに従って、バージョンの使用を開始してください。

バージョン管理スキーム

バージョン管理の要件は API 開発者ごとに異なります。 Azure API Management では、バージョン管理への 1 つのアプローチが規定されているわけではなく、代わりに複数のオプションが提供されます。

パス ベースのバージョン管理

パス バージョン管理スキームが使用されている場合は、すべての API 要求の URL パスにバージョン識別子を含める必要があります。

たとえば、https://apis.contoso.com/products/v1 と https://apis.contoso.com/products/v2 は同じ products API ではあっても、それぞれバージョン v1 と v2 を参照できます。

パスベースのバージョン管理を使用している場合の API 要求 URL の形式は https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId} です。

ヘッダー ベースのバージョン管理

ヘッダー バージョン管理スキームが使用されている場合は、すべての API 要求の HTTP 要求ヘッダーにバージョン識別子を含める必要があります。 HTTP 要求ヘッダーの名前を指定できます。

たとえば、Api-Version という名前のカスタム ヘッダーを作成すると、クライアントはこのヘッダーの値に v1 または v2 を指定できます。

クエリ文字列ベースのバージョン管理

クエリ文字列バージョン管理スキームが使用されている場合は、すべての API 要求のクエリ文字列パラメーターにバージョン識別子を含める必要があります。 クエリ文字列パラメーターの名前を指定できます。

クエリ文字列ベースのバージョン管理を使用している場合の API 要求 URL の形式は https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier} です。

たとえば、https://apis.contoso.com/products?api-version=v1 と https://apis.contoso.com/products?api-version=v2 は同じ products API ではあっても、それぞれバージョン v1 と v2 を参照できます。

Note

OpenAPI 仕様の servers プロパティには、クエリ パラメーターは使用できません。 API バージョンから OpenAPI 仕様をエクスポートした場合、クエリ文字列はサーバー URL に表示されません。

元のバージョン

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

バージョンを表す方法

Azure API Management には、1 つの論理的な API の一連のバージョンを表す、バージョン セットと呼ばれるリソースが保持されています。 バージョン セットには、バージョン管理された API の表示名と、指定されたバージョンに要求を送信するために使用されるバージョン管理スキームが含まれています。

API の各バージョンは独自の API リソースとして保持された後、バージョン セットに関連付けられます。 バージョン セットには、操作またはポリシーが異なる API が含まれている場合があります。 セット内のバージョン間で大幅な変更を行う場合があります。

Azure portal によって、バージョン セットが作成されます。 Azure portal でバージョン セットの名前と説明を変更できます。

バージョン セットは、最終バージョンが削除されると自動的に削除されます。

Azure CLI、Azure PowerShell、Resource Manager テンプレート、または Azure Resource Manager API を使用して、バージョン セットを直接表示および管理できます。

Note

バージョンセット内のすべてのバージョンは、API にバージョンを最初に追加したときに使用されたバージョン管理スキームに基づいて、同じバージョン管理スキームを持ちます。

バージョン管理されていない API からバージョン管理された API への移行

Azure portal を使用して既存の API でバージョン管理を有効にすると、API Management リソースに次の変更が加えられます。

  • 新しいバージョン セットが作成されます。
  • 既存のバージョンは保持され、Original API バージョンとして構成されます。 この API はバージョン セットにリンクされますが、バージョン識別子を指定する必要はありません。
  • 新しいバージョンが新しい API として作成され、バージョン セットにリンクされます。 この新しい API には、バージョン管理スキームと識別子を使用してアクセスする必要があります。

バージョンとリビジョン

バージョンとリビジョンは別個の機能です。 各バージョンは、バージョン管理されていない API と同じように、複数のリビジョンを持つことができます。 リビジョンは、バージョンを使用せずに使用することも、その他の方法で使用することもできます。 通常、バージョンは、破壊的変更のある API のバージョンを区別するために使用される一方、リビジョンは、API に軽微な変更および非破壊的変更を加えるために使用されます。

リビジョンに破壊的変更があることが判明した場合、またはリビジョンを正式にベータ バージョンまたはテスト バージョンに変更する場合は、リビジョンからバージョンを作成することができます。 Azure portal を使用して、[リビジョン] タブのリビジョン コンテキスト メニューで [Create Version from Revision]\(リビジョンからバージョンを作成\) をクリックします。

[開発者ポータル]

開発者ポータルには、API の各バージョンが個別に一覧表示されます。

バージョン管理された API の一覧を表示している API Management 開発者ポータル

API の詳細には、その API のすべてのバージョンの一覧も表示されます。 Original バージョンは、バージョン識別子なしで表示されます。

API の詳細とその API のバージョンの一覧を表示している API Management 開発者ポータル

ヒント

API バージョンが開発者ポータルに表示されるには、そのバージョンを製品に追加しておく必要があります。