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 資料。有關需要的範圍，請參閱上方詳細資料。
詳情請參閱授權要求。