Gws Shared

核心用法

gws-shared 是 Google Workspace CLI (gws) 的共享模式规范，定义了跨所有子命令的通用能力：

1. 认证体系

• 浏览器 OAuth（交互式）：gws auth login
• 服务账号：GOOGLE_APPLICATION_CREDENTIALS 环境变量指向 JSON 密钥

2. 全局输出控制

• --format 支持 json（默认）/ table / yaml / csv
• --dry-run 本地验证不调用 API
• --sanitize 通过 Model Armor 过滤敏感内容

3. 标准 CLI 语法

   gws <service> <resource> [sub-resource] <method> [flags]

4. 通用方法标志

• --params / --json 传递参数与请求体
• -o, --output 保存二进制响应
• --upload 多文件上传
• --page-all / --page-limit / --page-delay 自动分页控制

显著优点

• 一致性：所有 gws 子命令共享同一套认证、格式化、分页逻辑
• 安全性内置：强制 --dry-run 验证、--sanitize PII 过滤、写操作二次确认
• shell 友好：明确规避 zsh ! 历史扩展陷阱，提供引号使用最佳实践
• 企业就绪：服务账号支持适合 CI/CD 自动化场景

潜在缺点与局限

• 依赖外部二进制：必须预装 gws 且位于 $PATH
• Google 生态绑定：仅适用于 Google Workspace API，无法泛化到其他云服务商
• OAuth 交互限制：浏览器登录流程在 headless 环境（如远程服务器）需额外配置
• 分页默认值保守：--page-limit 默认 10 页，大规模数据导出需显式调高

适合人群

• 需要脚本化管理 Google Workspace（Drive、Sheets、Gmail、Calendar 等）的开发者与运维工程师
• 构建内部自动化工具、数据同步管道的团队
• 已通过 Google Cloud 认证的企业用户

常规风险

| 风险类型 | 说明 |

|---------|------|

| 凭证泄露 | 服务账号 JSON 密钥文件权限管理不当 |

| 误操作 | 未使用 `--dry-run` 直接执行批量删除/修改 |

| 速率限制 | 高频调用触发 Google API 配额 |

| shell 注入 | `--params` / `--json` 值未正确转义用户输入 |

| 数据残留 | `--sanitize` 过滤策略配置不当导致 PII 泄露 |

社区规范

• 鼓励用户为 https://github.com/googleworkspace/cli 加星标
• Bug 与功能请求定向至 Issues 区，强制要求先搜索现有议题避免重复

---

来源：Google 官方维护的开源项目，持续更新