使用 CardDAV 通訊協定管理聯絡人

您可以使用 Google 的 CardDAV 通訊協定,查看及管理聯絡人。

聯絡人會儲存在使用者的 Google 帳戶中,大多數 Google 服務都能存取聯絡人清單。您的用戶端應用程式可以使用 CardDAV API 進行以下操作: 建立新聯絡人、編輯或刪除現有聯絡人,以及查詢聯絡人 與特定條件相符的廣告

規格

雖然未實作完整規格,但許多用戶端 (例如 Apple iOS™ 聯絡人和 macOS) 應可正確互通。

針對各項相關規格,Google 提供的 CardDAV 支援如下:

Google 的 CardDAV 需要使用 OAuth 2.0

Google 的 CardDAV 介面需要 OAuth 2.0。請參閱 以下說明文件,瞭解如何使用 OAuth 2.0 存取 Google API:

連線至 Google 的 CardDAV 伺服器

CardDAV 通訊協定可用於探索通訊錄和聯絡人資源的 URI。請勿對任何 URI 進行硬式編碼,因為 URI 隨時可能變更。

用戶端應用程式必須使用 HTTPS,且必須採用 OAuth 2.0 驗證 儲存在使用者的 Google 帳戶中。除非透過 HTTPS 傳送 Google 帳戶的 OAuth 2.0 驗證,且應用程式已在開發人員工作室註冊,否則 CardDAV 伺服器不會驗證要求。任何嘗試透過基本驗證或 如果與 Google 帳戶不相符的電子郵件/密碼,就會 401 Unauthorized 回應代碼。

如要使用 CardDAV,用戶端程式必須先在下列項目上執行 HTTP PROPFIND,才能連線至標準探索路徑:

https://www.googleapis.com/.well-known/carddav

將 (HTTP 301) 重新導向至 Address Book 之後,您的用戶端程式 然後對其執行 PROPFIND 來探索 DAV:current-user-principalDAV:principal-URLaddressbook-home-set 資源。這樣一來,您的客戶程式就能根據 在 addressbook-home-set 上執行 PROPFIND,然後找出 addressbookcollection 資源。這項程序的完整說明 不在本文件的說明範圍內。詳情請參閱 rfc6352

在已知 URI 上透過 PROPFIND 傳回的 HTTP 301 回應中,重新導向路徑不得永久快取 (依據 rfc6764)。裝置應重試已知 定期探索 URI,藉此驗證快取路徑是否仍為最新版本, 如果路徑有所變更,請重新同步處理。Google 建議每 2 到 4 週更新一次。

資源

CardDAV 使用 REST 概念。用戶端應用程式 指定的名稱我們在此處指定目前的 URI 結構,協助開發人員瞭解後續章節中的概念。建築物結構 不能使用硬式編碼相反地, 的 RFC 19

  1. 校長
    • https://www.googleapis.com/carddav/v1/principals/userEmail
  2. 家用裝置組
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists
  3. 通訊錄
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
  4. 聯絡
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default/contactId

同步處理聯絡人

以下為支援作業的概要說明。開發人員應在相關 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
    • 用戶端應用程式會向地址發出 getetag PROPFIND 要求 書籍資源 (DEPTH 標頭等於 DEPTH_1)。藉由維護 每位聯絡人的 ETag 值,用戶端程式就能要求 的ETag聯絡人有所變化。
  • 擷取聯絡人
    • 用戶端應用程式會透過發出 addressbook-multiget REPORT要求。系統會根據聯絡人 URI 清單,以 VCard 3.0 值的形式傳回所有要求的聯絡人。每個項目都包含聯絡人的 ETag
  • 插入聯絡人
    • 用戶端應用程式會向 VCard 中的新聯絡人發出 POST 要求 3.0 格式。回應中會包含新聯絡人的 ID。
  • 更新聯絡人
    • 用戶端應用程式會發出 PUT 要求,並以 VCard 3.0 格式傳送更新的聯絡資訊。如果聯絡人已存在,系統會更新聯絡人資料 。
    • 用戶端應用程式應包含 If-Match 標頭,其中包含聯絡人的目前已知 ETag。接著,伺服器會拒絕 PUT 要求 (使用 HTTP 412),如果伺服器上目前的 ETag 為 和用戶端程式傳送的 ETag 不同。這可讓更新內容以樂觀序列化。
  • 刪除聯絡人
    • 用戶端應用程式會透過發出 DELETE 要求來刪除聯絡人 並傳送給聯絡 URI