企业官网建设流程全解析

用 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 是gws（Google Workspace CLI）为 Admin SDKreports_v1API 自动生成的操作指南，覆盖管理员审计日志（Audit logs）与使用量报告（Usage reports）的全部 5 类资源 7 个方法。读完本文，你将掌握gws admin-reports的命令语法、各 API 资源的方法语义、gws schema的参数自检流程，以及如何在真实环境中安全地拉取登录活动、Drive 操作审计与用户/客户/实体使用量报告。

一、背景：gws 如何暴露 Admin SDK Reports API

gws是一个用 Rust 编写、面向人类与 AI Agent 的 Google Workspace 统一命令行工具。它的核心设计理念是不内置静态命令清单，而是在运行时读取 Google 官方 Discovery Service 文档，动态构建全部命令树——当 Google Workspace 新增端点或方法时，gws会自动跟进（参见 README.md 的 Architecture 一节）。

Admin SDK Reports API 在gws中的服务注册信息位于 crates/google-workspace/src/services.rs：

ServiceEntry { 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.rs：resolve_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 语义参考。

二、环境准备：安装、认证与前置 Skill

gws-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 --locked

2.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 token）>GOOGLE_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）两大类能力：

说明：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 schema

SKILL.md 明确要求在调用任何 API 方法前先做两步自检：

# 1. 浏览资源与方法（含每个方法的说明） gws admin-reports --help # 2. 检查某个方法的必填参数、类型与默认值 gws schema admin-reports.<resource>.<method>

gws 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.get

gws schema的路径格式为service.resource[.subresource].method，也支持service.<Type>直接查看类型定义；资源/方法不存在时会有明确的可用项提示（见 crates/google-workspace-cli/src/schema.rs）。

拿到 schema 输出后，用它来构造--params（URL/查询参数）与--json（请求体，本服务基本用不到）flag。

六、实战：构造并执行 admin-reports 调用

gws的方法级 flags 由命令构建器统一生成（实现见 crates/google-workspace-cli/src/commands.rs），与 skills/gws-shared/SKILL.md 中记录的全局 flags 配合使用。

6.1 方法级 flags

6.2 全局 flags

6.3 典型命令示例

# 1) 查看某个用户最近 10 条登录活动（审计日志） gws admin-reports activities list \ --params '{"userKey": "alice@example.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 一节）。
• 若返回accessNotConfigured（403），说明 GCP 项目中未启用 Admin SDK API，需在 Cloud Console 启用对应 API 后重试（README 的 Troubleshooting 一节有完整排查路径）。

七、底层原理：从服务名到 HTTP 请求

理解这条调用链有助于排查问题与扩展用法：

1. 服务解析：gws读取argv[1]（如admin-reports），在服务注册表中查得("admin", "reports_v1")，见 crates/google-workspace/src/services.rs。未注册的服务名会提示可用列表，并支持<api>:<version>直接指定任意未收录 API。
2. Discovery 拉取：按api_name:version获取该 API 的 Discovery 文档（带 24 小时缓存）。
3. 命令树构建：把文档中的 resources/methods 递归转换成 clap 子命令树，按需挂载--params、--json、--page-all等 flag，见 crates/google-workspace-cli/src/commands.rs。
4. 二次解析：用构建好的命令树重新解析剩余参数。
5. 认证与执行：选择认证来源、组装 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 的审计日志与使用量报告能力浓缩为一条命令：activities（list/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