Contacts API 已于 2022 年 1 月 19 日关停。使用本指南可以了解在迁移到 People API 时对字段、端点和授权范围进行的更改。
概览
People API 的所有功能与旧版 Contacts API 的功能相同，但其他联系人除外：
管理员在新范围内对“其他联系人”拥有只读权限。由于系统不支持将 mutate/写入信号发送回“其他联系人”，因此如果用户希望更新“其他联系人”的数据字段，必须将其添加为“我的联系人”。
通过该 API 只能读取“其他联系人”的基本联系信息。例如，全名、电子邮件地址和电话号码。
此外，旧的通讯录范围 (https://www.google.com/m8/feeds)（可提供对个人联系人和目录信息的访问权限）现被替换为以下范围：
- 如要访问个人通讯录，请使用：
https://www.googleapis.com/auth/contacts - 如需访问目录信息，请按以下步骤操作：
https://www.googleapis.com/auth/directory.readonly
通讯录
字段映射
| 联系人字段 | 人员字段 |
|---|---|
| atom:content | 传记 |
| atom:link rel='http://schemas.google.com/contacts/2008/rel#photo' | 照片 |
| atom:title | names |
| gContact:billingInformation | miscKeyword (type=OUTLOOK_BILLING_INFORMATION) |
| gContact:生日 | 生日 |
| gContact：calendarLink | calendarUrls |
| gContact:directoryServer | miscKeyword (type=OUTLOOK_DIRECTORY_SERVER) |
| gContact:event | 事件 |
| gContact:extendedProperty | clientData |
| gContact:externalId | externalIds |
| gContact:fileAs | fileAses |
| gContact:gender | 性别 |
| gContact:groupMembershipInfo | memberships.contactGroupMembership |
| gContact:hobby | 兴趣 |
| gContact：首字母 | 已弃用 昵称 (type=INITIALS) |
| gContact:jot type='home' | miscKeyword (type=HOME) |
| gContact:jot type='keywords' | miscKeyword (type=OUTLOOK_KEYWORD) |
| gContact:jot type='other' | miscKeyword (type=OTHER)（其他关键字） |
| gContact:jot type='user' | miscKeyword (type=OUTLOOK_USER) |
| gContact:jot type='work' | miscKeyword (type=WORK) |
| gContact:language | 语言 |
| gContact:maidenName | 已弃用 昵称 (type=MAIDEN_NAME) |
| gContact:英里 | miscKeyword (type=OUTLOOK_MILEAGE) |
| gContact:昵称 | 昵称 (type=DEFAULT) |
| gContact:occupation | 职业 |
| gContact:优先级 | miscKeyword (type=OUTLOOK_PRIORITY) |
| gContact:relation | 关系 |
| gContact:sensitivity | miscKeyword (type=OUTLOOK_SENSITIVITY) |
| gContact:shortName | 已弃用 昵称 (type=SHORT_NAME) |
| gContact:subject | miscKeyword (type=OUTLOOK_SUBJECT) |
| gContact:userDefinedField | userDefined |
| gContact:website | urls |
| gContact:yomiName | names.phonetic_full_name |
| gd:deleted | metadata.deleted |
| gd:email | emailAddresses |
| gd:im | imClients |
| gd:organization | organizations |
| gd:phoneNumber | phoneNumbers |
| gd:postalAddress | addresses.formattedValue |
| gd:where | 住所 |
| gd:structuredPostalAddress | 地址 |
个人通讯录端点
读取
需要 https://www.googleapis.com/auth/contacts 或 https://www.googleapis.com/auth/contacts.readonly 范围。
- 读取单个特定联系人的数据
people.get - 读取多个特定联系人
people.getBatchGet - 使用
people.connections.list读取联系人
mutate
需要 https://www.googleapis.com/auth/contacts 范围。更改除照片以外的所有联系人字段。
- 使用
people.createContact创建联系人 - 使用
people.updateContact更新现有联系人 - 使用
people.deleteContact删除联系人。
照片修改
需要 https://www.googleapis.com/auth/contacts 范围。
- 使用
people.updateContactPhoto更新联系人照片。 - 使用
people.deleteContactPhoto删除联系人照片。
其他联系人端点
读取
其他联系人处于只读状态，仅返回 names、emailAddresses 和 phoneNumbers 字段。
需要 https://www.googleapis.com/auth/contacts.other.readonly 范围。
- 使用
otherContacts.list读取其他联系人。
复制
需要 https://www.googleapis.com/auth/contacts.other.readonly 和 https://www.googleapis.com/auth/contacts 范围。
- 使用
otherContacts.copyOtherContactToMyContactsGroup复制其他联系人。
全局地址列表端点
需要 https://www.googleapis.com/auth/directory.readonly 范围。
- 列出所有目录联系人和个人资料
people.listDirectoryPeople。 - 搜索目录联系人和个人资料
people.searchDirectoryPeople。
联系人群组
字段映射
| Contacts API 联系人群组字段 | People API 联系人群组字段 |
|---|---|
| atom:update | metadata.updateTime |
| atom:title | name |
| atom:content | name |
| gd:deleted | metadata.deleted |
| systemGroup | groupType=SYSTEM_CONTACT_GROUP |
端点
读取
需要 https://www.googleapis.com/auth/contacts 或 https://www.googleapis.com/auth/contacts.readonly 范围。
- 使用
people.contactGroups.get获取特定的联系人群组 - 使用
people.contactGroups.list列出联系人群组
mutate
需要 https://www.googleapis.com/auth/contacts 范围。
- 使用
people.contactGroups.create创建联系人群组 - 使用
people.contactGroups.update更新联系人群组 - 使用
people.contactGroups.delete删除联系人群组 使用
people.contactGroups.members.modify在联系人群组中添加或移除联系人
授权范围
旧版范围 https://www.google.com/m8/feeds 是 https://www.googleapis.com/auth/contacts 范围的别名。这意味着，采用旧版范围的现有 OAuth 授权将适用于 People API 中需要 https://www.googleapis.com/auth/contacts 范围的任何端点。读取和写入联系人和联系人群组将适用于旧范围。
People API 需要新的范围才能访问“其他联系人”或目录数据。如需了解所需范围，请参阅上文的详细信息。
如需了解详情，请参阅授权请求。