API のバージョニング

このページでは、API のバージョン番号を変更して構成とデプロイを行う詳細な手順を説明します。API に加える変更が下位互換性を維持するかどうかに応じて、使用する手順が異なります。

  • 下位互換性のある変更（新しいフィールドやメソッドの追加など）が新しいバージョンの API に含まれる場合は、下位互換性のある変更をご覧ください。
  • 新しい API で既存のメソッドを変更した結果、ユーザーのクライアント コードとの互換性がなくなる場合は、下位互換性のない変更をご覧ください。

詳細とベスト プラクティスについては、API のライフサイクル管理をご覧ください。

下位互換性のある変更

既存のクライアント コードとの下位互換性がある変更を API で行った場合は、新しいバージョンをデプロイする前に API のマイナー バージョン番号をインクリメントすることをおすすめします。Cloud Endpoints では一度に 1 つのマイナー バージョンの API のみが実行されますが、[エンドポイント] > [サービス] のグラフとログでバージョン番号が表示されます。マイナー バージョン番号をインクリメントしてからデプロイすることによって、グラフとログにデプロイのラベル付き履歴が表示されます。

マイナー バージョン番号をインクリメントするには:

  1. openapi.yaml で、info.version フィールドのマイナー バージョン番号をインクリメントします。たとえば、現在のバージョンが 1.1 の場合、info.version を 1.2 に設定します。

    info:
  description: "A simple Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.2"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

  2. Google Cloud CLI を使用して API 構成をデプロイします。

    gcloud endpoints services deploy openapi.yaml

  3. 前のステップで返された構成 ID を使用して API バックエンドをデプロイします。詳細については、API バックエンドをデプロイするをご覧ください。

下位互換性のない変更

ユーザーのクライアント コードとの互換性がない変更を API で行った場合は、API のメジャー バージョン番号をインクリメントすることをおすすめします。Endpoints では、API の複数のメジャー バージョンを同時に実行できます。両方のバージョンの API を提供することで、ユーザーは使用するバージョンを選択できます。また、新しいバージョンに移行するタイミングを管理することもできます。

既存のバージョンと新しいバージョンの API を同時に実行するには:

  1. 提供するバージョンそれぞれの OpenAPI 構成ファイルを作成します。この手順では、例としてファイル名 openapi-v1.yaml と openapi-v2.yaml を使用します。

  2. openapi-v1.yaml の内容を openapi-v2.yaml にコピーします。

  3. openapi-v1.yaml で、次のように構成します。

    • info.version フィールドに既存のバージョン番号を設定します。
    • basePath フィールドは変更せずにそのままにします。

    例:

    info:
  description: "A simple Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.1"
host: "echo-api.endpoints.example-project-12345.cloud.goog"
basePath: "/v1"

  4. openapi-v2.yaml で、次のように構成します。

    • 下位互換性のない変更を行います。
    • info.version フィールドに新しいバージョン番号を設定します。
    • basePath フィールドに新しいメジャー バージョン番号を設定します。
    • x-google-endpoints セクションを削除します。DNS IP アドレスまたは allowCors フラグを指定する場合、このセクションは必要です。2 つの yaml 構成ファイルを使用して 2 つのバージョンの API をデプロイする場合、そのうちの 1 つだけが x-google-endpoints を持つことができますが、構成ファイルは両方のバージョンに適用されます。

    例:

    info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "2.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"
basePath: "/v2"

  5. Google Cloud CLI を使用して、両方の API 構成ファイルをデプロイします。

    gcloud endpoints services deploy openapi-v1.yaml openapi-v2.yaml

  6. 前のステップで返された構成 ID を使用して、両方のバージョンの API を提供する単一のバックエンドをデプロイします。詳細については、API バックエンドをデプロイするをご覧ください。

次のステップ