企业官网建设流程全解析

gogcligog drive activity命令完全指南：在终端中查询 Google Drive 审计活动事件

【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli

导读

gog drive activity是 gogcli（Google Workspace in your terminal）提供的 Drive Activity 审计命令组，它让开发者、安全团队与自动化脚本无需打开 Google Cloud Console 或编写自定义 API 客户端，即可在终端中直接查询 Drive 上"谁在何时对哪个文件做了什么"的完整审计轨迹。本文将以 docs/commands/gog-drive-activity.md 为主体，结合其子命令文档 docs/commands/gog-drive-activity-query.md 与仓库源码实现，完整讲解命令用法、全部筛选参数、过滤表达式生成规则、分页与脚本化输出策略。读完本文，你将可以独立完成"按文件/文件夹/时间/动作维度查询 Drive 活动、将结果接入 CI 与告警流水线"的实战任务。

命令总览：gog drive activity

gog drive activity是一个父命令，它本身不直接发起查询，而是通过唯一的子命令gog drive activity query对外暴露能力。其核心职责是"Query Drive Activity audit events"（查询 Drive Activity 审计事件），整体依赖 Google 官方的 Drive Activity API v2（driveactivity.googleapis.com）。

gog drive (drv) activity <command>

• 别名：drv是drive的别名，因此gog drv activity query ...与gog drive activity query ...等价；
• 子命令：query（别名list、ls），即 gog drive activity query。

从源码看，父命令结构定义在 internal/cmd/drive_activity.go：

type DriveActivityCmd struct { Query DriveActivityQueryCmd `cmd:"" name:"query" aliases:"list,ls" help:"Query Drive Activity API v2"` }

gog drive activity本身继承gog drive命令组的全部通用旗标，其中包括账号选择（--account）、输出格式（--json/--plain）、只读保护（--readonly）、安全检查（--gmail-no-send）等，这些旗标会一并传递给子命令。

子命令：gog drive activity query

gog drive activity query是实际执行查询的命令，用法如下：

gog drive (drv) activity query (list,ls) [flags]

query支持三个互通的命令名：query、list、ls。它调用 Drive Activity API v2 的Activity.Query端点（对应 HTTP POST/v2/activity:query），这在测试用例 internal/cmd/drive_changes_activity_test.go 中得到了验证：测试通过httptest断言请求路径为/v2/activity:query，并校验了请求体中的ItemName与Filter字段。

核心查询参数

动作筛选（--actions）的取值与映射

--actions接收的是人类友好的短名，源码会在构建请求前把它们映射为 Drive Activity API 的action_detail_case枚举值。完整映射表见 internal/cmd/drive_activity.go：

几点重要行为：

• 多个动作用逗号分隔，如--actions edit,share；
• 大小写不敏感，内部会统一ToLower后匹配；
• 重复映射自动去重：例如同时传share,permission_change只会生成一个PERMISSION_CHANGE；
• 传入未知动作会直接报用法错误unknown Drive Activity action %q（测试 internal/cmd/drive_changes_activity_test.go 中验证了该错误与退出码 2）。

过滤表达式的生成规则（源码级）

这是本命令最值得关注的内幕。query并不直接把--from/--to/--actions原样透传给 API，而是由driveActivityFilter函数（internal/cmd/drive_activity.go）将它们组装成一个合法的 Drive Activity 过滤表达式：

• --from→time >= "RFC3339时间"；
• --to→time <= "RFC3339时间"；
• --actions只有一个时 →detail.action_detail_case:EDIT；
• --actions有多个时 →detail.action_detail_case:(EDIT PERMISSION_CHANGE)（注意括号内的空格分隔）；
• --filter提供原始表达式 → 原样追加；
• 各部分用AND连接。

测试用例 internal/cmd/drive_changes_activity_test.go 给出了具体验证：当传入("edit,share", "2026-01-01T00:00:00Z", "2026-01-02T00:00:00Z", "detail.action_detail_case:-MOVE")时，最终过滤串同时包含time >= "2026-01-01T00:00:00Z"、time <= "2026-01-02T00:00:00Z"、detail.action_detail_case:(EDIT PERMISSION_CHANGE)与原始的detail.action_detail_case:-MOVE（否定式排除）。

利用这一点，你可以做到比--actions更细粒度的筛选，例如"排除移动动作、只看编辑"：

gog drive activity query --file 1ABCxyz... --actions edit --filter "detail.action_detail_case:-MOVE"

请求体的组装

queryRequest函数（internal/cmd/drive_activity.go）负责把旗标组装为QueryDriveActivityRequest：

• --max直接写入PageSize，且必须大于 0，否则报用法错误（测试验证了--max 0与--max -1都会在创建 API 服务之前失败并返回退出码 2）；
• --file会规范化 ID：若用户直接传items/xxx前缀，代码会用strings.TrimPrefix去掉后统一拼成items/<ID>作为ItemName；
• --folder同样规范化后作为AncestorName（祖先路径），因此查询文件夹会包含其全部后代的活动；
• --file与--folder互斥，同时传入会报use either --file or --folder, not both；
• --consolidate时设置ConsolidationStrategy{Legacy: &Legacy{}}，即使用 API 提供的 legacy 合并策略（把同一对象的连续相似活动合并为一条）。

分页与全量拉取

与项目其他列表类命令一致，query通过loadPagedItems（internal/cmd/paged_list_helpers.go）处理分页：

• 默认只取当前页（--max指定页大小，默认 10）；
• 传入--page <token>可继续翻页，token 来自上一轮输出的nextPageToken；
• 传入--all时调用collectAllPages（internal/cmd/paging.go）持续拉取直至nextPageToken为空，并带有分页死循环防护（pageTokenGuard会记录已见过的 token）。

如果当前页之后还有更多数据，终端输出末尾会提示：

# More results: use --all to fetch every page, or --page <token> for the next page

该提示由printNextPageHintWithAll（internal/cmd/output_helpers.go）生成。

输出格式与脚本化

默认 TSV 表格

非 JSON 模式下，query以制表符分隔输出表头TIME ACTION ACTOR TARGET（internal/cmd/drive_activity.go）：

• TIME：优先取activity.Timestamp；若活动只带时间范围（TimeRange），则取起始时间StartTime；
• ACTION：由driveActivityActionName根据PrimaryActionDetail判断，输出与--actions一致的短名（edit、create、comment、permission_change等）；
• ACTOR：由driveActivityActors生成，能区分多种主体类型：
  • 当前登录用户显示为me；
  • 已知用户显示其PersonName；
  • 已删除用户显示deleted_user，未知用户显示unknown_user；
  • 管理员操作显示administrator，系统操作显示system；
  • 匿名用户anonymous、模拟身份impersonation也各有标签；
  • 多个主体以逗号连接。
• TARGET：由driveActivityTargets生成，对 Drive 文件优先取标题（title），标题为空时回退到name；对 Drive 本身取Title；对文件评论取父文件标题。

注意单元格内的制表符会被sanitizeTab替换为空格，以保证 TSV 结构不被破坏。

JSON 模式（推荐用于脚本）

加-j/--json后，输出结构为：

{ "activities": [ ... ], "nextPageToken": "..." }

要点：

• activities为 Drive Activity API 的原始对象数组（包含timestamp、primaryActionDetail、actors、targets等完整字段）；
• nextPageToken用于继续分页，配合--page使用；
• --results-only可丢弃nextPageToken等信封字段，只保留主结果；
• 空结果时 JSON 中activities为空数组，且不会打印终端的人类可读提示。

无结果时的退出码约定

--fail-empty（别名--non-empty、--require-results）允许把"无活动"变成可编程判断的信号：当查询结果为空时，命令以退出码 3退出（emptyResultsExitCode = 3，定义见 internal/cmd/paging.go）。这在 CI/告警脚本中非常有用，例如"当日 24 小时没有任何文件共享活动即告警"：

gog drive activity query --from 2026-01-01T00:00:00Z \ --actions share --fail-empty --json if [ $? -eq 3 ]; then echo "no share activity in the window" | ./notify fi

结合其他通用旗标

父命令与子命令共享一批全局旗标，其中与本主题强相关的有：

例如，一个只读审计脚本可以这样加固：

gog drive activity query --folder 0Bxxxx --readonly \ --no-input --json --results-only --max 50

权限与账号授权

Drive Activity 是一个只读审计服务，其 OAuth scope 为https://www.googleapis.com/auth/drive.activity.readonly。在 gogcli 的认证体系中，它对应driveactivity服务（见 internal/googleauth/service.go），服务备注明确写着："Read-only audit/activity scope; authorize with --services driveactivity"。

因此在使用前，若当前账号尚未授权该 scope，需要执行（参考 gog-auth-services）：

gog auth add --services driveactivity

或对已有多服务账号补充授权 driveactivity。底层实现上，internal/googleapi/driveactivity.go 通过newGoogleServiceForAccount按账号构建driveactivity.NewService，并注册了对应的 API 名driveactivity.googleapis.com（用于 API 启用检查）。

与其他 Drive 命令的分工

在gog drive命令族中，activity不是唯一的审计入口，它与其他命令存在明确分工：

如果你的诉求是"某文件最近被谁改过/分享过"，选activity；如果是"全盘盘点当前哪些文件被共享给了谁"，选audit；如果是"持续监听增量变化"，选changes。

典型实战场景

场景一：审计某个文件最近 7 天的全部活动

gog drive activity query --file 1ABCxyz... \ --from "$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%SZ)" \ --to "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --all

场景二：追踪某个共享文件夹内所有"共享/权限变更"事件（含后代）

gog drive activity query --folder 0Bxxxx --actions share,delete --all -p

场景三：把活动流喂给下游 Agent/LLM 流水线

gog drive activity query --file 1ABCxyz... --actions edit --json --results-only

（JSON 模式输出的原始activities数组字段完整，非常适合直接交给 LLM 或审计程序解析。）

场景四：监控"空窗口"并告警

结合--fail-empty与退出码 3（见上文）即可在无活动时触发告警分支。

小结与延伸阅读

gog drive activity把 Google Drive Activity API v2 的查询能力封装为一个易用的子命令：--file/--folder划定对象范围，--actions/--from/--to生成结构化过滤表达式，--filter提供原始表达式兜底，--all/--page解决分页，--fail-empty与退出码 3 服务脚本化判断，JSON 输出则面向 Agent 与自动化消费。配合--readonly与--no-input，它可以安全地嵌入只读审计与合规监控流水线。

若需继续深入，可阅读以下仓库资料：

• 命令文档：gog drive activity、gog drive activity query、父命令 gog drive
• 源码实现：internal/cmd/drive_activity.go（参数组装与过滤生成）、internal/googleapi/driveactivity.go（服务构建）
• 测试用例：internal/cmd/drive_changes_activity_test.go（过滤串与请求体验证）
• 认证与 scope：internal/googleauth/service.go（driveactivity服务定义）
• 通用分页/退出码机制：internal/cmd/paging.go、internal/cmd/paged_list_helpers.go

【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli