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/contacts 或 https://www.googleapis.com/auth/contacts.readonly 範圍。

• 讀取單一特定聯絡人 people.get
• 讀取多位特定聯絡人 people.getBatchGet
• 運用 people.connections.list 讀取聯絡人

更改

需要 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:updated	metadata.updateTime
atom:title	name
atom:content	name
gd:已刪除	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 列出聯絡人群組

更改

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

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

詳情請參閱授權要求。

用戶端程式庫

• 如果是 Apps Script，請參閱進階使用者服務。
• 如需其他支援的語言，請參閱安裝用戶端程式庫。