Compute Engine バージョニング ガイド: API、クライアント ライブラリ、ツール

このガイドでは、Compute Engine が REST API、クライアント ライブラリ、gcloud コマンドライン ツールでバージョンを管理する方法について説明します。このドキュメントでは、チャンネル ベースのバージョン管理（CBV）とインターフェース ベースのバージョン管理（IBV）の違いについて説明します。主に IBV に焦点を当てています。

始める前に

  • まだ設定していない場合は、認証を設定します。認証では、 Google Cloud サービスと API にアクセスするための ID が確認されます。ローカル開発環境からコードまたはサンプルを実行するには、次のいずれかのオプションを選択して Compute Engine に対する認証を行います。

    このページのサンプルをどのように使うかに応じて、タブを選択してください。

    コンソール

    Google Cloud コンソールを使用して Google Cloud サービスと API にアクセスする場合、認証を設定する必要はありません。

    gcloud

    1. Google Cloud CLI をインストールします。インストール後、次のコマンドを実行して Google Cloud CLI を初期化します。

      gcloud init

      外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

  • デフォルトのリージョンとゾーンを設定します。

    • REST

    このページの REST API サンプルをローカル開発環境で使用するには、gcloud CLI に指定した認証情報を使用します。

      Google Cloud CLI をインストールします。

      外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

    詳細については、 Google Cloud 認証ドキュメントの REST を使用して認証するをご覧ください。

チャンネル ベースのバージョニングとインターフェース ベースのバージョニング

Compute Engine API は、チャネルベースのバージョン管理（CBV）とインターフェースベースのバージョン管理（IBV）の 2 つのバージョン管理スキームをサポートしています。

  • チャンネル ベースのバージョニングでは、リリースは長期間にわたって使用され、インプレース アップデートが提供されます。Compute Engine は、v1、ベータ版、アルファ版の各チャンネルをサポートしています。

  • インターフェース ベースのバージョン管理では、個々のインターフェース、メソッド、リソースがバージョン管理され、増分的に独立して進化できます。

IBV は CBV に優先します。ただし、CBV の既存の実装は、IBV の導入や新しいバージョンによる影響を受けません。既存の API リリースを維持する場合は、CBV を引き続き使用できます。

IBV は、API の動作と、そのリクエストとレスポンスのペイロードが、意図した API バージョンに準拠していることを確認するのに役立ちます。IBV を使用するには、クエリ パラメータまたはヘッダーを使用して、リクエストで API バージョンを指定します。詳細については、API リクエストを作成するをご覧ください。

IBV を使用すると、次の特典が得られます。

  • 安定性の向上: IBV は、サービスが応答する必要がある API バージョンを指定できるようにすることで、実行中のアプリケーションを変化から保護します。
  • 変更の導入を制御する: IBV を使用すると、リクエストを処理するバージョンを選択できます。これにより、独自のスケジュールで新しいサービス機能にアップグレードできます。

バージョニング戦略の詳細については、API 改善提案 185 をご覧ください。

インターフェース ベースのバージョニング ポリシー

Compute Engine IBV API の各リリースは、インターフェースが個別にバージョンを変更する場合でも、同じサービス バージョンを共有するインターフェース変更のコレクションです。

Compute Engine IBV API は、安定版とプレビュー版をサポートしています。

安定版

ほとんどの API リリースは安定版です。安定版は AIP-180 で定義されている厳格な互換性を維持します。つまり、同じバージョンの新しい安定版リリースでは、既存の機能が壊れたり、コードの書き換えが必要になったりすることはありません。

Compute Engine は、YYYY-MM-DD 形式（2026-09-01 など）の標準日付を使用して安定版の API バージョンを識別します。日付が新しいほど、新しいリリースであることを示します。

Compute Engine は、安定版を長期間サポートしているため、本番環境システムは信頼性が高く、中断されません。ほとんどのアプリケーションでは、1 つの安定版を使用するだけで日常的なタスクを実行できます。

プレビュー バージョン

Compute Engine は、新機能に関するユーザーからの早期のフィードバックを収集するために、プレビュー バージョンをリリースすることがあります。プレビュー リリースでは、日付に -preview タグが追加されます（例: 2026-10-01-preview）。

プレビュー バージョンには、最新の安定版のすべての機能に加えて、新しく追加された試験運用版の機能が含まれています。プレビュー版を使用する場合は、次の点に注意してください。

  • プレビュー機能は、以前のリリースや今後のリリースとの互換性を保証するものではありません。
  • ミッション クリティカルな本番環境にプレビュー バージョンを使用することはおすすめしません。
  • プレビュー機能は、安定版に昇格する際に変更、改良、削除されることがあります。

プレビュー バージョンは、新機能を試して、安定版のリリース時にコードを更新する予定がある場合に使用します。

リクエストで API バージョンを指定する

IBV を使用して API 呼び出しを行うには、リクエストでクエリ パラメータまたはヘッダーを使用してターゲット バージョンを指定します。API リクエストを行う方法の例については、API リクエストを作成するをご覧ください。

Cloud クライアント ライブラリ

Cloud クライアント ライブラリを使用すると、未加工の REST 呼び出しの構築と解析の負担が軽減されます。各ライブラリ リリースは、特定の日付ベースの API バージョンに直接接続します。

新機能にアクセスするには、Cloud クライアント ライブラリ パッケージを最新リリースに更新します。更新された Cloud クライアント ライブラリは、新しい安定版とプレビュー版の API リリースとともに公開されます。

本番環境のアプリケーションは安定版の Cloud クライアント ライブラリで実行し、プレビュー版のライブラリはテスト環境に分離することをおすすめします。

Google Cloud CLI（gcloud）

gcloud CLI を使用すると、個々の REST エンドポイントを手動で追跡することなく、Compute Engine リソースを管理できます。

gcloud CLI は、コマンドを次の 2 つのカテゴリに分類します。

  • 安定版コマンド: 標準コマンド（gcloud compute instances create など）は、安定版 API バージョンを対象とします。これらのコマンドは完全にサポートされており、予測可能であるため、本番環境のスクリプトにおすすめします。
  • プレビュー コマンド: 早期アクセス機能では gcloud preview グループ（gcloud preview compute ... など）を使用します。これらのコマンドは、最終リリース前にコントラクトが変更される可能性があるため、簡単な警告を表示します。

Terraform

Google Cloud Terraform プロバイダは API のバージョニングを抽象化し、基盤となる API のインタラクションを管理します。Terraform 構成では、バージョン ヘッダーの手動設定は公開されず、必要ありません。

新機能にアクセスするには、 Google Cloud Terraform プロバイダを最新リリースに更新します。プレビュー機能には、google-beta プロバイダを使用します。

よくある質問

このセクションでは、Compute Engine API のバージョン管理に関するよくある質問について説明します。

  • v1（CBV）から IBV に移行する必要がありますか？

    いいえ。既存の CBV v1 API リクエストは、これまでどおりに機能します。ただし、IBV API で利用可能な新機能にはアクセスできません。

  • IBV API バージョンのサポート期間はどれくらいですか？

    安定版は、標準の Google Cloud非推奨ポリシーに基づいて永続的に維持されます。

  • IBV API の新しいバージョンはどのくらいの頻度でリリースされますか？

    新しい IBV API バージョンは、四半期ごとのリリースで計画されています。プレビュー版はいつでもリリースできます。

  • Google Cloud コンソールで何かを有効にする必要がありますか？

    いいえ。IBV API は、Compute Engine API でデフォルトで有効になっています。

  • リクエストでバージョンを指定しないとどうなりますか？

    リクエストはデフォルトで CBV v1 エンドポイントに送信されます。

  • Cloud Audit Logs エントリで API バージョンを確認するにはどうすればよいですか？

    API バージョンは、protoPayload.requestMetadata.callerSuppliedUserAgent とリクエスト ヘッダーまたはクエリ パラメータに記録されます。

次のステップ

Compute Engine API の詳細については、次のドキュメントをご覧ください。