google-workspace

Google Workspace

概述

通过 OAuth 身份验证与 Google Drive、Gmail、Calendar 和 Docs 交互。支持文件上传、文件夹管理、电子邮件搜索、日历搜索和文档操作。

快速决策树

What do you need?
│
├── Google Drive
│   ├── Search files/folders → references/drive-search.md
│   │   └── Script: scripts/gdrive_search.py
│   │
│   ├── Upload files → references/drive-upload.md
│   │   └── Script: scripts/google_drive_upload.py
│   │
│   ├── Create folder structure → references/folder-structure.md
│   │   └── Script: scripts/gdrive_folder_structure.py
│   │
│   ├── Create client folder → references/create-folder.md
│   │   └── Script: scripts/create_client_folder.py
│   │
│   └── Search transcripts → references/transcript-search.md
│       └── Script: scripts/gdrive_transcript_search.py
│
├── Gmail
│   └── Search emails → references/gmail-search.md
│       └── Script: scripts/gmail_search.py
│
└── Calendar
    └── Search meetings → references/calendar-search.md
        └── Script: scripts/google_calendar_search.py

环境设置

首次身份验证后，OAuth 凭据会保存在本地。

必需文件

• client_secrets.json - 从 Google Cloud Console 获取
• settings.yaml - PyDrive2 配置
• mycreds.txt - 自动生成的 OAuth 令牌

首次设置

1. 前往 Google Cloud Console
2. 启用 API：Drive、Gmail、Calendar、Docs
3. 创建 OAuth 2.0 凭据（桌面应用）
4. 下载为 client_secrets.json
5. 运行任意脚本 - 浏览器会打开以进行 OAuth 授权

常见用法

搜索客户端文件夹

python scripts/gdrive_search.py folder "Microsoft"

上传文件

python scripts/google_drive_upload.py --files *.png --folder "Clients/Acme/Assets"

搜索电子邮件

python scripts/gmail_search.py --domain "microsoft.com" --days 14

搜索日历

python scripts/google_calendar_search.py "Microsoft" --days-back 30

OAuth 范围

范围	用途
drive	完整 Drive 访问权限
spreadsheets	Sheets 访问权限
documents	Docs 访问权限
gmail.readonly	读取电子邮件
calendar.readonly	读取日历

费用

免费 - Google Workspace API 提供充足的免费配额。

安全说明

凭据处理

• client_secrets.json - OAuth 应用凭据（切勿提交到 git）
• mycreds.txt - 用户 OAuth 令牌（切勿提交到 git，应添加到 .gitignore）
• settings.yaml - PyDrive2 配置（可提交，不含机密信息）
• 令牌会自动刷新；如果凭据泄露，请在 Google 账号设置中撤销
• 切勿在不同用户或设备之间共享 OAuth 凭据

数据隐私

• 可访问用户的个人 Google Drive、Gmail 和 Calendar
• 文件可能包含机密业务信息
• 电子邮件内容高度敏感 - 尽量减少存储
• 日历事件可能包含私人会议详情
• 共享云端硬盘访问权限遵循原有权限设置

访问范围

• 仅请求必需的最低范围：
  • drive - 完整 Drive 访问权限（读/写）
  • drive.readonly - 只读 Drive 访问权限（可行时优先使用）
  • spreadsheets - Google Sheets 访问权限
  • documents - Google Docs 访问权限
  • gmail.readonly - 只读电子邮件访问权限
  • calendar.readonly - 只读日历访问权限
• 查看/撤销访问权限：https://myaccount.google.com/permissions

合规注意事项

• OAuth 授权：用户明确同意访问范围
• GDPR：Google Workspace 数据包含欧盟用户的个人身份信息
• 数据驻留：Google Workspace 可能有数据驻留要求
• 共享云端硬盘：遵循组织的共享政策
• 审计跟踪：Google Admin Console 会跟踪 API 访问情况
• 凭据安全：安全存储 client_secrets.json，不要放在代码仓库中

故障排除

常见问题

问题：OAuth 令牌已过期

**症状：**出现“Invalid credentials”或“Token has been expired or revoked”错误 **原因：**OAuth 刷新令牌已过期或被撤销 解决方案：

• 删除 mycreds.txt 文件
• 重新运行任意脚本以触发新的 OAuth 流程
• 在浏览器中完成授权
• 系统会自动创建新的 mycreds.txt

问题：找不到文件

**症状：**使用有效文件 ID 时出现“File not found”错误 **原因：**无权访问文件、文件已删除或文件 ID 错误 解决方案：

• 从 Google Drive URL 中核实文件 ID
• 检查文件共享权限
• 确保 OAuth 用户有权访问该文件
• 先尝试在浏览器中直接访问文件

问题：超出配额

**症状：**出现“User rate limit exceeded”或“Quota exceeded”错误 **原因：**24 小时内 API 请求过多 解决方案：

• 等待 24 小时，直到配额重置
• 创建一个具有新配额的 Google Cloud 项目
• 在脚本中实现指数退避
• 减少 API 调用频率

问题：缺少 settings.yaml

症状：“未找到 settings.yaml”或 PyDrive2 配置错误 **原因：**缺少 PyDrive2 配置文件 解决方案：

• 从模板复制：cp settings.yaml.example settings.yaml
• 确保 settings 中的 client_secrets.json 路径正确
• 确认 save_credentials_backend 设置为 "file"
• 检查 settings.yaml 是否位于脚本的工作目录中

问题：client_secrets.json 无效

症状：“客户端密钥无效”或 OAuth 配置错误 **原因：**OAuth 凭据文件格式错误或内容不正确 解决方案：

• 从 Google Cloud Console 重新下载
• 确保创建凭据时选择了“桌面应用”类型
• 检查 JSON 格式是否有效
• 确认已为本地身份验证配置重定向 URI

问题：范围访问遭拒

症状：“权限不足”错误 **原因：**OAuth 同意页面缺少所需范围 解决方案：

• 删除 mycreds.txt 以重置 OAuth 会话
• 重新进行身份验证并接受所有请求的范围
• 确认 settings.yaml 中的范围与脚本要求一致
• 检查 Google Cloud Console 中的范围限制

资源

• references/drive-search.md - 搜索文件和文件夹
• references/drive-upload.md - 将文件上传到 Drive
• references/folder-structure.md - 创建文件夹层级结构
• references/create-folder.md - 创建客户端文件夹
• references/transcript-search.md - 搜索转录文件
• references/gmail-search.md - 搜索 Gmail
• references/calendar-search.md - 搜索日历会议

集成模式

从 Drive 到视频制作

技能： google-workspace → video-production 用例： 从 Drive 文件夹组装课程视频 流程：

1. 在 Drive 中搜索包含课程文件的视频文件夹
2. 通过 video-production 脚本下载视频
3. 将视频与标题幻灯片拼接，并上传最终成品

从模板到内容

技能： google-workspace → content-generation 用例： 根据品牌模板生成文档 流程：

1. 从 Drive 加载模板（提案、报告格式）
2. 通过 content-generation 生成内容
3. 创建包含格式化内容的新 Google Doc

从日历到转录文件

技能： google-workspace → transcript-search 用例： 查找日历事件对应的会议录音 流程：

1. 搜索与特定客户相关的日历会议
2. 获取会议日期和标题
3. 在 transcript-search 中搜索匹配的录音