google-workspace

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Workspace

Overview

概述

Interact with Google Drive, Gmail, Calendar, and Docs using OAuth authentication. Supports file uploads, folder management, email search, calendar search, and document operations.

通过OAuth认证与Google Drive、Gmail、日历和Docs进行交互。支持文件上传、文件夹管理、邮件搜索、日历搜索和文档操作。

Quick Decision Tree

快速决策树

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

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

Environment Setup

环境搭建

OAuth credentials are stored locally after first authentication.

首次认证后，OAuth凭据将存储在本地。

Required Files

所需文件

```
client_secrets.json
```
- From Google Cloud Console
```
settings.yaml
```
- PyDrive2 configuration
```
mycreds.txt
```
- Auto-generated OAuth tokens

```
client_secrets.json
```
- 来自Google Cloud Console
```
settings.yaml
```
- PyDrive2配置文件
```
mycreds.txt
```
- 自动生成的OAuth令牌

First-Time Setup

首次设置步骤

Go to Google Cloud Console
Enable APIs: Drive, Gmail, Calendar, Docs
Create OAuth 2.0 credentials (Desktop app)
Download as
```
client_secrets.json
```
Run any script - browser opens for OAuth consent

访问Google Cloud Console
启用API：Drive、Gmail、Calendar、Docs
创建OAuth 2.0凭据（桌面应用类型）
下载为
```
client_secrets.json
```
运行任意脚本 - 浏览器将打开以完成OAuth授权

Common Usage

常见用法

Search Client Folder

搜索客户文件夹

bash

python scripts/gdrive_search.py folder "Microsoft"

bash

python scripts/gdrive_search.py folder "Microsoft"

Upload Files

上传文件

bash

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

bash

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

Search Emails

搜索邮件

bash

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

bash

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

Search Calendar

搜索日历

bash

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

bash

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

OAuth Scopes

OAuth 权限范围

Scope	Purpose
`drive`	Full Drive access
`spreadsheets`	Sheets access
`documents`	Docs access
`gmail.readonly`	Read emails
`calendar.readonly`	Read calendar

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

Cost

成本

Free - Google Workspace APIs have generous free quotas.

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

Security Notes

安全说明

Credential Handling

凭据处理

```
client_secrets.json
```
- OAuth app credentials (never commit to git)
```
mycreds.txt
```
- User OAuth tokens (never commit to git, add to .gitignore)
```
settings.yaml
```
- PyDrive2 config (can be committed, no secrets)
Tokens auto-refresh; revoke via Google Account settings if compromised
Never share OAuth credentials between users/machines

```
client_secrets.json
```
- OAuth应用凭据（绝不要提交到git）
```
mycreds.txt
```
- 用户OAuth令牌（绝不要提交到git，添加到.gitignore）
```
settings.yaml
```
- PyDrive2配置文件（可提交，不含敏感信息）
令牌会自动刷新；若泄露，可通过Google账户设置撤销
切勿在用户/设备之间共享OAuth凭据

Data Privacy

数据隐私

Access to user's personal Google Drive, Gmail, and Calendar
Files may contain confidential business information
Email content is highly sensitive - minimize storage
Calendar events may contain private meeting details
Shared Drive access respects original permissions

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

Access Scopes

访问权限范围

Request minimum required scopes:
- ```
drive
```
  - Full Drive access (read/write)
- ```
drive.readonly
```
  - Read-only Drive access (preferred when possible)
- ```
spreadsheets
```
  - Google Sheets access
- ```
documents
```
  - Google Docs access
- ```
gmail.readonly
```
  - Read-only email access
- ```
calendar.readonly
```
  - Read-only calendar access
Review/revoke access: https://myaccount.google.com/permissions

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

Compliance Considerations

合规注意事项

OAuth Consent: Users explicitly consent to access scopes
GDPR: Google Workspace data contains EU user PII
Data Residency: Google Workspace may have data residency requirements
Shared Drives: Respect organizational sharing policies
Audit Trail: Google Admin Console tracks API access
Credential Security: Store
```
client_secrets.json
```
securely, not in repos

OAuth授权：用户明确同意访问权限范围
GDPR：Google Workspace数据包含欧盟用户的个人可识别信息（PII）
数据驻留：Google Workspace可能有数据驻留要求
共享Drive：遵守组织共享政策
审计跟踪：Google管理控制台跟踪API访问
凭据安全：安全存储
```
client_secrets.json
```
，不要存放在代码仓库中

Troubleshooting

故障排除

Common Issues

常见问题

Issue: OAuth token expired

问题：OAuth令牌过期

Symptoms: "Invalid credentials" or "Token has been expired or revoked" error Cause: OAuth refresh token expired or revoked Solution:

Delete
```
mycreds.txt
```
file
Re-run any script to trigger fresh OAuth flow
Complete the browser authorization
New
```
mycreds.txt
```
will be created automatically

症状： 出现“无效凭据”或“令牌已过期或被撤销”错误 原因： OAuth刷新令牌过期或被撤销 解决方案：

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

Issue: File not found

问题：文件未找到

Symptoms: "File not found" error with valid file ID Cause: No access to file, file deleted, or wrong file ID Solution:

Verify file ID from the Google Drive URL
Check file sharing permissions
Ensure OAuth user has access to the file
Try accessing file directly in browser first

症状： 文件ID有效但出现“文件未找到”错误 原因： 无文件访问权限、文件已删除或文件ID错误 解决方案：

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

Issue: Quota exceeded

问题：配额超出

Symptoms: "User rate limit exceeded" or "Quota exceeded" error Cause: Too many API requests in 24-hour period Solution:

Wait 24 hours for quota reset
Create a new Google Cloud project with fresh quota
Implement exponential backoff in scripts
Reduce frequency of API calls

症状： 出现“用户速率限制超出”或“配额超出”错误 原因： 24小时内API请求过多 解决方案：

等待24小时配额重置
创建新的Google Cloud项目以获取新配额
在脚本中实现指数退避机制
减少API调用频率

Issue: settings.yaml missing

问题：settings.yaml缺失

Symptoms: "settings.yaml not found" or PyDrive2 configuration error Cause: Missing PyDrive2 configuration file Solution:

Copy from template:
```
cp settings.yaml.example settings.yaml
```
Ensure
```
client_secrets.json
```
path is correct in settings
Verify save_credentials_backend is set to "file"
Check settings.yaml is in the script's working directory

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

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

Issue: client_secrets.json invalid

问题：client_secrets.json无效

Symptoms: "Invalid client secrets" or OAuth configuration error Cause: Malformed or incorrect OAuth credentials file Solution:

Re-download from Google Cloud Console
Ensure "Desktop app" type was selected when creating credentials
Check JSON format is valid
Verify redirect URIs are configured for local auth

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

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

Issue: Scope access denied

问题：权限范围被拒绝

Symptoms: "Insufficient permission" error Cause: OAuth consent missing required scopes Solution:

Delete
```
mycreds.txt
```
to reset OAuth session
Re-authenticate and accept all requested scopes
Verify scopes in
```
settings.yaml
```
match script requirements
Check Google Cloud Console for scope restrictions

症状： 出现“权限不足”错误 原因： OAuth授权缺少所需的权限范围 解决方案：

删除
```
mycreds.txt
```
以重置OAuth会话
重新认证并接受所有请求的权限范围
验证
```
settings.yaml
```
中的权限范围与脚本要求匹配
检查Google Cloud Console的权限范围限制

Resources

资源

references/drive-search.md - Search files and folders
references/drive-upload.md - Upload files to Drive
references/folder-structure.md - Create folder hierarchies
references/create-folder.md - Create client folders
references/transcript-search.md - Search transcript files
references/gmail-search.md - Search Gmail
references/calendar-search.md - Search calendar meetings

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 - 搜索日历会议

Integration Patterns

集成模式

Drive to Video Production

Drive到视频制作

Skills: google-workspace → video-production Use case: Assemble course videos from Drive folder Flow:

Search Drive for video folder with lesson files
Download videos via video-production scripts
Stitch videos with title slides and upload final output

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

搜索Drive中包含课程文件的视频文件夹
通过video-production脚本下载视频
将视频与标题幻灯片拼接并上传最终输出

Templates to Content

模板到内容

Skills: google-workspace → content-generation Use case: Generate documents from branded templates Flow:

Load template from Drive (proposal, report format)
Generate content via content-generation
Create new Google Doc with formatted content

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

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

Calendar to Transcripts

日历到转录文件

Skills: google-workspace → transcript-search Use case: Find meeting recordings from calendar events Flow:

Search calendar for meetings with specific client
Get meeting dates and titles
Search transcript-search for matching recordings

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

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