介绍
# Google Chat Messaging
使用两种方法向 Google Chat 发送消息：
1. **Webhooks** - 快速、预配置的通道（消息显示为机器人） 2. **OAuth** - 向任何空间或用户进行动态消息传递（需要身份验证）
## 快速开始
### 方法 1：Webhooks（适用于已知通道，推荐）
发送到预配置的通道：
```bash python3 scripts/send_webhook.py "$WEBHOOK_URL" "Your message here" ```
使用线程的示例： ```bash python3 scripts/send_webhook.py "$WEBHOOK_URL" "Reply message" --thread_key "unique-thread-id" ```
**配置：** 将 webhooks 存储在 `google-chat-config.json` 中：
```json { "webhooks": { "acs_engineering_network": "https://chat.googleapis.com/v1/spaces/...", "general": "https://chat.googleapis.com/v1/spaces/..." } } ```
读取配置并发送： ```bash WEBHOOK_URL=$(jq -r '.webhooks.acs_engineering_network' google-chat-config.json) python3 scripts/send_webhook.py "$WEBHOOK_URL" "Deploy completed ✅" ```
### 方法 2：OAuth（适用于动态消息传递）
**首次设置：**
1. 将 OAuth 凭据保存到文件（例如 `google-chat-oauth-credentials.json`） 2. 运行初始身份验证（打开浏览器，保存令牌）：
```bash python3 scripts/send_oauth.py \ --credentials google-chat-oauth-credentials.json \ --token google-chat-token.json \ --space "General" \ "Test message" ```
**按名称发送到空间：** ```bash python3 scripts/send_oauth.py \ --credentials google-chat-oauth-credentials.json \ --token google-chat-token.json \ --space "Engineering Network" \ "Deploy completed" ```
**注意：** OAuth 消息会自动包含 `🤖` 表情符号前缀。使用 `--no-emoji` 禁用此功能： ```bash python3 scripts/send_oauth.py \ --credentials google-chat-oauth-credentials.json \ --token google-chat-token.json \ --space "Engineering Network" \ "Message without emoji" \ --no-emoji ```
**列出可用空间：** ```bash python3 scripts/send_oauth.py \ --credentials google-chat-oauth-credentials.json \ --token google-chat-token.json \ --list-spaces ```
**发送到私信（DM，需要现有空间 ID）：** ```bash # 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 发送到空间（速度更快）：** ```bash 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 软件包：
```bash 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](https://console.cloud.google.com) 2. 选择您的项目或创建一个新项目 3. 启用 **Google Chat API** 4. 前往 **APIs & Services → Credentials**（API 和服务 → 凭据） 5. 创建 **OAuth 2.0 Client ID**（桌面应用类型） 6. 下载 JSON 并保存为 `google-chat-oauth-credentials.json`
凭据 JSON 应如下所示： ```json { "installed": { "client_id": "...apps.googleusercontent.com", "client_secret": "GOCSPX-...", "redirect_uris": ["http://localhost"], ... } } ```
## Webhook 设置指南
要为 Google Chat 空间创建 webhook：
1. 在浏览器中打开 Google Chat 2. 进入该空间 3. 点击空间名称 → **Apps & integrations**（应用与集成） 4. 点击 **Manage webhooks**（管理 Webhooks）→ **Add 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：** ```python 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 错误：** - 如果令牌过期，请再次运行身份验证流程 - 验证 Cloud Console 中已启用 Google Chat API - 检查用户是否有权访问目标空间 - 对于私信，确保用户电子邮件正确且在同一工作区中
**权限错误：** - Webhooks：必须是空间的成员 - OAuth：必须有权访问目标空间或用户 - 企业工作区：某些功能可能会被管理员策略限制
## 示例
**向工程通道发送部署通知：** ```bash WEBHOOK=$(jq -r '.webhooks.acs_engineering_network' google-chat-config.json) python3 scripts/send_webhook.py "$WEBHOOK" "🚀 Production deploy v2.1.0 completed" ```
**提醒特定用户有关任务：** ```bash python3 scripts/send_oauth.py \ --credentials google-chat-oauth-credentials.json \ --token google-chat-token.json \ --dm [email protected] \ "Your report is ready for review: https://docs.company.com/report" ```
**将多条消息串联在一起（webhook）：** ```bash 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" ```