Gws People

核心用法

gws people 是基于 Google People API 的命令行工具，提供完整的联系人生命周期管理能力。核心架构遵循 gws people <resource> <method> 的层级设计，主要资源分为三类：

1. contactGroups - 联系人分组管理：创建、删除、更新分组，以及成员操作
2. otherContacts - 其他联系人处理：自动收集的联系人（如邮件往来对象）的查询与迁移
3. people - 核心联系人操作：CRUD、批量操作、照片管理、搜索及企业目录访问

关键方法包括 batchCreateContacts/batchUpdateContacts 批量处理、searchContacts/searchDirectoryPeople 智能搜索、以及 listDirectoryPeople 企业目录同步。搜索前需发送空查询预热缓存，此为官方强制的性能优化要求。

显著优点

• 完整 API 覆盖：支持个人联系人、其他联系人、企业目录三大数据源
• 批量操作原生支持：避免逐条 API 调用，显著提升大规模通讯录管理效率
• 企业场景就绪：searchDirectoryPeople 和 listDirectoryPeople 直接对接 Google Workspace 组织目录
• 增量同步机制：通过 sync_token 实现高效差量更新，支持删除状态追踪
• CLI 原生设计：与 gws 生态统一，支持 gws schema 自省和参数自动补全

潜在局限

• 并发限制严格：所有 mutate 操作必须串行执行，同一用户的并发请求会导致延迟增加和失败
• 同步令牌有效期：sync_token 7 天过期，过期后需全量重新同步
• 字段限制：单值字段（姓名、生日、性别等）禁止多值提交，否则 400 错误
• 企业目录延迟：写入后同步查询可能存在数分钟延迟
• 搜索依赖预热：首次搜索必须先发空查询，增加调用复杂度

适合人群

• 需要批量管理 Google 联系人的开发者/系统管理员
• 构建通讯录同步、CRM 集成的自动化工作流工程师
• 管理 Google Workspace 组织成员信息的企业 IT 团队
• 偏好命令行操作、追求脚本化管理的效率用户

常规风险

| 风险类型 | 说明 |

|---------|------|

| 数据覆盖 | `update_mask` 模式为全量替换，误操作可能导致非预期字段丢失 |

| 重复创建 | 分组名称唯一性约束失败返回 HTTP 409，需前置校验逻辑 |

| 权限越界 | 企业目录查询返回域内全部成员信息，需注意隐私合规 |

| 并发故障 | 忽视串行执行要求将导致请求失败率上升 |

| 同步失效 | 长期未操作的 `sync_token` 过期会导致同步链路中断 |