google-chat

用途

本工具用于向 Google Chat 的空间（Space）和用户发送消息，支持两种方式：Webhook 和 OAuth。适用于发送通知、告警或消息到 Google Chat 频道的场景。

主要能力

方式一：Webhook（推荐用于已知频道）

向预先配置的频道发送消息，消息以机器人身份显示。支持线程回复。

发送命令：

python3 scripts/send_webhook.py "$WEBHOOK_URL" "Your message here"

带线程的示例：

python3 scripts/send_webhook.py "$WEBHOOK_URL" "Reply message" --thread_key "unique-thread-id"

Webhook 配置存储在 google-chat-config.json 中：

{
  "webhooks": {
    "acs_engineering_network": "https://chat.googleapis.com/v1/spaces/...",
    "general": "https://chat.googleapis.com/v1/spaces/..."
  }
}

读取配置并发送：

WEBHOOK_URL=$(jq -r '.webhooks.acs_engineering_network' google-chat-config.json)
python3 scripts/send_webhook.py "$WEBHOOK_URL" "Deploy completed ✅"

方式二：OAuth（用于动态消息发送）

首次设置：将 OAuth 凭据保存到文件（如 google-chat-oauth-credentials.json），然后运行初始认证（会打开浏览器并保存 token）：

python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --space "General" \
  "Test message"

按名称发送到空间：

python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --space "Engineering Network" \
  "Deploy completed"

注意：OAuth 消息会自动添加 🤖 emoji 前缀，使用 --no-emoji 可禁用：

python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --space "Engineering Network" \
  "Message without emoji" \
  --no-emoji

列出可用空间：

python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --list-spaces

发送私信（需要已有空间 ID）：

# 注意：Google Chat API 不支持通过邮箱创建新私信
# 需要已有私信会话的空间 ID
python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --space-id "spaces/xxxxx" \
  "The report is ready"

按空间 ID 发送（更快）：

python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --space-id "spaces/AAAALtlqgVA" \
  "Direct message to space"

使用方式

依赖安装

安装所需的 Python 包：

pip install google-auth-oauthlib google-auth-httplib2 google-api-python-client

所需 OAuth 权限范围

https://www.googleapis.com/auth/chat.messages — 发送消息
https://www.googleapis.com/auth/chat.spaces — 访问空间信息
https://www.googleapis.com/auth/chat.memberships.readonly — 列出空间成员（用于私信识别）

OAuth 设置指南

如果 OAuth 凭据尚不存在：

前往 Google Cloud Console
选择或创建项目
启用 Google Chat API
前往 APIs & Services → Credentials
创建 OAuth 2.0 Client ID（Desktop app 类型）
下载 JSON 并保存为 google-chat-oauth-credentials.json

凭据 JSON 格式示例：

{
  "installed": {
    "client_id": "...apps.googleusercontent.com",
    "client_secret": "GOCSPX-...",
    "redirect_uris": ["http://localhost"],
    ...
  }
}

Webhook 设置指南

为 Google Chat 空间创建 Webhook：

在浏览器中打开 Google Chat
进入目标空间
点击空间名称 → Apps & integrations
点击 Manage webhooks → Add webhook
为其命名（如 "Agustin Networks"）
复制 Webhook URL
添加到 google-chat-config.json

方法选择

使用 Webhook 的场景：

重复向相同频道发送消息
消息应以机器人/服务身份显示
速度重要（无需 OAuth 握手）
配置是静态的

使用 OAuth 的场景：

动态向不同空间发送消息
消息应来自配置的 Google Chat App
空间名称在运行时确定
需要列出和发现可用空间

适用场景

部署通知发送到工程频道
向特定用户发送任务提醒
将多条消息归入同一线程

示例：

WEBHOOK=$(jq -r '.webhooks.acs_engineering_network' google-chat-config.json)
python3 scripts/send_webhook.py "$WEBHOOK" "🚀 Production deploy v2.1.0 completed"

python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --dm juan@empresa.com \
  "Your report is ready for review: https://docs.company.com/report"

WEBHOOK=$(jq -r '.webhooks.general' google-chat-config.json)
THREAD_KEY="deploy-$(date +%s)"

python3 scripts/send_webhook.py "$WEBHOOK" "Starting deploy..." --thread_key "$THREAD_KEY"
# ... deployment happens ...
python3 scripts/send_webhook.py "$WEBHOOK" "Deploy completed ✅" --thread_key "$THREAD_KEY"

限制

OAuth 限制

无法通过邮箱地址创建新私信（Google Chat API 限制）
发送私信需要已有会话的空间 ID
可使用 --list-spaces 查找可用的私信空间 ID

消息格式

两种方法均支持简单文本。如需高级格式（卡片、按钮），需构造 JSON payload：

Webhook 卡片示例：

import json
import urllib.request

payload = {
    "cardsV2": [{
        "cardId": "unique-card-id",
        "card": {
            "header": {"title": "Deploy Status"},
            "sections": [{
                "widgets": [{
                    "textParagraph": {"text": "Production deploy completed successfully"}
                }]
            }]
        }
    }]
}

data = json.dumps(payload).encode("utf-8")
req = urllib.request.Request(webhook_url, data=data, headers={"Content-Type": "application/json"})
urllib.request.urlopen(req)

故障排查

Webhook 错误：

验证 Webhook URL 是否正确且有效
检查空间是否仍存在且 Webhook 未被删除
确保消息不为空

OAuth 错误：

如果 token 过期，重新运行认证流程
验证 Cloud Console 中已启用 Google Chat API
检查用户是否有权访问目标空间
对于私信，确保用户邮箱正确且在同一工作区

权限错误：

Webhook：必须是空间成员
OAuth：必须有权访问目标空间或用户
企业工作区：部分功能可能受管理员策略限制