Google Chat 消息发送

使用两种方法向 Google Chat 发送消息：

1. Webhooks（网络钩子）- 快速、预配置的通道（消息以机器人身份出现）
2. OAuth（授权）- 向任何空间或用户发送动态消息（需要身份验证）

快速开始

方法一：Webhooks（推荐用于已知通道）

发送到预配置的通道：

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

带线程的示例：

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

配置：将 webhooks 存储在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（用于动态消息发送）

首次设置：

1. 将 OAuth 凭据保存到文件（例如，google-chat-oauth-credentials.json）
2. 运行初始身份验证（打开浏览器，保存令牌）：

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 消息会自动包含🤖表情符号前缀。使用--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）：

# Note: Google Chat API doesn't support creating new DMs by email
# You need the space ID of an existing DM conversation
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 凭据尚不存在：

1. 前往Google Cloud Console
2. 选择您的项目或创建一个新项目
3. 启用Google Chat API
4. 前往API 和服务 → 凭据
5. 创建OAuth 2.0 客户端 ID（桌面应用类型）
6. 下载 JSON 并另存为google-chat-oauth-credentials.json

凭据 JSON 文件应类似如下：

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

Webhook 设置指南

要为 Google Chat 空间创建 webhook：

1. 在浏览器中打开 Google Chat
2. 进入相应空间
3. 点击空间名称 →应用和集成
4. 点击管理 webhook→添加 webhook
5. 为其命名（例如，"Agustin Networks"）
6. 复制 webhook URL
7. 添加到google-chat-config.json

选择正确的方法

在以下情况使用 Webhooks：

• 需要重复向同一频道发送消息
• 消息应显示为机器人/服务发送
• 速度至关重要（无需 OAuth 握手流程）
• 配置是静态的

在以下情况使用 OAuth：

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

OAuth 限制：

• 无法通过电子邮件地址创建新的私聊对话（Google Chat API 限制）
• 发送私聊消息需要现有对话的空间 ID
• 使用--list-spaces命令查找可用的私聊空间 ID

消息格式化

两种方法都支持简单文本。如需高级格式化（卡片、按钮），需要构建 JSON 载荷：

带有卡片的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错误：

• 如果令牌已过期，请重新运行身份验证流程
• 验证Google Chat API是否已在云控制台中启用
• 检查用户是否有权访问目标空间
• 对于私信，请确保用户电子邮件地址正确且在同一工作区内

权限错误：

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

示例

向工程频道发送部署通知：

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）：

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"