夜間にプロジェクト内のVMを一覧にして台帳と突き合わせるスクリプトや、停止し忘れたVMを探す監視の仕組みは、Compute EngineのAPIの「全ゾーンをまとめて一覧にする」呼び出し（aggregatedList）を使って作れます。このとき、どこか1つのゾーンで一時的な問題が起きると、一覧の取得そのものが失敗することがあります。逆に、失敗を避ける設定にすると、一部のゾーンが抜けた一覧が返ってきます。どちらの動きになるかは、APIの既定と呼び出し方で決まります。
Compute EngineのAPIの「日付で指定する版」は、リリースノートによると2026年9月29日に一般提供になり、2026年11月5日の公式ブログで詳しく告知されました。既存の /v1 はそのまま使えますが、新しい版ではこの一覧の既定などが変わります。本記事では、公式の資料と、編集部が版ごとのDiscovery文書とPythonのライブラリを比べた結果をもとに、既存の自動化で確かめる点を整理します。
日付の版の仕組み
ブログによると、Compute EngineのAPIはこれまで /v1（一般提供）、/beta、/alpha の3つの系統で提供されてきました。今回、これと並べて、日付を名前にした版が加わります。ドキュメントでは、この方式をinterface-based versioning（IBV）と呼んでいます。
- 安定版（YYYY-MM-DD）: 四半期ごとに公開され、最初の版は
2026-09-01。公開後に互換性を壊す変更は入らず、現時点でサポートの終了日はない - プレビュー版（YYYY-MM-DD-preview）: 安定版から分かれて、より短い間隔で公開される。期間は1年で、最初の版は
2026-10-01-preview。互換性は保証されず、ドキュメントは重要な本番環境での利用を勧めていない - /v1: 引き続き完全にサポートされ、版を指定しない場合の既定のまま。ただしドキュメントは、日付の版で提供される新機能は
/v1からは使えないとしている
版は、URLのパスではなく、HTTPヘッダー X-Goog-Api-Version か、クエリの $apiVersion で指定します。パスは /compute/v1/ のままなので、リソースの selfLink の形も変わりません。シェルの二重引用符の中では $apiVersion が変数として展開されるため、ドキュメントは %24apiVersion と書くよう案内しています。
新しい版で変わること
ブログは、日付の版で次の点が変わる、または変えられるようになると書いています。
- 全体の一覧が既定で部分成功になる。
/v1のaggregatedListはreturnPartialSuccessの既定がfalseで、1つのゾーンの一時的な問題で全体が失敗し得る。新しい版では部分成功が既定になる。リリースノートも、2026-09-01のaggregatedListは到達できない範囲があるときに既定で部分的な結果を返し、returnPartialSuccessはaggregatedListとlistのメソッドでは使えなくなった、と書いている - エラーが機械で読める形になる。
google.rpc.ErrorInfoに理由・領域・付随情報を入れる形式にそろえる。存在しない版を指定したときは、使える版の一覧を返す例が挙がっている - IAMの権限の確認を厳しくできる。 範囲の広すぎた従来の権限の確認を、新しい版で絞れるようになる
- 古いリソースの定義を整理できる。 APIの設計の指針（AIP）に沿った形へ、版を分けて移す道ができる
リリースノートに具体的に載っている変更は、2026-09-01 では1の部分成功です。2026-10-01-preview では、projects.get・regions.get・regions.list の応答から quotas がなくなり、割り当ての確認にはCloud Quotas APIを使うよう案内されています。
版ごとのDiscovery文書を比べた
ブログには「版ごとのDiscovery文書を取得できる」とあります。編集部は2026年11月5日に、認証なしで取得できるDiscovery文書を、版を変えて取得しました。11月6日に取り直しても、次の数字は同じでした。
version=2026-09-01とversion=2026-10-01-previewは取得でき、version=2099-01-01は「Discovery document not found」（404）になった- 3つとも
basePathは/compute/v1/で、revision は 20261026 - メソッドの数は、
/v1が1,018、2026-09-01が1,019、2026-10-01-previewが1,092。プレビュー版には安定版にない73のメソッドがある /v1では203のメソッド（list120、aggregatedList53 など）にあるreturnPartialSuccessの指定が、2026-09-01ではすべてなくなっている
最後の点は、ブログの「部分成功が既定」と、リリースノートの「returnPartialSuccess は使えなくなった」に一致します。新しい版では、そもそも部分成功を選ぶ指定がありません。一方で、2026-09-01 のDiscovery文書とRESTリファレンスでも、aggregatedList の説明文には「失敗を防ぐため returnPartialSuccess を true にすることを勧める」という従来の文が残っていました。定義と説明文がそろっていない状態なので、説明文だけを読んで判断しないほうが安全です。なお、リリースノートが既定で部分的な結果を返すと書いているのは aggregatedList で、list の挙動には触れていません。
気をつけたいのは「自動で版が変わる」経路
直接HTTPで呼んでいるスクリプトは、ヘッダーかクエリで版を指定しない限り /v1 のままです。注意が要るのは、ライブラリやツールの側で版が決まる経路です。ブログの表には次のように書かれています。
| 経路 | 版の決まり方 |
|---|---|
| クライアントライブラリ（Python・Go・Java・Node.js など） | ライブラリの各リリースが特定の日付の版に結び付く。パッケージ名（compute_v1 など）は変わらない |
| gcloud | gcloud compute は同梱の安定版を使う。新しい gcloud preview compute はプレビュー版を使う。既存の gcloud compute、beta、alphaのスクリプトはそのまま動くとされている |
| Terraform（google・google-beta） | google は安定版、google-beta はプレビュー版を内部で使う。HCLで版を指定する必要はない |
つまり、コードを1行も変えなくても、ライブラリやTerraformのプロバイダーを上げたときに、一覧の取得が部分成功に変わる可能性があります。どのリリースからどの版に結び付くかは、ブログには書かれていません。
Pythonのライブラリは1.55.0から切り替わっている
そこで、Pythonのクライアントライブラリ（google-cloud-compute）のPyPIの配布物を比べました。2026年9月17日の1.54.0までは版のヘッダーを送る処理がなく、10月1日の1.55.0から11月5日の1.57.0までの正式版には 2026-09-01 を送る処理が入っています。
編集部は1.54.0と1.57.0を検証用の仮想環境に入れて動かし、APIには接続せず、aggregated_list が送ろうとする内容だけを確かめました。
| 版 | 送るヘッダー | return_partial_success=True を指定したとき |
|---|---|---|
| 1.54.0 | 版のヘッダーなし | 受け付ける |
| 1.57.0 | x-goog-api-version: 2026-09-01 | ValueError（Unknown field）で止まる |
部分成功を明示して失敗を避けていたコードは、ライブラリを上げると、リクエストを作る時点で例外になります。1.55.0以降の配布物には、この指定の定義がありません。Node.jsの7.9.0の配布物とGoのmainブランチのソースにも、2026-09-01 を送る処理が入っていました。Terraformのプロバイダーがどの版を送るかは確かめられていません。
既存の自動化で確かめること（編集部の提案）
- 呼び出し元を洗い出す。 VMの一覧・棚卸し・停止の自動化が、直接HTTP・クライアントライブラリ・gcloud・Terraformのどれで呼んでいるかを一覧にする。ライブラリとプロバイダーの版も控える
- 部分成功の結果を捨てない。
aggregatedListの応答には、取得できなかった範囲を示すunreachablesがある（/v1と2026-09-01の両方の定義にある）。これが空でないときに警告を出す処理を、版を変える前に入れておく。抜けたゾーンに気づかないまま「VMはない」と判断するのが一番危ない - 検証環境でヘッダーを付けて試す。 本番の前に、
X-Goog-Api-Version: 2026-09-01を付けて同じ処理を動かし、件数とエラーの形を比べる - ライブラリの更新を版の更新として扱う。 依存関係の自動更新のPRでも、Compute Engineのライブラリとプロバイダーは、結び付く版を確かめてからマージする。
return_partial_successを指定している箇所も、更新の前に検索して外す
gcloud をAIのエージェントに操作させる場合の権限の考え方は、リモートMCPの権限設計の記事で扱いました。Terraformの運用を整える話は、OpenTofuとTerraformの記事も参照してください。
確認した範囲
2026年11月5日に、Google Cloud公式ブログの告知（同日公開）を取得し、原文と照合しました。11月6日に、Compute Engineのリリースノート、APIの版のガイド、リクエストの作り方の説明、
2026-09-01のRESTリファレンスとも照合しました（資料調査）。あわせて、Compute EngineのDiscovery文書（/v1、2026-09-01、2026-10-01-preview）を認証なしで取得し、メソッドとパラメーターを比べました。Pythonのライブラリ1.54.0と1.57.0は、macOS 26.5.1上のPython 3.15.0で動かし、APIに接続しない形で送信内容を確かめました（実機検証）。認証が必要なAPIの呼び出しは行っていないため、部分成功の実際の応答、定義にないパラメーターをHTTPで直接送ったときの扱い、ErrorInfoの実際の内容は未確認です。Terraformのプロバイダーが送る版、JavaなどPython・Node.js・Go以外のライブラリも確認していません。
クラウドの自動化やインフラの構成管理の見直しは、開発・AI・自動化のご相談からお問い合わせください。
