gogcli 实战指南用gog contacts directory list从 Google Workspace 目录高效导出通讯录【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli导读gog contacts directory list是 gogcliGoogle Workspace in your terminal中用于列出 Workspace 企业目录Domain Directory中所有用户档案的核心只读命令其底层调用 Google People API 的people.listDirectoryPeople接口。本文以该命令的官方参考文档为骨架结合仓库源码internal/cmd/contacts_directory.go等详解其调用链、全部命令行参数、分页机制、文本与 JSON 双输出模式及测试验证方式帮助你快速掌握在终端里批量拉取、检索企业通讯录的完整实操方案。一、命令定位在 contacts 命令树中的位置gog contacts directory list位于gog contacts命令树中的directory分组之下directory分组专门处理Workspace 域目录Directory中的人员档案与个人通讯录contacts、其他联系人contacts other形成三套独立的数据源。从仓库源码看命令树的注册结构定义在 internal/cmd/contacts_directory.gotype ContactsDirectoryCmd struct { List ContactsDirectoryListCmd cmd: name:list help:List people from the Workspace directory Search ContactsDirectorySearchCmd cmd: name:search help:Search people in the Workspace directory } type ContactsDirectoryListCmd struct { Max int64 name:max aliases:limit help:Max results default:50 Page string name:page aliases:cursor help:Page token All bool name:all aliases:all-pages,allpages help:Fetch all pages FailEmpty bool name:fail-empty aliases:non-empty,require-results help:Exit with code 3 if no results }directory分组下共有两个子命令子命令说明gog contacts directory list列出 Workspace 目录中的全部人员gog contacts directory search按关键词在 Workspace 目录中搜索人员父命令与完整命令树见 gog-contacts-directory 与 gog-contacts。二、基本用法命令的标准调用形式为gog contacts (contact) directory list [flags]其中(contact)表示该分组同时接受contacts与contact两种拼写即下面两条命令等价gog contacts directory list gog contact directory list最简调用列出默认 50 条目录人员gog contacts directory list带账号指定与结果数控制gog contacts directory list --account adminexample.com --max 100命令属于只读操作默认不会产生任何修改性请求配合--readonly标志可在运行时进一步强制拦截所有变更类 API 请求。三、完整参数参考以下参数表完整继承自命令的官方文档其中--max、--page、--all、--fail-empty为list子命令的专属参数其余为 gogcli 全命令共享的全局标志。3.1 子命令专属参数参数类型默认值说明--max--limitint6450每页返回的最大结果数。源码中要求max 0否则返回usage(max must be 0)错误见 contacts_directory.go--page--cursorstring分页令牌Page token用于获取下一页结果--all--all-pages--allpagesbool自动抓取所有分页--fail-empty--non-empty--require-resultsbool无结果时以退出码 3 结束便于脚本检测空结果3.2 全局参数参数类型默认值说明--access-tokenstring直接使用提供的访问令牌绕过存储的 refresh token令牌约 1 小时过期-a--account--acctstring指定账号邮箱、别名或auto用于 Google API 命令认证--clientstringOAuth 客户端名称用于选择已存储的凭据与令牌桶--colorstringauto输出颜色auto\|always\|never--disable-commandsstring逗号分隔的禁用命令列表支持点路径dot paths-n--dry-run--dryrun--noop--previewbool不执行任何修改仅打印预期动作并以成功退出本命令为只读天然无副作用--enable-commandsstring逗号分隔的启用命令前缀列表支持点路径用于限制 CLI 面--enable-commands-exactstring逗号分隔的精确启用命令列表父命令不会自动启用子命令-y--force--assume-yes--yesbool跳过破坏性命令的确认提示--gmail-no-sendboolfalse阻止 Gmail 发送操作Agent 安全开关-h--helpkong.helpFlag显示上下文相关的帮助信息--homestring覆盖 gogcli 的 config/data/state/cache 根目录等价于GOG_HOME环境变量-j--json--machineboolfalse以 JSON 输出到 stdout最适合脚本解析--no-input--non-interactive--noninteractivebool永不提示交互改为失败退出适合 CI-p--plain--tsvboolfalse输出稳定可解析的纯文本TSV无颜色--quota-projectstring用于计费的 Google Cloud 项目作为X-Goog-User-Project头发送部分 API 配合--access-token或 ADC 时需要--readonlyboolfalse运行时拦截所有修改类 API 请求auth add也会申请只读 OAuth 范围--results-onlyboolJSON 模式下仅输出主结果丢弃nextPageToken等信封字段--select--pick--projectstringJSON 模式下选择逗号分隔的字段尽力而为支持点路径推荐大多数命令使用--fields-v--verbosebool开启详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中将获取的外部文本字段包裹在 untrusted-content 标记内说明命令框架基于 Kong CLI 库构建因此--help/--version的类型标注为kong.helpFlag/kong.VersionFlag属于框架注入的通用标志。四、源码级调用链解析list子命令的执行入口是ContactsDirectoryListCmd.Runinternal/cmd/contacts_directory.go核心调用链如下4.1 认证与客户端获取Run → requireAccount(flags) → peopleDirectoryService(ctx, account) → runtime.Services.PeopleDirectorypeopleDirectoryServiceinternal/cmd/runtime_services.go从运行时的服务工厂中取出 People API 客户端requireAccount负责解析--account指定的账号邮箱/别名/auto未指定且无法自动推断时命令直接报错退出。4.2 API 请求构造命令通过 Google People API 的people.listDirectoryPeople接口拉取目录数据关键参数如下contacts_directory.gocall : svc.People.ListDirectoryPeople(). Sources(DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE). ReadMask(directoryReadMask). PageSize(c.Max). Context(ctxTimeout) if strings.TrimSpace(pageToken) ! { call call.PageToken(pageToken) } resp, callErr : call.Do()其中Sources(DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE)固定指定数据源为域档案Domain Profile即 Workspace 企业目录中的用户信息而非个人通讯录ReadMask(directoryReadMask)只请求必需的字段directoryReadMask names,emailAddresses常量定义在 contacts_directory.go避免拉取超大响应PageSize(c.Max)每页大小取--max值默认 50Context(ctxTimeout)每个 API 请求带 20 秒超时directoryRequestTimeout 20 * time.Second防止网络挂起。4.3 分页统一封装分页逻辑统一走loadPagedItemsinternal/cmd/paged_list_helpers.go未指定--all时仅请求一次返回当前页数据与nextPageToken指定--all时调用collectAllPages循环携带 page token 抓取全部页面直到 API 不再返回NextPageToken。每条目录记录的读取掩码只包含姓名与邮箱两个字段因此在有结果而下一页存在时终端会提示# More results: use --all/--all-pages to fetch every page, or --page token for the next page由printNextPageHintWithAll输出。五、输出格式与字段映射5.1 文本表格输出默认默认输出为对齐的文本表格列定义见directoryPersonColumnsinternal/cmd/contacts_presentation.go列头含义取值来源RESOURCE人员资源标识person.ResourceName形如people/xxxxNAME显示名primaryName(p)EMAIL主邮箱primaryEmail(p)字段提取函数定义在 internal/cmd/contacts.goprimaryName优先取Names[0].DisplayName缺失时用GivenName FamilyName拼接primaryEmail取EmailAddresses[0].Value。所有值经sanitizeTab清洗保证表格在含特殊字符时不错位。5.2 JSON 输出脚本友好加--json或--machine后命令输出结构化的 JSON 信封{ people: [ {resource: people/xxxx, name: Zhang San, email: zhangsanexample.com} ], nextPageToken: npt }每条记录只包含resource/name/email三个字段name、email为空时使用omitempty省略。若配合--results-only信封字段nextPageToken会被丢弃仅输出people数组本身。5.3 空结果与失败语义无结果且未指定--fail-emptystderr 打印No results正常退出指定--fail-empty别名--non-empty/--require-results无结果时以退出码 3结束见failEmptyExit非常适合在 CI 或脚本中作为目录为空/查询无命中的判定信号。六、与兄弟命令的配合使用directory list常用于全量导出结合其他命令可覆盖完整场景场景推荐命令全量导出目录人员含分页gog contacts directory list --all --json按姓名/邮箱搜索目录人员gog contacts directory searchquery拉取个人通讯录含电话/生日gog contacts list拉取其他联系人含电话gog contacts other list搜索其他联系人gog contacts other search三者数据源不同目录来自DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE其他联系人来自OtherContacts.List额外带phoneNumbers字段见 contacts_directory.go。因此在目录中找人与在通讯录中找人结果可能不同需要按需选择。七、测试验证与可复现性仓库用 httptest 模拟 People API 对list命令做了端到端验证internal/cmd/execute_contacts_directory_text_test.go。测试要点mock 服务只响应people:listDirectoryPeople路径的请求返回单条人员记录resourceName: people/d1、displayName: Dir、email: direxample.com及nextPageToken: npt以--max 1执行contacts directory list断言 stderr 包含分页提示# More results: use --all/--all-pages...stdout 包含RESOURCE、people/d1、direxample.com。这套测试同时印证了读取掩码只包含姓名/邮箱、分页提示的触发条件、以及表格列头与字段映射的实现细节。八、实际使用注意事项权限范围读取目录人员需要 People Directory API 的读取范围gog auth add时保持默认范围即可覆盖只读场景若使用--readonly则会申请只读 OAuth 范围见 gog-auth-add。配额与分页--max同时决定单页大小建议先用默认 50 查看数据规模再用--all全量拉取避免一次请求过大触发配额限制。脚本化组合推荐--json --no-input --fail-empty三件套配合--account指定账号可获得确定性强、无交互、可判空的输出适合定时任务与 CI。目录可见性DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE返回的是域目录中对当前账号可见的人员档案可见范围受 Workspace 管理员设置如目录共享设置约束。访问令牌直连临时场景可用--access-token直接注入令牌但令牌约 1 小时过期长期自动化建议走受管凭据与--account。相关文档gog contacts directory父命令gog contacts directory search兄弟命令gog contacts命令组命令索引核心实现internal/cmd/contacts_directory.go字段展示internal/cmd/contacts_presentation.go字段提取internal/cmd/contacts.go分页封装internal/cmd/paged_list_helpers.go测试用例internal/cmd/execute_contacts_directory_text_test.go【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考