Azure API Management のバージョン

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

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

ほとんどの場合、各 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を参照できます。

元のバージョン

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

バージョンの表現方法

API Management では、 バージョン セットと呼ばれるリソースが保持されます。これは、1 つの論理 API のバージョンのセットを表します。 バージョン セットには、バージョン管理された API の表示名と、指定されたバージョンへの要求の転送に 使用されるバージョン管理スキーム が含まれます。

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

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

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

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

バージョン管理されていない API をバージョン管理された API に移行する

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

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

バージョンと改定

バージョンとリビジョンは、異なる機能です。 バージョン管理されていない API と同様に、各バージョンに複数のリビジョンを含めることができます。 バージョンを使用せずに、または逆の方法でリビジョンを使用できます。 通常、バージョンは破壊的変更がある API バージョンを分離するために使用され、リビジョンは API に対する軽微な変更と非破壊的変更に使用できます。

リビジョンに破壊的変更がある場合、またはリビジョンを正式にベータ/テスト バージョンに変換する場合は、リビジョンからバージョンを作成できます。 Azure portal で、[リビジョン] タブのリビジョン コンテキスト メニュー (...) で、このリビジョンから [バージョンの作成] を選択します。

開発者ポータル

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

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