用 gws CLI 调用 Google Workspace Admin SDK Reports：审计日志与使用量报告完整实战指南

用 gws CLI 调用 Google Workspace Admin SDK Reports审计日志与使用量报告完整实战指南【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cli本文基于 skills/gws-admin-reports/SKILL.md 展开。该 Skill 是gwsGoogle Workspace CLI为 Admin SDKreports_v1API 自动生成的操作指南覆盖管理员审计日志Audit logs与使用量报告Usage reports的全部 5 类资源 7 个方法。读完本文你将掌握gws admin-reports的命令语法、各 API 资源的方法语义、gws schema的参数自检流程以及如何在真实环境中安全地拉取登录活动、Drive 操作审计与用户/客户/实体使用量报告。一、背景gws 如何暴露 Admin SDK Reports APIgws是一个用 Rust 编写、面向人类与 AI Agent 的 Google Workspace 统一命令行工具。它的核心设计理念是不内置静态命令清单而是在运行时读取 Google 官方 Discovery Service 文档动态构建全部命令树——当 Google Workspace 新增端点或方法时gws会自动跟进参见 README.md 的 Architecture 一节。Admin SDK Reports API 在gws中的服务注册信息位于 crates/google-workspace/src/services.rsServiceEntry { aliases: [admin-reports, reports], api_name: admin, version: reports_v1, description: Audit logs and usage reports, },也就是说服务别名alias为admin-reports同时支持简写别名reports底层对应 Google API 名admin、版本reports_v1服务描述为Audit logs and usage reports审计日志与使用量报告。该注册逻辑有单元测试直接印证见 crates/google-workspace/src/services.rsresolve_service(admin-reports)与resolve_service(reports)均解析为(admin, reports_v1)未知服务名则会返回Unknown service校验错误。gws的技能文件SKILL.md也是自动生成的由gws generate-skills依据 CLI 自身的 clap 元数据与 Discovery 文档批量产出生成器实现位于 crates/google-workspace-cli/src/generate_skills.rs。因此SKILL.md中每个资源、方法描述都直接取自 Discovery 文档原文可作为可靠的 API 语义参考。二、环境准备安装、认证与前置 Skillgws-admin-reports是一个服务级 Skill它的使用前提是gws二进制位于$PATH并已完成认证。SKILL.md 的 PREREQUISITE 明确要求先阅读 skills/gws-shared/SKILL.md认证、全局 flags、安全规则若该文件缺失运行gws generate-skills即可重新生成。2.1 安装 gws按 README.md 提供的安装方式任选其一# npm 自动下载对应平台的预编译二进制 npm install -g googleworkspace/cli # 或从源码构建 cargo install --git https://github.com/googleworkspace/cli --locked2.2 认证Admin SDK Reports API 属于管理员级 API需要具有相应管理权限的 Google Workspace 账号或服务账号授权。认证方式详见 skills/gws-shared/SKILL.md# 浏览器 OAuth交互式 gws auth login # 服务账号无浏览器环境适合 CI/服务器 export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE/path/to/key.json环境变量优先级依次为GOOGLE_WORKSPACE_CLI_TOKEN预获取的 access tokenGOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE凭据文件gws auth login加密存储的凭据 ~/.config/gws/credentials.json明文凭据。具体每个方法要求哪些 OAuth scope可通过下文gws schema输出的scopes字段确认该字段直接来自 Discovery 文档由 crates/google-workspace-cli/src/schema.rs 原样透出。三、命令语法与 API 资源总览统一命令语法为gws admin-reports resource method [flags]gws admin-reports下共 5 个资源、7 个方法覆盖审计日志activities、channels与使用量报告customerUsageReports、entityUsageReports、userUsageReport两大类能力资源方法用途activitieslist检索特定客户账号下某个应用如 Admin 控制台应用、Google Drive 应用的活动列表对应管理员活动报告与 Drive 活动报告其参数细节参见活动参数参考指南activitieswatch开始接收账号活动的推送通知Push Notificationschannelsstop停止通过某个 channel 继续监视资源customerUsageReportsget检索客户账号的属性与统计数据集合对应 Customers Usage Report 指南entityUsageReportsget检索账号内用户所用实体的属性与统计数据集合对应 Entities Usage Report 指南userUsageReportget检索账号内一组用户的属性与统计数据集合对应 User Usage Report 指南说明admin-reports资源下没有需要--json请求体的写方法全部以 GET 查询参数为主--json这类请求体 flag 由命令构建器按方法是否有 request schema 动态决定是否挂载见 crates/google-workspace-cli/src/commands.rs。四、各资源方法与实战要点4.1 activities审计日志审计日志是管理员排查安全事件的核心入口例如谁在什么时间登录了账号谁下载了哪个 Drive 文件。list检索指定客户账号与应用的审计活动列表典型应用场景包括 Admin 控制台活动管理员操作审计与 Google Drive 活动文件共享、下载、权限变更审计。查询参数如用户键、应用名、事件名、时间范围、过滤器、分页等的完整清单以gws schema admin-reports.activities.list输出为准。watch注册一个 channel让 Google 在有新活动时通过推送通知Push Notifications主动送达适合构建持续审计的监控管道。channel 的配置参数如 channelId、地址等同样以gws schema admin-reports.activities.watch输出为准。4.2 channels推送通道管理stop停止通过某个 channel 继续监视资源。与activities.watch成对使用——当你不再需要某条推送通道时调用它以释放资源并停止计费与流量。4.3 customerUsageReports客户使用量报告get检索整个客户账号customer层面的使用量聚合统计例如各应用的整体活跃度、存储占用等。适合生成组织级周报/月报。4.4 entityUsageReports实体使用量报告get检索账号内实体entities的使用统计即按用户之外的对象维度如 Drive 文档等实体聚合的用量数据适合回答哪些实体被高频使用之类的问题。4.5 userUsageReport用户使用量报告get按用户维度聚合使用量统计是某个用户上周登录了多少次、用了多少存储这类问题的标准答案来源。通常需要指定目标用户键与报告日期具体参数与必填项以gws schema admin-reports.userUsageReport.get输出为准。五、调用前的自检流程--help 与 gws schemaSKILL.md 明确要求在调用任何 API 方法前先做两步自检# 1. 浏览资源与方法含每个方法的说明 gws admin-reports --help # 2. 检查某个方法的必填参数、类型与默认值 gws schema admin-reports.resource.methodgws schema是参数自检的关键它从 Discovery 文档拉取目标方法定义输出httpMethod、path、完整parameters含required、type、location、format、default、enum、repeated等字段、所需scopes以及请求/响应体 schema见 crates/google-workspace-cli/src/schema.rs。例如# 查看 activities.list 的全部参数与权限要求 gws schema admin-reports.activities.list # 查看 userUsageReport.get 的参数含必填项 gws schema admin-reports.userUsageReport.getgws schema的路径格式为service.resource[.subresource].method也支持service.Type直接查看类型定义资源/方法不存在时会有明确的可用项提示见 crates/google-workspace-cli/src/schema.rs。拿到 schema 输出后用它来构造--paramsURL/查询参数与--json请求体本服务基本用不到flag。六、实战构造并执行 admin-reports 调用gws的方法级 flags 由命令构建器统一生成实现见 crates/google-workspace-cli/src/commands.rs与 skills/gws-shared/SKILL.md 中记录的全局 flags 配合使用。6.1 方法级 flagsFlag说明--params {key: val}URL/查询参数JSON 字符串--json {key: val}请求体仅当方法声明了 request schema 时存在-o, --output PATH将二进制响应保存到文件--page-all自动翻页每页输出一行 JSONNDJSON--page-limit N--page-all最大翻页数默认 10--page-delay MS翻页间隔毫秒数默认 1006.2 全局 flagsFlag说明--format FORMAT输出格式json默认、table、yaml、csv--dry-run仅本地校验不真正调用 API--sanitize TEMPLATE通过 Model Armor 模板对响应做内容安全过滤6.3 典型命令示例# 1) 查看某个用户最近 10 条登录活动审计日志 gws admin-reports activities list \ --params {userKey: aliceexample.com, applicationName: login, maxResults: 10} # 2) 查看 Drive 应用的审计活动并以表格输出 gws admin-reports activities list \ --params {userKey: all, applicationName: drive} \ --format table # 3) 拉取整个客户账号某天的使用量报告customer 维度 gws admin-reports customerUsageReports get \ --params {date: 2026-09-17} # 4) 拉取全部用户的使用量报告并自动翻页NDJSON 流式输出 gws admin-reports userUsageReport get \ --params {userKey: all, date: 2026-09-17} \ --page-all | jq -r .usageReport[].date # 5) 只做参数本地校验不真正发起请求写操作与批量前务必先跑 gws admin-reports channels stop \ --params {id: CHANNEL_ID, resourceId: RESOURCE_ID} \ --dry-run注意 zsh 历史展开问题参数值中含!时用双引号包裹外层JSON 参数统一用单引号包裹避免 shell 吞掉内部双引号详见 skills/gws-shared/SKILL.md 的 Shell Tips。6.4 输出与错误处理所有输出均为结构化 JSON--format可切 table/yaml/csv方便 Agent 或脚本直接消费。退出码可编程化0成功、1API 错误4xx/5xx、2认证错误、3参数校验错误、4Discovery 拉取失败、5内部错误见 README.md 的 Exit Codes 一节。若返回accessNotConfigured403说明 GCP 项目中未启用 Admin SDK API需在 Cloud Console 启用对应 API 后重试README 的 Troubleshooting 一节有完整排查路径。七、底层原理从服务名到 HTTP 请求理解这条调用链有助于排查问题与扩展用法服务解析gws读取argv[1]如admin-reports在服务注册表中查得(admin, reports_v1)见 crates/google-workspace/src/services.rs。未注册的服务名会提示可用列表并支持api:version直接指定任意未收录 API。Discovery 拉取按api_name:version获取该 API 的 Discovery 文档带 24 小时缓存。命令树构建把文档中的 resources/methods 递归转换成 clap 子命令树按需挂载--params、--json、--page-all等 flag见 crates/google-workspace-cli/src/commands.rs。二次解析用构建好的命令树重新解析剩余参数。认证与执行选择认证来源、组装 HTTP 请求--dry-run则在此前停下、执行并输出结构化结果。这一两阶段解析 Discovery 驱动的架构使得admin-reports的任何新方法在 Google 发布后即可直接使用无需升级二进制详见 README.md 的 Architecture 一节。八、Skill 的自动生成与维护skills/gws-admin-reports/SKILL.md是gws generate-skills的产物其结构frontmatter → 标题 → PREREQUISITE → 命令语法 → API Resources → Discovering Commands与生成模板一一对应见 crates/google-workspace-cli/src/generate_skills.rs。frontmatter 中的cliHelp: gws admin-reports --help供 OpenClaw 等 Agent 运行时定位帮助命令。因此若gws升级后方法描述有变化重新运行gws generate-skills即可让本地 Skill 与 CLI 版本当前为 0.22.5保持同步Skill 清单总览见 docs/skills.md同样自动生成请勿手改。九、安全与合规实践Reports API 触及组织级敏感数据登录记录、文件操作、用量统计skills/gws-shared/SKILL.md 中的安全规则在此尤其重要绝不直接输出密钥/token审计结果可能包含敏感信息注意脱敏后再转发写/删操作先确认channels stop属于有副作用的操作先--dry-run校验参数优先--dry-run批量或破坏性场景先本地校验PII 过滤对含个人信息的报告输出可用--sanitize接入 Model Armor 做内容安全过滤。与之配套的 persona-it-admin 也把监控可疑登录活动、审阅审计日志列为日常运维流程与gws admin-reports的能力形成闭环。十、小结gws admin-reports把 Google Workspace Admin SDK Reports API 的审计日志与使用量报告能力浓缩为一条命令activitieslist/watch覆盖审计日志与推送监控channels.stop管理推送通道customerUsageReports/entityUsageReports/userUsageReport的get覆盖客户、实体、用户三个维度的使用量报告。配合--help与gws schema的自检流程、--dry-run/--format/--page-all等执行控制无论是人工运维还是 AI Agent 自动化都能以零样板代码的方式稳定获取并消费这些管理数据。【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考