Chat API が必要になる場面
PART 04 までの通知は、すべて Webhook で作れた。Chat API に移る理由がなければ、Webhook のままで十分だ。移る価値があるのは、次のどれかが必要になったときである。
| やりたいこと | Webhook | Chat API |
|---|---|---|
| 「実行中」と送ったメッセージを「完了」に書き換える | できない | spaces.messages.patch |
| 誤って送ったメッセージを消す | できない(手で消す) | spaces.messages.delete |
| 同じアプリとして複数のスペースに送る | スペースごとに URL を管理 | アプリを追加したスペースならどこでも |
| スペースやメンバーの一覧を取る(メンション用のユーザー ID など) | できない | spaces.list / spaces.members.list |
| 組織のポリシーで Webhook が禁止されている | 使えない | Chat アプリが許可されていれば使える |
この回では、Chat アプリを作ってサービスアカウントで認証し(アプリ認証)、投稿・書き換え・削除までを行う。ユーザー本人として投稿する「ユーザー認証」もあるが、通知用途では「誰が送ったか」がアプリ名で明確になるアプリ認証のほうが向いている。
Google Cloud 側の準備
図1: Chat API で投稿するまでの準備(①〜④)と、メッセージの書き換え
Chat アプリは 1つの Google Cloud プロジェクトに1つ 作る。通知専用のプロジェクト(例:gchat-notify)を新しく作っておくと、権限や鍵の管理が他と混ざらない。手順は Workspace のアカウントで Google Cloud コンソールにログインして行う。
1. プロジェクトを作り、Google Chat API を有効にする
- Google Cloud コンソールで新しいプロジェクトを作る(組織は自社の Workspace を選ぶ)
- API とサービス → ライブラリ で「Google Chat API」を検索し、有効にする
- OAuth の同意画面(Google Auth Platform)の設定を求められたら、ユーザーの種類を 内部 にし、アプリ名とサポートのメールアドレスだけ入れて保存する
2. Chat API の「構成」でアプリを作る
Google Chat API のページの 構成 タブが、Chat 上に表示される「アプリ」の設定画面になる。
| 項目 | 設定する値 |
|---|---|
| アプリ名 | Chat に表示される名前(25文字まで)。例:運用通知 |
| アバターの URL | 正方形の PNG / JPEG の HTTPS URL(256×256 ピクセル以上を推奨) |
| 説明 | 40文字まで。例:バッチ・アラームの結果を通知します |
| マークアップ構文 | テキストの書式(後述)。Webhook 用に書いたメッセージを流用するなら「Chat」 |
| インタラクティブ機能 | 有効にする。機能で「スペースとグループの会話に参加する」を選ぶ |
| 接続設定 | HTTP エンドポイント URL など(後述) |
| 公開設定 | このアプリを使えるようにするユーザー。最初は自分のメールアドレス、運用時はチームの Google グループを指定する |
| ログ | 「エラーを Logging に記録」にチェックしておくと、原因調査が楽になる |
画面に「Google Workspace アドオンとしてこの Chat 用アプリを作成する」といったチェックボックスが表示される場合、この記事の手順は従来型の Chat アプリを前提にしているので、チェックを外して進める。
接続設定(イベントの送り先)について
インタラクティブ機能を有効にすると、接続設定(ユーザーがアプリにメンションしたときなどにイベントを届ける先)の入力を求められる。インタラクティブ機能を無効にしたままだと、Chat の画面からアプリを検索してスペースに追加できないため、通知専用のアプリでもここは埋める必要がある。
通知専用で応答を作らないなら、自分たちが管理する HTTPS の URL を入れておけばよい。届いたイベントに応答しない場合、ユーザーがアプリにメンションすると「応答がありません」と表示されるが、API からの投稿には影響しない。後で対話型にしたくなったら、ここを Cloud Run や Apps Script のデプロイに差し替える。
3. サービスアカウントとキーを作る
- IAM と管理 → サービス アカウント → サービス アカウントを作成 で、名前(例:
gchat-notifier)を付けて作る。プロジェクトのロールは付けなくてよい - 作成したサービスアカウントを開き、キー → 鍵を追加 → 新しい鍵を作成 → JSON で鍵ファイルをダウンロードする
スコープ https://www.googleapis.com/auth/chat.bot を使うアプリ認証は、Workspace の管理者による承認がいらない。サービスアカウントは「このアプリとして API を呼ぶための身分証」で、Chat 上の名前やアイコンは手順2の構成のものが使われる。
⚠️ 鍵ファイルの作成が禁止されている組織がある
サービスアカウントの鍵は漏れると悪用されやすいため、新しく作られた Google Cloud の組織では、組織ポリシーで鍵の作成が既定で禁止されていることがある。「鍵を追加」でエラーになったら、組織の管理者に例外を相談するか、Google Cloud の中(Cloud Run など)で、サービスアカウントを直接割り当てて動かす方法を検討する。鍵の扱いは PART 06 でも触れる。
スペースにアプリを追加し、スペース名を調べる
アプリ認証では、アプリがメンバーになっているスペースにしか投稿できない。投稿先のスペースで、次の操作をする。
- スペース名の横の下向き矢印 → アプリとインテグレーション を開く
- アプリを追加 をクリックし、手順2で付けたアプリ名を検索して追加する
次に、API で指定する スペース名(spaces/AAAA... の形)を調べる。ブラウザで Chat のスペースを開いたときの URL の末尾の ID がそれにあたる。
https://mail.google.com/chat/u/0/#chat/space/AAAAxxxxxxx
↓
スペース名 = spaces/AAAAxxxxxxx同じスペースに Webhook がある場合は、Webhook URL の spaces/AAAAxxxxxxx の部分も同じ値だ。アプリが参加しているスペースの一覧は、後述 の spaces.list でも取得できる。
Python で投稿する
pip install google-api-python-client google-auth鍵ファイルのパスとスペース名は環境変数から読む。クライアントを作る処理をモジュールにしておくと、以降の例で使い回せる。
"""Google Chat API をアプリ認証(サービスアカウント)で呼ぶための小さなモジュール"""
import os
from google.oauth2 import service_account
from googleapiclient.discovery import build
SCOPES = ["https://www.googleapis.com/auth/chat.bot"]
SPACE = os.environ["GCHAT_SPACE"] # 例: spaces/AAAAxxxxxxx
def chat_client():
creds = service_account.Credentials.from_service_account_file(
os.environ["GCHAT_SA_KEY"], scopes=SCOPES # 鍵ファイル(JSON)のパス
)
return build("chat", "v1", credentials=creds, cache_discovery=False)
def create_message(body: dict, message_id: str | None = None,
thread_key: str | None = None, space: str = SPACE) -> dict:
params = {"parent": space, "body": body}
if message_id:
params["messageId"] = message_id # 後から書き換えるための自分で決めた ID
if thread_key:
params["body"] = {**body, "thread": {"threadKey": thread_key}}
params["messageReplyOption"] = "REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
return chat_client().spaces().messages().create(**params).execute()
if __name__ == "__main__":
print(create_message({"text": "Chat API からのテスト投稿です。"}))$env:GCHAT_SA_KEY = 'C:\secure\gchat-notifier.json'
$env:GCHAT_SPACE = 'spaces/AAAAxxxxxxx'
python gchat_api.pyWebhook と違い、応答にはメッセージ全体(送信者・作成日時・本文など)が返る。sender を見ると、送信者がアプリ("type": "BOT")になっていることを確認できる。メッセージの JSON(text・cardsV2・thread)は Webhook とまったく同じなので、PART 03 の status_card() もそのまま create_message() に渡せる。
メッセージを書き換える・削除する
Chat API ならではの使い方が、1つのメッセージを状況に合わせて書き換える ことだ。たとえば長いバッチの開始時に「⏳ 実行中」と投稿しておき、終わったら同じメッセージを「✅ 完了(所要時間)」に書き換える。スペースに流れるメッセージは1つのままで、見る人は最新の状態だけを読めばよい。
書き換えるには、対象のメッセージの名前(spaces/.../messages/...)が必要になる。投稿時の応答から取ってもよいが、投稿するときに自分で messageId を決めておく と、別のプロセスからでも同じ名前で書き換えられて便利だ。messageId は client- で始め、英小文字・数字・ハイフンだけで63文字以内にする。
import time
from datetime import date
from gchat_api import SPACE, chat_client, create_message
job = "daily-aggregate"
message_id = f"client-{job}-{date.today():%Y%m%d}" # 例: client-daily-aggregate-20261031
name = f"{SPACE}/messages/{message_id}"
# 1. 開始時に投稿
create_message({"text": f"⏳ *{job}* 実行中…"}, message_id=message_id)
started = time.monotonic()
# ... 長い処理 ...
elapsed = int(time.monotonic() - started)
# 2. 終了時に同じメッセージを書き換える(updateMask で変える項目を指定)
chat_client().spaces().messages().patch(
name=name,
updateMask="text",
body={"text": f"✅ *{job}* 完了({elapsed // 60}分{elapsed % 60}秒)"},
).execute()カードを書き換えるときは、updateMask に cards_v2 を指定し、body に新しい cardsV2 を入れる(テキストとカードの両方なら text,cards_v2)。書き換えでは、新しい投稿のようにメンバーへ改めて通知が飛ぶことは通常ないので、「開始」と「完了」で2回通知されるのを避けたい場面にも向いている。
削除は名前を指定するだけだ。
chat_client().spaces().messages().delete(name=name).execute()💡 アプリが書き換え・削除できるのは自分が送ったメッセージだけ
アプリ認証では、そのアプリ自身が作成したメッセージしか更新・削除できない。人が書いたメッセージや、Webhook が送ったメッセージは対象外だ。
スペースとメンバーの一覧を取る
アプリが参加しているスペースの一覧と、スペースのメンバー一覧は次のように取れる。複数のスペースに同じ通知を送る、メンション用のユーザー ID を調べる、といった用途に使う。
from gchat_api import chat_client
chat = chat_client()
# アプリが参加しているスペース
for space in chat.spaces().list().execute().get("spaces", []):
print(space["name"], space.get("spaceType"), space.get("displayName", ""))
# あるスペースのメンバー(users/数字 がメンションに使うユーザー ID)
resp = chat.spaces().members().list(parent="spaces/AAAAxxxxxxx").execute()
for m in resp.get("memberships", []):
member = m.get("member", {})
print(member.get("name"), member.get("type"), member.get("displayName", ""))結果が多いときは、応答の nextPageToken を次の呼び出しの pageToken に渡して続きを取る(考え方は boto3 のページネーション と同じ)。アプリ認証では、メンバーの表示名など一部の項目が返らないことがあるので、名前とユーザー ID の対応表を作るときは、Chat の画面と見比べて確認したい。
書式の違い:Markdown と Chat 記法
Webhook から移ってきたときに一番つまずくのが、テキストの書式だ。Webhook の既定は Chat 独自の記法 だが、新しく作った Chat アプリの既定は標準の Markdown になっている。
| 表示 | Chat 記法(Webhook の既定) | Markdown(新しい Chat アプリの既定) |
|---|---|---|
| 太字 | *太字* | **太字** |
| 斜体 | _斜体_ | *斜体* |
| 取り消し線 | ~取り消し~ | ~~取り消し~~ |
| リンク | <URL|表示文字> | [表示文字](URL) |
| メンション | <users/123...> | <chat-user data-user="users/123..."> |
表のとおり、Chat 記法の *太字* は Markdown では 斜体 として表示されてしまう。Webhook 用に書いたメッセージをそのまま Chat API に流すなら、構成画面の マークアップ構文 を「Chat」に切り替えておくのが簡単だ。新しく書くなら Markdown にそろえてもよいが、Webhook と Chat API が混在している間は、どちらか一方に統一しておくことをおすすめする。カードの中の書式(HTML タグ)はどちらの設定でも変わらない。
つまずきやすい点
| 症状 | 原因と対処 |
|---|---|
| スペースの「アプリを追加」でアプリが見つからない | 構成の 公開設定 に自分(またはグループ)が入っていない、インタラクティブ機能が無効、構成を保存していない |
| 403 / 404 でスペースに投稿できない | アプリがそのスペースのメンバーになっていない、またはスペース名の誤り(spaces/ の付け忘れなど) |
投稿時に Google Chat app not found のようなエラー | Chat API は有効にしたが「構成」を保存していない。構成タブでアプリ名などを入れて保存する |
| 書き換えで 404 | messageId が違う、または別のアプリ・Webhook が送ったメッセージを指定している |
400 で messageId が不正と言われる | client- で始まっていない、大文字や _ を含んでいる、63文字を超えている |
*太字* が斜体になる | アプリのマークアップ構文が Markdown。上記 のとおり「Chat」に切り替えるか、**太字** で書く |
✅ 次の記事では…
最終回の PART 06 では、Webhook URL とサービスアカウントの鍵の守り方、429 に備えたリトライ、長文の分割、よくあるエラーの一覧、そして「通知が多すぎて読まれない」を防ぐ設計をまとめる。