托管 OAuth 轻松管理 Google 通讯录

通过托管 OAuth 安全接入 Google People API，实现联系人、联系人群组的增删改查与智能搜索，适合需要自动化通讯录管理的个人与团队。

基本信息

• 技能名称?Google Contacts
• 中文名称?托管 OAuth 轻松管理 Google 通讯录
• 作者?byungkyu
• 分类?专业技能
• 版本?1.0.4
• 标签?google-api, contacts, oauth, crm, address-book, people-api, email, productivity

使用方法

使用说明
核心用法
本技能是 Google People API 的代理封装，通过 Maton 平台提供托管 OAuth 认证，让用户无需处理复杂的 Google OAuth 流程即可操作 Google 通讯录。核心能力覆盖三大场景：

1. 联系人全生命周期管理
   支持单条/批量查询、创建、更新、删除联系人
   提供 personFields 精细字段控制（姓名、邮箱、电话、地址、公司、生日、备注等）
   支持 etag 乐观锁并发控制，防止数据覆盖
2. 联系人群组管理
   系统内置群组（星标、家人、同事、好友等）与用户自定义群组
   群组成员批量增删，支持连带删除选项
3. 智能搜索与其他联系人
   全文搜索联系人姓名、邮箱等信息
   管理"其他联系人"（邮件往来但未正式添加的联系人），可一键转正
   使用时需设置 MATON_API_KEY 环境变量，所有请求通过 https://api.maton.ai/google-contacts/{path} 代理转发，Maton 自动注入 OAuth Token。多账号场景下可通过 Maton-Connection 头部指定具体连接。
   显著优点
   零 OAuth 配置成本 ：托管认证省去客户端 ID/Secret 管理、Token 刷新、权限范围配置等繁琐步骤
   完整 API 覆盖 ：完整映射 Google People API，包括批量操作、分页、搜索等高级功能
   多语言友好 ：提供 Python、JavaScript、Bash/curl 等多种代码示例，降低接入门槛
   多账号支持 ：同一 Maton 密钥可管理多个 Google 账号的通讯录连接
   潜在缺点与局限性
   供应商锁定 ：完全依赖 Maton 代理服务，若服务中断或定价调整将直接影响使用
   网络依赖 ：所有请求必须经过 Maton 服务器中转，无法离线或直连 Google API
   搜索延迟 ：新建联系人存在索引延迟，搜索结果可能不包含最新数据
   写入需确认 ：技能文档明确要求写操作前需用户确认，自动化场景下可能增加交互复杂度
   并发限制 ：同一用户的变更请求建议串行发送，高并发写入可能触发限流或失败
   适合人群
   需要快速集成 Google 通讯录功能的开发者与自动化工程师
   无 OAuth 开发经验但希望使用 Google People API 的个人用户
   管理多个 Google 账号通讯录的运维人员
   构建 CRM 同步、客户管理、通讯录备份等场景的工具开发者
   常规风险
   | 风险类型 | 说明 | |---------|------| | 数据隐私 | 联系人数据流经 Maton 代理服务器，需信任第三方数据处理能力 | | Token 安全 | MATON_API_KEY 泄露将导致对应 Google 账号的通讯录被完全控制 | | 误操作风险 | 批量删除、群组连带删除等操作不可逆，需谨慎确认 | | 服务可用性 | 依赖 Maton 服务稳定性，建议实现本地缓存与降级方案 | | 合规风险 | 处理欧盟 GDPR、中国个人信息保护法等场景需额外评估 | 建议生产环境启用连接审计日志，定期轮换 API Key，并为敏感操作设置二次确认机制。