gog admin users list 详解:gogcli 中批量查询 Google Workspace 域用户的参数、分页与脚本化机制【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本篇以 gogcli 的命令参考文档gog-admin-users-list为主体,结合 internal/cmd/admin_users.go 的源码实现与 internal/cmd/admin_test.go 的测试用例,完整讲解gog admin users list的每个参数、表格/JSON 两种输出格式、分页令牌机制、退出码语义,以及运行该命令所需的 Workspace 管理员权限配置,帮助读者把它安全地集成到运维脚本与 CI 流程中。命令定位:gog admin管理面中的只读盘点命令gog admin子树基于 Google Admin SDK Directory API 实现 Workspace 用户、组织单元与群组的管理能力。gog admin users list(别名ls)是该子树中的只读查询命令,用于按域名列出用户,其父命令为gog admin users,完整命令族还包括get、create、delete、suspend,可参见 docs/commands/gog-admin-users.md。该文档页本身由gog schema --json自动生成(页首注明 Generated fromgog schema --json. Do not edit this page by hand),因此参数语义与运行时行为以源码为准,两者一致。基本用法(摘自 docs/commands/gog-admin-users-list.md):gog admin users list (ls) [flags]一个最小可用的调用(来自 docs/workspace-admin.md 的运维示例):gog --account adminexample.com admin users list --domain example.com --json命令级参数:五个决定查询行为的本地 Flag从源码结构看,AdminUsersListCmd结构体(internal/cmd/admin_users.go)只定义了 5 个本地字段,其余表格中的参数均继承自全局RootFlags:Flag别名类型默认值说明--domain—string无(必填)要列出用户的域名,例如example.com--max--limitint64100单页最大结果数(对应 Admin SDK 的maxResults)--page--cursorstring无分页令牌,用于续取下一页--all--all-pages、--allpagesbool否自动抓取所有页--fail-empty--non-empty、--require-resultsbool否查询无结果时以退出码 3 退出几个关键细节:--domain必填:源码中先对值做TrimSpace,为空直接返回usage(domain required (e.g., --domain example.com))(internal/cmd/admin_users.go)。--max是单页大小而非总上限:c.Max被传给svc.Users.List().MaxResults(c.Max)(internal/cmd/admin_users.go),配合--all时意味着每页 100 条、逐页拉完。--max小于等于 0 会报错max must be 0,且该校验发生在创建 Admin 服务之前——internal/cmd/admin_test.go 中的TestAdminListInvalidMaxFailsBeforeWorkspaceCheck用--max 0与--max -1验证了这一点,退出码为 2,并断言此时不应发起任何 API 请求。--fail-empty服务于脚本判断:无结果时通过 internal/cmd/paging.go 的failEmptyExit返回退出码 3(常量emptyResultsExitCode 3),便于 shell 中区分查询成功但域内无匹配用户与正常有结果。全局参数速查(文档 Flags 表的完整继承)原始参考文档给出了一张包含全部可见 Flag 的完整表格。除上表 5 个命令级参数外,其余为所有gog命令共享的全局参数,完整列表如下(与 docs/commands/gog-admin-users-list.md 一致):Flag类型默认说明--access-tokenstringUse provided access token directly (bypasses stored refresh tokens; token expires in ~1h)-a/--account/--acctstringAccount email, alias, or auto for authenticated Google API commands--clientstringOAuth client name (selects stored credentials token bucket)--colorstringautoColor output: auto|always|never--disable-commandsstringComma-separated list of disabled commands; dot paths allowed--enable-commandsstringComma-separated list of enabled command prefixes; dot paths allowed (restricts CLI)--enable-commands-exactstringComma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children-n/--dry-run/--dryrun/--noop/--previewboolDo not make changes; print intended actions and exit successfully-y/--force/--assume-yes/--yesboolSkip confirmations for destructive commands--gmail-no-sendboolfalseBlock Gmail send operations (agent safety)-h/--helpkong.helpFlagShow context-sensitive help.--homestringOverride gogcli config/data/state/cache root (equivalent to GOG_HOME)-j/--json/--machineboolfalseOutput JSON to stdout (best for scripting)--no-input/--non-interactive/--noninteractiveboolNever prompt; fail instead (useful for CI)-p/--plain/--tsvboolfalseOutput stable, parseable text to stdout (TSV; no colors)--quota-projectstringGoogle Cloud project to bill for API usage (sent as X-Goog-User-Project; some APIs require it with --access-token or ADC)--readonlyboolfalseBlock mutating API requests at runtime; auth add also requests read-only OAuth scopes--results-onlyboolIn JSON mode, emit only the primary result (drops envelope fields like nextPageToken)--select/--pick/--projectstringIn JSON mode, select comma-separated fields (best-effort; supports dot paths)-v/--verboseboolEnable verbose logging--versionkong.VersionFlagPrint version and exit--wrap-untrustedboolfalseIn JSON/raw output, wrap fetched text fields in external untrusted-content markers对list这类只读命令而言,--dry-run/--force等变更类参数实际上不生效,它们的意义体现在同族的suspend/delete上;而--json、-p、--select、--results-only则直接影响list的输出形态,下面分节展开。执行流程:从参数校验到 Admin SDK 调用AdminUsersListCmd.Run的完整调用链(internal/cmd/admin_users.go)可概括为六步:本地校验:trim 后的--domain为空则报用法错误;--max 0报max must be 0。两者均为本地错误,不产生任何网络请求。账号校验:requireAdminAccount先解析-a/--account,再调用isConsumerAccount(internal/cmd/account_helpers.go)——账号域名为gmail.com或googlemail.com时直接拒绝,提示 Admin SDK Directory API requires a Google Workspace account with domain-wide delegation; consumer accounts (gmail.com/googlemail.com) are not supported。这印证了 docs/workspace-admin.md 中 It is Workspace-only: personal gmail.com accounts cannot use these commands 的说法。获取 Admin 服务:adminDirectoryService从运行时服务注册表中取出 Admin Directory 客户端(internal/cmd/runtime_services.go)。构造 API 调用:svc.Users.List().Domain(domain).MaxResults(c.Max),若提供了--page令牌则追加.PageToken(pageToken),底层为google.golang.org/api/admin/directory/v1的 Directory API。分页抓取:交由 internal/cmd/paged_list_helpers.go 的loadPagedItems——未指定--all时只执行一次fetch;指定--all时进入 internal/cmd/paging.go 的collectAllPages循环,直到服务端返回空令牌为止,且设有 10,000 页的上限与重复令牌防护(从源码结构看,pageTokenGuard用于跟踪已见令牌以防分页死循环)。分支输出:JSON 模式或表格模式,详见下节。输出格式:四列表格与带分页令牌的 JSON 信封默认表格输出表格列由adminUserColumns()定义(internal/cmd/admin_presentation.go),固定为四列:列取值EMAILprimaryEmailNAMEname.fullName(用户无名字时为空)SUSPENDEDyes/noADMINyes/no(来自isAdmin字段)若查询无结果,stderr 输出No users found(并受--fail-empty控制退出码)。若服务端返回了nextPageToken,会在 stderr 追加提示(internal/cmd/output_helpers.go):# More results: use --all/--all-pages to fetch every page, or --page token for the next page提示写在 stderr 而非 stdout,保证了 stdout 是纯表格数据,可被直接管道或重定向。JSON 输出-j/--json模式下输出结构为(由源码中的outfmt.WriteJSON调用确定,internal/cmd/admin_users.go):{ users: [ { email: adaexample.com, name: Ada Lovelace, suspended: false, admin: true } ], nextPageToken: }每个用户对象固定输出email与suspended、admin,name带omitempty,用户档案缺名字时该键不出现。internal/cmd/admin_test.go 中的TestAdminUsersList_JSON_AllowsNilName专门用无name字段的模拟响应验证了这一点:命令不报错,且name解码为空串。信封字段nextPageToken在指定--all时会被清空(所有页已抓完);单独使用时携带续页令牌。--results-only可去掉这类信封字段,只保留主结果;--select email,admin可做最佳努力的字段投影(帮助文本提示多数命令更推荐--fields)。-p/--plain则输出无着色的 TSV 稳定文本,适合不依赖 JSON 解析器的传统管道。分页与退出码:脚本化的两个关键契约分页。三种工作模式:模式行为适用场景默认单页,--max条(默认 100),信封中带nextPageToken快速抽样、人工查看--page token从指定令牌处续取一页脚本逐页游标式抓取--all循环抓取直到令牌为空,上限 10,000 页,超限报pagination exceeded max pages全量导出退出码。从源码可确认的语义:参数类错误(缺--domain、--max非法)走usage错误路径,退出码 2(由 internal/cmd/admin_test.go 的ExitCode(result.err) ! 2断言验证);--fail-empty且无结果时退出码 3;API 错误(权限、API 未启用等)按错误内容包装后返回非零。shell 脚本中可据此三分支处理。前置条件:Workspace 账号与域范围委托gog admin users list能跑通的前提在 docs/workspace-admin.md 中有完整说明,要点如下:必须是 Workspace 账号:-a/--account指向的账号域不能是gmail.com/googlemail.com,否则在创建 Admin 服务之前即被拒绝。无人值守场景用服务账号 域范围委托:gog auth service-account set adminexample.com --key ~/Downloads/service-account.json gog auth service-account status adminexample.com服务账号需要被委托的 Admin SDK 作用域清单可由gog auth services --json查询。作用域要求:源码中的错误包装函数wrapAdminDirectoryError(internal/cmd/admin_common.go)对三类典型故障给出针对性诊断,可以据此反推所需配置:accessNotConfigured/ Admin SDK API has not been used → 提示先在 Cloud 控制台启用 Admin SDK API;insufficientPermissions/ insufficient authentication scopes / Not Authorized → 提示确认服务账号已开启域范围委托,且委托了admin.directory.user, admin.directory.group, and admin.directory.group.member等作用域;domain_wide_delegation/invalid_grant→ 提示域范围委托未配置或已失效,需在 Workspace 管理控制台检查。其中list实际只读取用户资源,核心是admin.directory.user作用域,但错误提示按 Directory 管理面整体给出,按提示补齐即可。实战示例以下示例均可在配置好服务账号委托后直接运行(账号与域名请按实际替换):# 1. 默认表格:列出域名用户(单页,最多 100 条) gog --account adminexample.com admin users list --domain example.com # 2. JSON 全量导出(每页 100 条,自动翻页) gog --account adminexample.com admin users list --domain example.com --all --json users.json # 3. 游标式续页:用上一步信封中的 nextPageToken gog --account adminexample.com admin users list --domain example.com \ --page nextPageToken --json # 4. CI 健康检查:域内没有任何用户视为失败(退出码 3) if gog --account adminexample.com admin users list --domain example.com \ --fail-empty --no-input --plain /dev/null; then echo domain has users else echo empty or failed, exit$? fi--no-input在 CI 中保证不会因交互提示挂起;--readonly可作为额外的运行时保险,阻断一切变更类请求。与相邻命令的配合list产出的email字段可直接作为同族命令的输入参数,构成典型的盘点—处置工作流(参见 docs/commands/gog-admin-users.md 与 docs/workspace-admin.md):# 查看单个用户详情(org unit、别名、最近登录等) gog --account adminexample.com admin users get adaexample.com --json # 先 dry-run 再执行变更 gog --account adminexample.com admin users suspend adaexample.com --dry-run gog --account adminexample.com admin users suspend adaexample.com --force # 删除(破坏性,需 --force 跳过确认) gog --account adminexample.com admin users delete adaexample.com --force相关参考页:gog-admin-users-get.md、gog-admin-users-suspend.md、gog-admin-users-delete.md、gog-admin-users-create.md,以及 docs/commands/README.md 的命令总索引。小结gog admin users list表面上只是一条只读查询命令,但在 gogcli 中它承载了管理面命令的完整工程契约:本地参数先行校验(退出码 2)、Admin SDK Directory API 调用、令牌分页(单页/续页/全量三模式)、表格与 JSON 双输出(含nextPageToken信封与--results-only/--select投影)、以及--fail-empty提供的退出码 3 语义。理解了 internal/cmd/admin_users.go 中的这条调用链,再叠加 docs/workspace-admin.md 的服务账号域范围委托配置,就可以把域用户盘点稳定地嵌入脚本、CI 与 Agent 自动化流程中。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考