Google Cloud の Cloud Support API v2 は、サポートケースの作成や更新、検索などを行える REST API です。
サポートポータルの Web UI の操作だけでなく、API も活用することで、サポートケース管理の自動化や効率化を図ることができます。
今回は、先日公開した Cloud Support MCP Server (Cloud Support API v2 を操作するための MCP サーバー) を開発した際に得られた Tips をいくつかご紹介したいと思います。
(1) cases.search API の検索クエリ構文と制約
Cloud Support API v2 ではサポートケースの検索用に cases.search メソッドが提供されています。
cases.search は便利な機能ではあるのですが、上手く使うにはクエリパラメータ（query）の制約を理解している必要があります。
主なポイントを以下に挙げると：
指定可能なフィールドの種類
query では決められたフィールドのみフィルタとして使用できます。
具体的には以下のとおりです。
- 組織（organization）または プロジェクト（project）のリソース名
- ケースの ステータス（state：OPEN/CLOSED）
- 優先度（priority：P0〜P4）
- ケース作成者の メールアドレス（creator.email）
ケースのステータスはサポートポータルから確認すると OPEN / CLOSED 以外にもステータスは色々ある (e.g. "In progress, Google Support") のですが、search API の検索においてはケースがクローズされているか否か (CLOSED 以外はすべて OPEN のバリエーションの一部とみなされる) ようです。
AND/OR演算子の使用
複数条件を組み合わせる場合は基本的に AND で連結します。
ただし、priority フィールドに限り、複数値を OR で指定することが可能です（e.g. priority=P1 OR priority=P2）。
他のフィールドでは OR 条件の併用はできず、事実上 1 クエリ内で各種フィールドは一度ずつしか指定できないことになります。
プロジェクトまたは組織の指定必須
cases.search を実行する際は、必ず organization または project の指定が必要です。
search API のページには明記されていませんが、organizations/{org-id} を指定した場合は組織配下で作成されたすべてのサポートケースが検索対象になります。
特定プロジェクト内に限定する場合は projects/{project-id} を指定します。
このいずれかを指定しないとクエリは無効になります。
グローバル検索と全文検索
ケースのタイトル（displayName）や説明文、コメント内のテキストで検索したい場合、無指定フィールドのグローバル検索が可能です。
具体的にはクエリ文字列をそのまま引用符で囲みます（例："障害" のように記述すると、タイトル・説明・コメントを横断して「障害」を含むケースを検索）。
更新日時によるフィルタ
特定の日付以降に更新されたケースのみ取得したい場合、updateTime フィールドを使用できます。
ISO 8601 形式の日付を > 演算子 (Newer の意味) と共に指定します（e.g. updateTime>"2025-01-01T00:00:00+09:00"）。
updateTime はこの > 演算子のみをサポートするため、< や \= は使えません。
この制約により、過去の指定範囲の期間や特定日のケースだけを絞り込むことはできない仕様となっています。
そうした過去の一部期間を絞り込みたい場合は、期間の開始日以降のケースを一旦すべて取得し、アプリケーション側でフィルタリングする必要があります。
(2) caseClassifications.search API の検索条件に関する制約
Cloud Support API v2 ではサポートケースの ケース分類 (Case Classification) を取得するために caseClassifications.search という API が提供されています。
ケース分類はサポートケースのカテゴリ（e.g. "Technical Issue > Compute > Compute Engine" のような階層）を表すもので、新規ケース作成時に正確な ID を指定する必要があります。
この caseClassifications.search API にもクエリパラメータがありますが、公式ドキュメント上は具体的なクエリ記法について情報が少なく、実際に利用できるフィルタ条件は限定的です。
現時点で私が確認できているのは、ドキュメントにある displayName を使ったフィルタだけです。
分類名に「Compute Engine」を含むものを検索したい場合、次のようにクエリを指定します。
query=displayName:"*Compute Engine*"
上記のように displayName: プレフィックスを付け、引用符内で部分一致させたい文字列を * ワイルドカード付きで指定します。
この例では「Compute Engine」を名前に含むケース分類（例えば「Technical Issue > Compute > Compute Engine」など）がヒットし、その分類IDと表示名が取得できます。
ケース分類 ID は新しいサービスの登場に伴って追加されることもあれば、整理されて既存のケースがなくなることもあります。
そのため、一度取得したケース分類の ID がずっと使い続けられるとは限りません。
現在の仕様では、取得した ID は最低 6 ヶ月は有効性が保証されるようになっています。
分類体系の変更などによって非推奨化された ID は caseClassifications.search の結果から除外されるようになりますが、非推奨になってから 6 ヶ月は有効のようです。
6 ヶ月を過ぎると当該 ID でのケース作成が失敗することになりそうです。
(3) cases.list と cases.search の使い分け
Cloud Support API v2 には、ケースを一覧取得する cases.list と、前述の cases.search という二つの類似した API があります。
これらの違いと使い分けについて整理します。
cases.list
cases.list は指定した親リソース直下のサポートケースを取得します。
例えば parent として組織（organization）を指定した場合、その組織に直接ひも付いたケースのみが返ります。
ここで重要なのは、組織配下のプロジェクトで発行されたケースは含まれないということです。
Cloud Support のケースは通常プロジェクト単位で作成されますが、組織を親に指定しても内部的にその子プロジェクトまでは検索しないため、結果に漏れが生じます。
したがって、cases.list は特定のプロジェクトID を parent に指定する場合に、そのプロジェクトのケース一覧を取得する用途に適しています。
クエリパラメータとしては filter が用意されており、state（OPEN/CLOSED）、priority（P0〜P4、OR指定可）、creator.email での絞り込みが可能です。
cases.search
cases.search は前述のように柔軟な検索が可能で、組織全体を包括的に検索できる点が強みです。
parent として organizations/{organizationId} を指定すると、その組織自体に紐づくケースに加え、組織配下のすべてのプロジェクトのケースを横断的に取得できます。
したがって、組織内のサポートケースを網羅的に集計・検索したい場合はこちらを使う必要があります。
例えば組織全体の未解決（OPEN）のケースを洗い出したい、といった場合には cases.search で parent に組織を指定し、さらにクエリで state=OPEN を加えることで一括取得が可能です。
(4) ケースのステータス変化に対するイベント駆動化の可能性
サポートケース管理を自動化する上で、「ケースに更新があったら自動で通知や処理を行いたい」というニーズがあります。
例えば、テクニカルサポートから回答が来たタイミングや、ケースがクローズされたタイミングで社内ツールに通知したり、後続の処理（ドキュメント更新や問題管理システムのチケットクローズなど）を自動実行できれば便利です。
理想的にはこれらを Pub/Sub や Eventarc によるイベント駆動で実装できるとスマートですが、現状はいくつか制約があります。
まず、Google Cloud にはリソースの操作履歴を記録する Cloud Audit Logs があります。
Cloud Support API も監査ログの対応サービス一覧に含まれており、一見するとケース更新があればログ経由で検知できそうです。
実際、Cloud Support API v2 の各メソッド呼び出し時には対応する監査ログエントリが生成されます。
例えばケースをクローズするAPIメソッド CaseService.CloseCase は Data Access 種別の監査ログとして記録されます。
そのため、Audit Logging を有効化し、かつログから protoPayload.methodName="...CloseCase" のようなフィルタで検出する方法が考えられそうです。
しかしながら、実際には サポートポータル（Cloud Consoleのサポート画面）上での操作や、サポート担当者によるケース操作では監査ログが出力されないようです。
私が動作確認した限りでは、どうやら Cloud Support API の監査ログは基本的に API を直接操作した場合にのみ出力される仕様のようです。
ユーザーやサービスアカウントが直接 Cloud Support API を実行した場合（例えば自前のスクリプトやシステム経由でケースを更新・クローズした場合）にはログが残りますが、Cloud Console のサポートポータルからユーザーが画面操作でケースをクローズした場合や、サポートエンジニアが内部的にケースステータスを変更した場合は、対応する API 呼び出しが自分のプロジェクトコンテキストで発生しないため監査ログに現れない、ということではないかと思われます (現状は) 。
そのため、サポートケースのステータス変化をリアルタイムに捕捉するためのイベント駆動なアーキテクチャは現状の仕様だと実現が難しそうです。
代替策としては、定期的に API からケース情報をポーリングし、ステータス変化を検出する方法が考えられます。
例えば毎日 1 回決まった時間に cases.search で OPEN なケースを取得し、前回からステータスが変わったものを洗い出す、といった実装です。
厳密なリアルタイム性には欠けますが、現状では現実的な手段と言えるでしょう。
将来的には、サポートケースのステータス変化が操作方法を問わず監査ログに出力されるようになってくれることを期待したいですね。
まとめ
Cloud Support API v2 を利用するうえで押さえておきたいいくつかの Tips をご紹介しました。
人力かつ画面操作で行われがちなサポートケースの操作ですが、制約を理解したうえで上手く API を活用すれば、プログラム経由でサポートケース管理の自動化や効率化が図れるのではと思います。
手段のひとつとして Cloud Support MCP Server もありますので、もし機会があれば試してみて頂けたらと思います。
