您可以使用 Google 的 CardDAV 通訊協定查看及管理聯絡人。
聯絡人會儲存在使用者的 Google 帳戶中,大多數 Google 服務都可以存取聯絡人清單。您的用戶端應用程式可以使用 CardDAV API 建立新的聯絡人、編輯或刪除現有聯絡人,以及查詢符合特定條件的聯絡人。
規格
目前未實作完整規格,但許多用戶端 (例如 Apple iOSTM Contacts 和 macOS) 應能正確互通。
針對每項相關規格,Google 的 CardDAV 支援如下:
- rfc2518:適用於分散式編寫 (WebDAV) 的 HTTP 擴充功能
- 支援 HTTP 方法
GET
、PUT
、DELETE
、OPTIONS
和PROPFIND
。 - 不支援 HTTP 方法
LOCK
、UNLOCK
、COPY
、MOVE
或MKCOL
。 - 「不」支援任意 (使用者定義) WebDAV 屬性。
- 「不」支援 WebDAV 存取控制 (rfc3744)。
- 支援 HTTP 方法
- rfc5995:使用 POST 將成員新增至 WebDAV 集合
- 支援在不指定 ID 的情況下建立新聯絡人。
- rfc6352:CardDAV:vCard Extensions 到網路分散式編寫與版本管理 (WebDAV)
- 支援 HTTP 方法
REPORT
,但並非所有定義的報表均會導入。 - 支援提供主體集合和聯絡人集合。
- 支援 HTTP 方法
- rfc6578:WebDAV 的集合同步
- 用戶端應用程式必須在初次同步處理後,切換至此作業模式。
- rfc6749:OAuth 2.0 授權架構和 rfc6750:OAuth 2.0 授權架構:不記名憑證的使用方式
- 支援使用 OAuth 2.0 HTTP 驗證來驗證 CardDAV 用戶端程式。Google 不支援其他驗證方法。為保護聯絡人資料,我們要求 CardDAV 連線使用 HTTPS。
- rfc6764:將 Calendaring Extensions 的服務定位到 WebDAV (CalDAV) 和 vCard Extensions 到 WebDAV (CardDAV)
- 根據 rfc6764 的第 6 節,必須啟動 CardDAV 網址。
- 支援 CalDAV 中的日曆集合實體標記 (CTag),這個標記可在 CardDAV 和 CalDAV 規格之間共用。聯絡人
ctag
就像資源ETag
,因為聯絡人通訊錄中的任何內容有所變更。這可讓用戶端程式快速判斷不需要同步處理任何已變更的聯絡人。 - Google 使用 VCard 3.0 做為聯絡人編碼格式。請參閱:rfc6350: VCard 3.0。
Google 的 CardDAV 需要 OAuth 2.0
Google 的 CardDAV 介面需要 OAuth 2.0。如要瞭解如何使用 OAuth 2.0 存取 Google API,請參閱下列連結的說明文件:
正在連線至 Google 的 CardDAV 伺服器
CardDAV 通訊協定可讓您探索通訊錄和聯絡資源 URI。您不得對任何 URI 進行硬式編碼,因為 URI 可能會隨時變更。
用戶端應用程式必須使用 HTTPS,且必須針對使用者的 Google 帳戶提供 OAuth 2.0
驗證。除非該要求經由 HTTPS 透過 HTTPS 驗證 Google 帳戶的 OAuth 2.0 驗證,且已在 DevConsole 註冊,否則系統不會驗證要求。只要您嘗試透過基本驗證方式透過 HTTP 進行連線,或使用與 Google 帳戶不符的電子郵件/密碼時,系統就會傳回 HTTP 401 Unauthorized
回應代碼。
如要使用 CardDAV,您的用戶端程式一開始必須在以下位置執行 HTTP PROPFIND
,以便連線至標準探索路徑:
https://www.googleapis.com/.well-known/carddav
將 (HTTP 301
) 重新導向至 Address Book 資源後,您的用戶端程式就可以在其上執行 PROPFIND
來探索 DAV:current-user-principal
、DAV:principal-URL
和 addressbook-home-set
屬性。您的用戶端程式接著可以在 addressbook-home-set
上執行 PROPFIND
,並尋找 addressbook
和 collection
資源,藉此探索主要通訊錄。這項程序的完整說明不在本文件的討論範圍內。詳情請參閱 rfc6352。
根據 rfc6764 的規定,在 HTTP 301
回應中透過已知 URI 上的 PROPFIND
傳回的重新導向路徑,您「不得」永久快取這類路徑。裝置應定期重試已知的 URI 探索,確認快取路徑是否仍為最新資訊,並在路徑有所變更時重新同步處理。Google 建議每 2 到 4 週顯示一次費率。
資源
CardDAV 採用 REST 概念。用戶端應用程式會處理由 URI 指定的資源。此處指定目前的 URI 結構,可協助開發人員瞭解下一節的概念。結構可能會變動,且不可硬式編碼。相反地,您應根據 RFC 找到資源
- 主體
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- https://www.googleapis.com/carddav/v1/principals/
- 住家組合
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists
- https://www.googleapis.com/carddav/v1/principals/
- 通訊錄
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default
- https://www.googleapis.com/carddav/v1/principals/
- 聯絡
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default/contactId
- https://www.googleapis.com/carddav/v1/principals/
同步處理聯絡人
以下是支援作業的一般說明。開發人員應在相關 RFC 中尋找詳細資料。要求與回應主要都是以 XML 編碼。以下是用戶端應用程式用於同步處理的主要作業:
- 使用 CTag
- 用戶端程式會使用通訊錄資源上的
getctag
PROPFIND
要求,判斷伺服器上是否有任何聯絡人已變更,並判斷是否需要同步處理。如果聯絡人有所變更,這個屬性的值保證會改變。用戶端應用程式應儲存這個值,並只在初次同步處理時使用,並在sync-token
失效時做為備用方案使用。定期輪詢getctag
屬性會導致節流。
- 用戶端程式會使用通訊錄資源上的
- 使用 sync-token
- 用戶端程式會使用通訊錄上的
sync-token
PROPFIND
要求來取得代表目前狀態的sync-token
。用戶端應用程式必須儲存這個值並定期發出sync-collection
REPORT
要求,以確認自上次核發時間sync-token
以來的變更。核發權杖的效期為 29 天,REPORT
回應會包含新的sync-token
。
- 用戶端程式會使用通訊錄上的
- 使用 ETag
- 用戶端應用程式會向 Address Book 資源發出
getetag
PROPFIND
要求 (DEPTH
標頭等於DEPTH_1
)。透過保留每位聯絡人的ETag
值,用戶端程式即可要求已變更ETag
的聯絡人值。
- 用戶端應用程式會向 Address Book 資源發出
- 擷取聯絡人
- 用戶端應用程式會發出
addressbook-multiget
REPORT
要求以擷取聯絡人。針對聯絡人 URI 清單,報表會以 VCard 3.0 值傳回所有要求的聯絡人。每個項目都包含聯絡人的ETag
。
- 用戶端應用程式會發出
- 插入聯絡人
- 用戶端應用程式會以 VCard 3.0 格式向新聯絡人發出
POST
要求。回應中會包含新聯絡人的 ID。
- 用戶端應用程式會以 VCard 3.0 格式向新聯絡人發出
- 更新聯絡人
- 用戶端應用程式會向 VCard 3.0 格式的更新聯絡人發出
PUT
要求。如果通訊錄中已有聯絡人,系統便會更新聯絡人。 - 用戶端應用程式應包含
If-Match
標頭,以及聯絡人目前已知的ETag
。如果伺服器上目前的ETag
與用戶端程式傳送的ETag
不同,伺服器就會拒絕PUT
要求 (含HTTP 412
)。如此一來,您就能為更新作業最佳化序列化。
- 用戶端應用程式會向 VCard 3.0 格式的更新聯絡人發出
- 刪除聯絡人
- 用戶端應用程式向聯絡人 URI 發出
DELETE
要求,藉此刪除聯絡人。
- 用戶端應用程式向聯絡人 URI 發出