- 关于本文
- 首先得出结论：什么是 Google 谷歌通讯录？
- 它在整个 Google 生态系统中的位置如何？
- “联系人”与“组织 Directory”不同
- 普通用户和文职人员该如何使用？
- Google Workspace 有何变化？
- 开发者指南：什么是 People API？
- 若要在 API 中安全地进行尝试，请从读取操作开始
- 注意 OAuth 作用域 (scope)
- 什么是 Domain Shared Contacts API？
- 如果以 Microsoft 365 类比？
- IT 管理员的关注点
- 安全性与个人信息
- 在图形界面（GUI）中安全地进行测试
- 官方信息
- 接下来要做什么？
- Papanda 尝试：通过 CSV 比较直观展示 Contacts 的效果
- 归根结底这是一款怎样的服务？
关于本文
本文是通过利用生成式 AI 的自动生成流程创建的。
本文将 Google 谷歌通讯录不单单视为一个“电子邮箱地址簿”，而是将其整理为区分个人联系人与 Google Workspace 目录信息的服务。在查阅了 Google 官方的通讯录帮助、People API 以及 Domain Shared Contacts API 文档后，本文从普通用户、管理员和开发者的各自视角进行了总结。
信息确认基准日：2026-09-19
首先得出结论：什么是 Google 谷歌通讯录？
Google 谷歌通讯录是 Google 提供的一项用于保存和整理姓名、电邮地址、电话号码等联系人信息的服务。
当您在 Gmail 等 Google 服务中查找联系人时，也会涉及它。但是，在 Google Workspace 组织中，切勿将“自己注册的个人联系人”与“组织目录（Directory）中的用户信息”视为相同的内容，这一点至关重要。
它在整个 Google 生态系统中的位置如何？
| 视角 | 定位 |
|---|---|
| 主分类 | Google / Google Workspace 的联系人与人物信息 |
| 主要目的 | 保存、搜索和整理人员的联系人信息 |
| 面向个人的核心 | Google 谷歌通讯录 |
| 面向开发者 | People API |
| Workspace 组织信息 | Domain Directory |
| 组织共用的外部联系人 | Domain Shared Contacts API |
| 经常搭配使用的代表性服务 | Gmail、Calendar、Google Workspace |
flowchart TB User[利用者] --> Contacts[Google Contacts] Contacts --> Personal[自分の連絡先] Contacts --> Other[Other contacts] Workspace[Google Workspace] --> Directory[組織Directory] Developer[開発者] --> People[People API] People --> Personal People --> Other People --> Directory Admin[管理者] --> Shared[Domain Shared Contacts]
“联系人”与“组织 Directory”不同
这一点对于理解 Google Contacts 至关重要。
在 People API 中，除了能够读写经身份验证的用户自身的 Contacts 之外，Google Workspace 用户还可以根据权限搜索域内的个人资料或域联系人。
另一方面，组织内部用户的信息与个人 Contacts 是不同的信息源。Google 官方也解释过，People API 会整合多个信息源来返回人物信息。
| 类型 | 示例 | 主要管理主体 |
|---|---|---|
| 个人 Contacts | 自己录入的客户 | 用户 |
| Other contacts | 在使用 Google 服务期间作为候选人积累的联系人 | 用户侧 |
| Domain profile | 本公司/本组织用户 | Workspace 组织 |
| 域共享联系人 | 希望在全公司范围内共享的外部联系人 | Workspace 管理侧 |
普通用户和文职人员该如何使用？
例如，当录入客户联系人时：
姓名
公司名称
电子邮件地址
电话号码
补充信息
等内容可以作为联系人进行整理。
使用标签，还可以将其分类为“客户”、“项目 A”等。
但是，如果在工作中录入个人信息，则必须遵守组织的信息管理规则。严禁将密码或 API 密钥等非联系人的机密信息保存到备忘录栏中。
Google Workspace 有何变化？
在 Workspace 中，不仅涉及个人联系人，还涉及组织目录（Directory）。
因此，在 Gmail 等应用中输入姓名时弹出的候选对象，不一定是你手动注册到“通讯录”中的人物。
在 Google Workspace 中，你可以根据管理员的设置和权限使用域内个人资料或联系人信息。
此外，在 Workspace 中，有一项将自己的联系人管理委托给同一组织内其他用户的功能。根据 Google 官方说明，联系人委派功能必须在同一域或同一组织内使用，且必须由目录管理员启用联系人共享功能。
开发者指南：什么是 People API？
以编程方式处理 Google Contacts 数据的核心 API 是 People API。
通过 People API，您可以获取、搜索、创建、更新和删除已认证用户的联系人。此外，在 Google Workspace 中，您还可以根据权限搜索域内的个人资料和联系人。
典型示例如下：
| 需求 | People API 示例 |
|---|---|
| 我的联系人列表 | people.connections.list |
| 搜索联系人 | people.searchContacts |
| 创建新联系人 | people.createContact |
| 更新现有联系人 | people.updateContact |
| 删除联系人 | people.deleteContact |
| 搜索组织目录 | people.searchDirectoryPeople |
| 联系人组管理 | contactGroups |
People API 的服务端点是 people.googleapis.com。
若要在 API 中安全地进行尝试，请从读取操作开始
与其一开始就大量创建和删除联系人，不如在测试用 Google 账号或获批的环境中从读取操作开始。
例如，获取自己的联系人列表的基本思路如下。
GET /v1/people/me/connections ?personFields=names,emailAddresses Host: people.googleapis.com
验证事项：返回的是否仅为预期的联系人。
成功条件：不是 HTTP 错误，而是能够获取已授权字段的联系人信息。
personFields 更改后，可以缩小获取目标的字段范围。设计时避免获取不必要的信息，在隐私保护方面也非常重要。
注意 OAuth 作用域 (scope)
使用 People API 创建联系人时，Google 官方的 people.createContact 会请求对联系人的 OAuth 权限。
OAuth 作用域表示“允许应用访问到什么程度”。
应避免仅需读取操作的处理却赋予写入权限等过度授权的设计。
此外，请勿将 OAuth 令牌、客户端密钥、真实邮箱地址、真实用户 ID 等保存到 GitHub 中。
什么是 Domain Shared Contacts API？
在 Workspace 中，供整个组织共享的外部联系人还有用于处理该联系人的 Domain Shared Contacts API。
Google 官方将此 API 解释为用于获取和更新“与 Google Workspace 域中所有用户共享的外部联系人”的工具。
重要的一点是，它是专为外部联系人而设计的。
Google 官方指出，如果使用此 API 创建内部用户或群组的信息，可能会导致重复或产生意外行为，因此建议使用 Directory API 来管理内部用户信息。
flowchart LR
A[人物情報を管理したい] --> B{誰の情報?}
B -->|自分の私的な連絡先| C[Google Contacts / People API]
B -->|組織内部ユーザー| D[Workspace Directory / Directory API]
B -->|全社共有する外部連絡先| E[Domain Shared Contacts API]
记住这种区隔，会让你更容易理解与 Contacts 相关的 API。
如果以 Microsoft 365 类比？
如果你有 Microsoft 365 的使用经验，与其将 Google Contacts 与 Outlook 的“联系人”进行一对一的对应，不如将其分为以下三类来理解会更安全：
个人 Contacts
组织 Directory
组织共享的外部联系人
。
| Google 端 | Microsoft 端接近的概念 |
|---|---|
| Google Contacts | Outlook 的个人联系人 |
| Workspace Directory | Microsoft 365 / Entra ID 端的组织用户信息 |
| People API | 按用途查看 Microsoft Graph 的人员与联系人相关 API |
| Domain Shared Contacts | 单独设计组织内共享外部联系人的机制 |
产品结构和 API 并不完全相同。关键不仅在于“通讯录”这一界面，还在于查看人员信息是由谁管理这一点。
IT 管理员的关注点
管理员尤其会区分以下几点进行考虑：
组织内部用户
个人拥有的联系人 (Contacts)
组织公共的外部联系人
联系人委派
来自 API 的访问权限
在采用“因为想向全体员工展示，所以将相同数据复制到每个用户的 Contacts 中”这种设计之前，请先确认 Directory 或 Domain Shared Contacts 的用途。
安全性与个人信息
联系人是极易包含姓名、电子邮箱、电话号码、所属部门等个人信息的数据。
不注册不必要的信息
在 API 中使用最小必要的 scope 和字段
切勿将真实存在的个人信息嵌入到示例代码中
不保存 OAuth 令牌或客户端密钥
在进行大量更新之前，请进行备份、测试并确认权限
对同一用户的 API 更改请求应按顺序处理
Google 官方建议使用 People API 依次发送针对同一用户的更改请求。请避免设计并行大量更新的方案。
在图形界面（GUI）中安全地进行测试
打开 Google 通讯录。
创建一个虚拟测试联系人，而不是真实人物。
添加一个标签。
确认可以通过搜索找到该联系人。
测试结束后，删除不需要的虚拟联系人。
成功条件：能够搜索到创建的虚拟联系人，并通过标签进行整理。
如果首先要进行更改，最安全的方法是只更改标签，并确认“人物数据”与“分类”之间的区别。
官方信息
接下来要做什么？
如果是普通用户或行政人员，可以先创建一个虚构的联系人，然后尝试添加标签和搜索功能。
如果是 IT 管理员，则应区分“个人联系人”、“内部通讯录”和“全公司共享的外部联系人”这三类，并理清各自组织中由谁来管理哪些信息。
如果是开发人员，可以在启用了 People API 的测试环境中，优先从读取联系人而非写入联系人开始，并尽量减少所需的 OAuth 权限范围和获取字段。
Papanda 尝试：通过 CSV 比较直观展示 Contacts 的效果
仅使用虚构的 3 个人员，将其做成一个演示，将导入 Google Contacts 的 CSV 列与 Outlook 等工具的 CSV 列并排显示。如果进行开发，则需确认 People API。电子邮件使用example.com等虚拟值。每日代码候选：google-contacts-csv-sample。
归根结底这是一款怎样的服务？
Google Contacts 是用于在 Google 中管理个人联系人信息的面向个人的入口。
在 Google Workspace 中，除了上述功能外，还加入了组织通讯录和共享外部联系人等其他人员信息。开发人员通过 People API，管理员通过 Directory 或 Domain Shared Contacts，结合“谁的信息由谁管理”这一原则进行区分使用，将更容易理解整体架构。
