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 需要新的范围才能访问“其他联系人”或目录数据。如需了解所需范围,请参阅上文的详细信息。
如需了解详情,请参阅授权请求。