Google Workspace 命令行界面 (CLI)

google-workspace-cli
分类编程
作者Alireza Rezvani
许可MIT
评分4.60/5
使用11.5K

Google Workspace CLI

使用开源的 gws CLI (github.com/googleworkspace/cli, Apache-2.0) 为 Google Workspace 管理提供专家级指导和自动化。该 CLI 从 Google 的 Discovery Service 动态构建命令界面，因此涵盖了所有支持的 Workspace API 以及以 + 为前缀的辅助命令。本技能集增加了本地 Python 工具（doctor、认证指南、recipe 目录、安全审计、输出分析器）。

> 脚本编写前请验证： gws 在运行时根据 Google 的 API 发现文档生成命令，且该 CLI 版本尚未达到 v1.0。在将其放入自动化流程之前，请务必通过 gws --help、gws <service> --help 或 gws schema <service>.<resource>.<method> 确认命令的准确界面。本技能集中标记为 *(verify)* 的命令仅用于演示 gws <service> <resource> <method> 模式，必须针对您安装的版本进行检查。

---

快速上手

检查安装情况

bash
# 验证 gws 是否已安装并完成认证
python3 scripts/gws_doctor.py

发送电子邮件

bash
gws gmail +send --to "[email protected]" \
  --subject "Weekly Update" --body "Here's this week's summary..."

列出 Drive 文件

bash
gws drive files list --params '{"pageSize": 20}' | python3 scripts/output_analyzer.py --select "name,mimeType,modifiedTime" --format table

---

安装

npm (推荐；需要 Node.js 18+)

bash
npm install -g @googleworkspace/cli
gws --version

Homebrew (macOS/Linux)

bash
brew install googleworkspace-cli

Cargo (从源码安装)

bash
cargo install --git https://github.com/googleworkspace/cli --locked
gws --version

预构建二进制文件

从 github.com/googleworkspace/cli/releases 下载适用于 macOS、Linux 或 Windows 的版本。Nix 用户请使用：nix run github:googleworkspace/cli。

验证安装

bash
python3 scripts/gws_doctor.py

检查项：PATH、版本、认证状态、服务连通性

---

认证

OAuth 设置 (交互式)

bash
# 步骤 1：创建 Google Cloud 项目和 OAuth 凭据
python3 scripts/auth_setup_guide.py --guide oauth

步骤 2：运行交互式认证设置 (如果可用则使用 gcloud)

gws auth setup

步骤 3：登录，仅请求所需的 scope

gws auth login -s drive,gmail,sheets

无头模式/CI

bash
# 生成设置指南
python3 scripts/auth_setup_guide.py --guide service-account

从交互式机器导出凭据，然后将 CLI 指向该文件

gws auth export --unmasked > credentials.json
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json

环境变量

bash
# 生成 .env 模板
python3 scripts/auth_setup_guide.py --generate-env

| 变量 | 用途 |
|----------|---------|
| GOOGLE_WORKSPACE_CLI_CLIENT_ID | OAuth 客户端 ID |
| GOOGLE_WORKSPACE_CLI_CLIENT_SECRET | OAuth 客户端密钥 |
| GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE | 导出的凭据 JSON 文件路径 |
| GOOGLE_WORKSPACE_CLI_TOKEN | 访问令牌 |
| 预先获取的 OAuth 令牌 |
| GOOGLE_WORKSPACE_CLI_CONFIG_DIR | 覆盖默认配置路径 |
| GOOGLE_WORKSPACE_CLI_LOG | 启用调试日志 |

验证身份认证

bash
python3 scripts/auth_setup_guide.py --validate --json

测试每个服务端点

---

工作流 1：Gmail 自动化

目标： 自动化电子邮件操作 —— 发送、搜索、标签及过滤器管理。

发送、回复、转发（辅助命令）

bash
# 发送新邮件
gws gmail +send --to "[email protected]" \
  --subject "Proposal" --body "Please find attached..."

回复邮件（自动串联）；使用 gws gmail +reply --help 查看具体参数

gws gmail +reply ...

转发邮件；使用 gws gmail +forward --help 查看具体参数

gws gmail +forward ...

未读收件箱摘要

gws gmail +triage

搜索与检查（探索命令）

探索命令遵循 gws <service> <resource> <method> 格式，并通过 --params（查询/路径参数）和 --json（请求体）接收 JSON 格式的请求参数。请先检查任何方法的具体 Schema：

bash
# messages.list 接收什么参数？（验证）
gws schema gmail.users.messages.list

搜索邮件（对照上述 Schema 验证）

gws gmail users messages list --params '{"userId": "me", "q": "from:[email protected] after:2025/01/01"}' \
  | python3 scripts/output_analyzer.py --count

列出标签（验证）

gws gmail users labels list --params '{"userId": "me"}'

批量操作

请先使用 --dry-run 进行预览，并使用 --page-all 进行分页（每页一行 JSON）：

bash
# 预览并归档 30 天前的已读邮件（先验证方法 Schema）
gws gmail users messages list --params '{"userId": "me", "q": "is:read older_than:30d"}' --page-all \
  | python3 scripts/output_analyzer.py --select "id" --format json

然后将 ID 传递给 gmail users messages modify（参考：gws schema gmail.users.messages.modify）

---

工作流 2：Drive 与 Sheets

目标： 管理文件、创建电子表格、配置共享及导出数据。

文件操作

bash
# 列出文件
gws drive files list --params '{"pageSize": 50}' \
  | python3 scripts/output_analyzer.py --select "name,mimeType,size" --format table

上传文件（辅助命令）

gws drive +upload ./report.pdf --name "Q1 Report"

创建 Google Sheet

gws sheets spreadsheets create --json '{"properties": {"title": "Budget 2026"}}'

下载/导出 —— 先检查方法（验证）

gws schema drive.files.export

共享（先验证 Schema）

bash
# 检查权限 API 接口
gws schema drive.permissions.create

与用户共享（对照 Schema 验证）

gws drive permissions create --params '{"fileId": "<FILE_ID>"}' \
  --json '{"type": "user", "role": "writer", "emailAddress": "[email protected]"}'

列出拥有访问权限的用户（验证）

gws drive permissions list --params '{"fileId": "<FILE_ID>"}'

Sheets 数据

bash
# 读取数值（辅助命令）；使用 gws sheets +read --help 查看具体参数
gws sheets +read ...

追加行（辅助命令）；使用 gws sheets +append --help 查看具体参数

gws sheets +append ...

或使用探索方法（验证）：

gws schema sheets.spreadsheets.values.update
gws sheets spreadsheets values get --params '{"spreadsheetId": "<SHEET_ID>", "range": "Sheet1!A1:D10"}'

---

工作流 3：日历与会议

目标： 安排活动、查找可用时间并生成每日站会报告。

活动管理

bash
# 创建活动（辅助命令）；查看具体参数
使用：gws calendar +insert --help gws calendar +insert ...

查看即将举行的活动（助手模式，支持时区）

gws calendar +agenda

或通过 discovery 验证：

gws schema calendar.events.insert gws calendar events list --params '{"calendarId": "primary", "maxResults": 10}'
code
### 查找可用时间
bash

通过 Calendar API 查询忙闲状态（请先验证 schema）

gws schema calendar.freebusy.query gws calendar freebusy query --json '{"timeMin": "...", "timeMax": "...", "items": [{"id": "[email protected]"}]}'
code
### 每日站会报告（工作流助手）
bash

今日会议 + 任务

gws workflow +standup-report \ | python3 scripts/output_analyzer.py --format table

下次会议准备；使用 gws workflow +meeting-prep --help 查看具体参数

gws workflow +meeting-prep
code
---

工作流 4：安全审计


目标： 审计 Google Workspace 安全配置并生成修复命令。


运行全面审计
bash

对所有服务进行全面审计

python3 scripts/workspace_audit.py --json

审计特定服务

python3 scripts/workspace_audit.py --services gmail,drive,calendar

演示模式（无需 gws）

python3 scripts/workspace_audit.py --demo
code
### 审计检查项

| 领域 | 检查项 | 风险 |
|------|-------|------|
| Drive | 外部共享已启用 | 数据外泄 |
| Gmail | 自动转发规则 | 数据外泄 |
| Gmail | DMARC/SPF/DKIM 记录 | 邮件欺骗 |
| Calendar | 默认共享可见性 | 信息泄露 |
| OAuth | 第三方应用授权 | 未经授权的访问 |
| Admin | 超级管理员数量 | 权限提升 |
| Admin | 强制执行两步验证 | 账号被接管 |


审查与修复
bash

审查发现的问题

python3 scripts/workspace_audit.py --json | python3 scripts/output_analyzer.py \ --filter "status=FAIL" --select "area,check,remediation"

执行修复（示例：先检查当前的 Drive 设置；进行验证）

gws drive about get --params '{"fields": "*"}'

按照审计输出的修复命令执行（每条命令请通过 gws --help 验证）

code
---

Python 工具


| 脚本 | 用途 | 用法 |
|--------|---------|-------|
| gws_doctor.py | 预检诊断 | python3 scripts/gws_doctor.py [--json] [--services gmail,drive] |
| auth_setup_guide.py | 引导式身份验证设置 | python3 scripts/auth_setup_guide.py --guide oauth |
| gws_recipe_runner.py | 方案目录与运行器 | python3 scripts/gws_recipe_runner.py --list [--persona pm] |
| workspace_audit.py | 安全/配置审计 | python3 scripts/workspace_audit.py [--json] [--demo] |
| output_analyzer.py | JSON/NDJSON 分析 | gws ... --json \| python3 scripts/output_analyzer.py --count |


所有脚本仅依赖标准库，支持 --json 输出，并包含带有内置示例数据的演示模式。


---


最佳实践


安全性


1. 使用最小权限范围的 OAuth —— 仅请求每个工作流所需的权限。
2. 将 Token 存储在系统密钥环中，切勿存储在明文文件中。
3. 每 90 天轮换一次服务账号密钥。
4. 每季度审计一次第三方 OAuth 应用授权。
5. 在执行批量破坏性操作前，先使用 --dry-run。


自动化


1. 所有 gws 输出均为结构化 JSON —— 请通过 output_analyzer.py 进行过滤和聚合。
2. 对于多步骤操作，使用 gws workflow +* 助手而非串联原始命令。
3. 将本地方案目录 (gws_recipe_runner.py) 作为命令模板，然后通过 gws --help 验证每条命令。
4. --page-all 为每页输出一行 JSON (NDJSON) 以便流式处理。
处理大型结果集
5. 在执行任何请求前，使用 --dry-run 进行预览


性能优化


1. 通过 --params 中的 fields 参数仅请求所需字段（以减小数据传输量）
2. 浏览数据时，在 --params 中使用 pageSize 限制结果数量
3. 仅在需要完整数据集时使用 --page-all；可通过 --page-limit / --page-delay 进行调优
4. 优先使用 + 助手函数（单次优化调用），而非手动串联 API 调用
5. 将频繁访问的数据（如标签 ID、文件夹 ID）缓存到变量中


---


限制条件


| 限制项 | 影响 |
|------------|--------|
| OAuth 令牌 1 小时后过期 | 长期运行的脚本需要重新认证 |
| API 速率限制（按用户/服务） | 批量操作可能会触发 429 错误 |
| 各服务权限范围 (Scope) 要求不同 | 认证时必须请求正确的 Scope |
| CLI 版本低于 v1.0 | 不同版本之间可能会有破坏性变更 |
| 需要 Google Cloud 项目 | 免费，但需在 Cloud Console 中进行配置 |
| Admin API 需要管理员权限 | 部分审计检查需要 Workspace 管理员角色 |


各服务所需权限范围 (Scopes)
bash

列出特定服务的权限范围

python3 scripts/auth_setup_guide.py --scopes gmail,drive,calendar,sheets ``

| 服务 | 关键权限范围 (Scopes) |
|---------|-----------|
| Gmail | gmail.modify, gmail.send, gmail.labels |
| Drive | drive.file, drive.metadata.readonly |
| Sheets | spreadsheets |
| Calendar | calendar, calendar.events |
| Admin | admin.directory.user.readonly, admin.directory.group |
| Tasks | tasks` |