バージョニング

このトピックでは、Google API で使用されるバージョニング戦略について説明します。通常、これらの戦略はすべての Google マネージドサービスに適用されます。

API に下位互換性のない（互換性を「破る」）変更を加える必要が生じることがあります。このような変更が原因で、元の機能で依存関係があるコードの問題や障害が発生する可能性があります。

Google API はバージョニングスキームを使用して、互換性を破る変更を防止します。さらに、Google API は、アルファコンポーネントやベータコンポーネントなど、特定の安定性レベルでのみ利用可能な一部の機能を提供します。

ガイダンス

すべての Google API インターフェースは、メジャーバージョン番号（protobuf パッケージの最後にエンコードされ、REST API の URI パスの最初の部分として含まれます）を提供する必要があります。API でフィールドの削除や名前変更など、互換性のない変更が行われた場合は、既存のユーザーコードが突然破損しないように、API のバージョン番号を増やす必要があります。

API の新しいメジャーバージョンは、同じ API の以前のメジャーバージョンに依存してはいけません。呼び出し元は、その API に関連する依存関係と安定性のリスクを理解していることを期待して、API は他の API に依存する場合があります。このシナリオでは、安定した API バージョンは他の API の安定したバージョンにのみ依存する必要があります。

同じ API の異なるバージョンは、適切な移行期間にわたって、単一のクライアントアプリケーション内で同時に動作できる必要があります。この期間により、クライアントは新しいバージョンにスムーズに移行できます。古いバージョンは、シャットダウンされる前に、十分に伝達された適切な非推奨期間を経過する必要があります。

アルファ版またはベータ版の安定性のリリースを行う場合、API では、protobuf パッケージと URI パスのメジャーバージョン番号の後に、安定性レベルを次のいずれかの方法で追加する必要があります。

チャンネルベースのバージョニング（推奨）
リリースベースのバージョニング
公開設定ベースのバージョニング

チャンネルベースのバージョニング

安定性チャンネルとは、インプレース更新を受け取る、指定された安定性レベルの長期リリースです。メジャーバージョンには、安定性レベルごとに複数のチャンネルはありません。この方法では、アルファ、ベータ、ステーブルの 3 つのチャンネルを使用できます。

アルファとベータのチャンネルは、安定性レベルをバージョンに追加しなければなりませんが、ステーブルチャンネルは安定性レベルを追加してはいけません。たとえば、ステーブルチャンネルでは、v1 は使用できるバージョンですが、v1beta や v1alpha は使用できません。同様に、v1beta または v1alpha は、ベータチャンネルとアルファチャンネルでは使用できるバージョンですが、v1 はどちらでも使用できません。これらの各チャンネルは新機能が追加されると「インプレース」で更新されます。

ベータチャンネルの機能は、ステーブルチャンネルの機能のスーパーセットである必要があります。アルファチャンネルの機能は、ベータチャンネルの機能のスーパーセットである必要があります。

API 機能の廃止

API 要素（フィールド、メッセージ、RPC）は、これ以上使用しないことを示すため、どのチャンネルでも廃止予定にマークされる可能性があります。

// Represents a scroll. Books are preferred over scrolls.
message Scroll {
  option deprecated = true;

  // ...
}

廃止予定の API 機能は、アルファからベータへも、ベータからステーブルへも移行しません。つまり、どのチャンネルにも機能の「事前の廃止予定」は到着しません。

ベータチャンネルの機能は、十分な期間廃止予定になった後に削除することができます。推奨期間は 180 日です。アルファチャネルにのみ存在する機能の場合、廃止予定はオプションで、機能を予告なく削除することができます。削除する前に API のアルファチャンネルで機能が廃止予定にされた場合、API は同じアノテーションを適用する必要があり、希望する任意の期間使用することができます。

リリースベースのバージョニング

個々のリリースは、その機能が安定したチャネルに組み込まれる前の限られた期間に利用可能になることが予想されるアルファ版またはベータ版のリリースであり、その後、個々のリリースはシャットダウンされます。リリースベースのバージョニング管理戦略を使用する場合、API は各安定性レベルで任意の数の個別のリリースを持つことができます。

アルファとベータのリリースでは、安定性レベルがバージョンに追加され、リリース番号がインクリメントされる必要があります。たとえば、v1beta1 や v1alpha5 です。API は、コメントなどのドキュメントで、これらのバージョンの時系列を記録する必要があります。

アルファまたはベータの各リリースは、下位互換性のある変更によってインプレースで更新される場合があります。ベータリリースの場合、下位非互換性の更新は、リリース番号をインクリメントして新しいリリースを公開することで実現することが推奨されます。たとえば、現在のバージョンが v1beta1 の場合、次は v1beta2 がリリースされます。

アルファとベータのリリースは、機能がステーブルチャンネルに到達した後には、シャットダウンされる必要があります。アルファリリースはいつでもシャットダウンできますが、ベータリリースではユーザーに合理的な移行期間を与えることが推奨されます。推奨期間は 180 日です。

公開設定ベースのバージョニング

API の公開設定は、Google API インフラストラクチャが提供する高度な機能です。これにより、API プロデューサーは 1 つの内部 API サーフェスから複数の外部 API ビューを公開でき、各ビューは次のような API 公開設定ラベルに関連付けられます。

import "google/api/visibility.proto";

message Resource {
  string name = 1;

  // Preview. Do not use this feature for production.
  string display_name = 2
    [(google.api.field_visibility).restriction = "PREVIEW"];
}

公開設定ラベルは、任意の API 要素のタグ付けに使用できる、大文字と小文字が区別される文字列です。慣例により、公開設定ラベルには常に大文字を使用する必要があります。上に示した例のように、明示的な公開設定ラベルが適用されていない限り、暗黙的な PUBLIC ラベルがすべての API 要素に適用されます。

各公開設定ラベルは許可リストです。API プロデューサーは、ラベルに関連付けられた API 機能を使用できるように、API コンシューマーに公開設定ラベルを付与する必要があります。つまり、API 公開ラベルは ACL が適用された API バージョンのようなものです。

複数の公開設定ラベルを、カンマ区切りの文字列（"PREVIEW,TRUSTED_TESTER" など）を使用して 1 つの要素に適用できます。複数の公開設定ラベルが使用されている場合、クライアントは公開設定ラベルの 1 つ（論理 OR）のみを必要とします。

1 つの API リクエストで使用できる公開設定ラベルは 1 つのみです。デフォルトでは、API コンシューマーに付与されている公開設定ラベルが使用されます。クライアントは、次のように明示的な公開ラベルを使用してリクエストを送信できます。

GET /v1/projects/my-project/topics HTTP/1.1
Host: pubsub.googleapis.com
Authorization: Bearer y29....
X-Goog-Visibilities: PREVIEW

API プロデューサーは、INTERNAL や PREVIEW などの API 公開設定を使用して API バージョニングを行うことができます。新しい API 機能は INTERNAL ラベルで始まり、PREVIEW ラベルに移行します。機能が安定して一般提供されると、すべての API 公開設定ラベルが API 定義から削除されます。

一般に、API の公開設定は増分変更に対する API のバージョニングと比較して実装が容易ですが、高度な API インフラストラクチャのサポートに依存します。Google Cloud APIs では多くの場合、プレビュー機能に API の公開設定が使用されます。