Contacts API 迁移指南

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/contactshttps://www.googleapis.com/auth/contacts.readonly 范围。

mutate

需要 https://www.googleapis.com/auth/contacts 范围。更改除照片以外的所有联系人字段。

照片修改

需要 https://www.googleapis.com/auth/contacts 范围。

其他联系人端点

读取

其他联系人处于只读状态,仅返回 namesemailAddressesphoneNumbers 字段。

需要 https://www.googleapis.com/auth/contacts.other.readonly 范围。

复制

需要 https://www.googleapis.com/auth/contacts.other.readonlyhttps://www.googleapis.com/auth/contacts 范围。

全局地址列表端点

需要 https://www.googleapis.com/auth/directory.readonly 范围。

联系人群组

字段映射

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/contactshttps://www.googleapis.com/auth/contacts.readonly 范围。

mutate

需要 https://www.googleapis.com/auth/contacts 范围。

授权范围

旧版范围 https://www.google.com/m8/feedshttps://www.googleapis.com/auth/contacts 范围的别名。这意味着,采用旧版范围的现有 OAuth 授权将适用于 People API 中需要 https://www.googleapis.com/auth/contacts 范围的任何端点。读取和写入联系人和联系人群组将适用于旧范围。

People API 需要新的范围才能访问“其他联系人”或目录数据。如需了解所需范围,请参阅上文的详细信息。

如需了解详情,请参阅授权请求

客户端库