Contacts API 遷移指南

Contacts API 已於 2022 年 1 月 19 日關閉。本指南說明遷移至 People API 時的欄位、端點和授權範圍異動。

總覽

People API 與舊版 Contacts API 的功能相同,所有功能都相同,但「其他聯絡人」除外:

  • 系統管理員透過新的範圍擁有「其他聯絡人」的唯讀權限。由於系統不支援傳送修改/寫入信號給「其他聯絡人」,因此如果使用者想要更新資料欄位,必須將「其他聯絡人」新增為「我的聯絡人」。

  • 您只能透過 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 錯誤關鍵字 (type=OUTLOOK_BILLING_INFORMATION)
gContact:birthday 生日
gContact:calendarLink calendarUrls
gContact:directoryServer 其他關鍵字 (type=OUTLOOK_DIRECTORY_SERVER)
gContact:event 事件
gContact:extendedProperty clientData
gContact:externalId externalIds
gContact:fileAs fileAses
gContact:gender 性別
gContact:groupmemberInfo memberships.contactGroupMembership
gContact:hobby 興趣
gContact:initials 已淘汰的 暱稱 (type=INITIALS)
gContact:jot type='home' 其他關鍵字 (type=HOME)
gContact:jot type='keywords' 其他關鍵字 (type=OUTLOOK_KEYWORD)
gContact:jot type='other' 其他關鍵字 (類型=OTHER)
gContact:jot type='user' 其他關鍵字 (type=OUTLOOK_USER)
gContact:jot type='work' 其他關鍵字 (type=WORK)
gContact:language 語言
gContact:maidenName 已淘汰 暱稱 (type=MAIDEN_NAME)
gContact:英里 其他關鍵字 (type=OUTLOOK_MILEAGE)
gContact:<暱稱> 暱稱 (type=DEFAULT)
gContact:occupation 職業
gContact:Priority 其他關鍵字 (type=OUTLOOK_PRIORITY)
gContact:relation 相關
gContact:敏感度 其他關鍵字 (type=OUTLOOK_SENSITIVITY)
gContact:shortName 已淘汰 暱稱 (type=SHORT_NAME)
gContact:subject 其他關鍵字 (type=OUTLOOK_SUBJECT)
gContact:userDefinedField userDefined
gContact:website urls
gContact:yomiName names.phonetic_full_name
gd:已刪除 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 範圍。

更改

需要 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:updated metadata.updateTime
atom:title name
atom:content name
gd:已刪除 metadata.deleted
systemGroup groupType=SYSTEM_CONTACT_GROUP

端點

讀取

需要 https://www.googleapis.com/auth/contactshttps://www.googleapis.com/auth/contacts.readonly 範圍。

更改

需要 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 範圍的所有端點。讀取及寫入聯絡人和聯絡人群組則支援舊版範圍。

使用者 API 需要新範圍才能存取「其他聯絡人」或 Directory 資料。有關需要的範圍,請參閱上方詳細資料。

詳情請參閱授權要求

用戶端程式庫