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

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

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

規格

因此，許多用戶端 (例如 Apple iOSTM 聯絡人 和 macOS 應能正確互通

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

• rfc2518：分散式編寫的 HTTP 擴充功能 (WebDAV)
  • 支援 HTTP 方法 GET、PUT、DELETE、OPTIONS 和 PROPFIND。
  • 「不」支援 HTTP 方法 LOCK、UNLOCK、COPY、MOVE 或 MKCOL。
  • 「不」支援任意 (使用者定義) WebDAV 屬性。
  • 「不」支援 WebDAV 存取控制 (rfc3744)。
• rfc5995：使用 POST 將成員新增至 WebDAV 集合
  • 支援在不指定 ID 的情況下建立新聯絡人。
• rfc6352：CardDAV: vCard Extensions to Web Distributed Authoring，以及 版本管理 (WebDAV)
  • 支援 HTTP 方法 REPORT，但並非所有定義的報表
  • 支援提供主體集合和聯絡人集合。
• rfc6578：WebDAV 的集合同步處理
  • 用戶端應用程式必須在 執行初始同步處理作業
• rfc6749：OAuth 2.0 授權架構和 rfc6750：OAuth 2.0 授權架構：不記名權杖使用
  • 支援使用 OAuth 2.0 HTTP 驗證 CardDAV 用戶端程式 驗證Google 不支援其他任何驗證方法。 為保障聯絡人資料安全，我們要求需透過 CardDAV 連線 HTTPS。
• rfc6764：找到適用於 WebDAV (CalDAV) 的日曆擴充功能和適用於 WebDAV (CardDAV) 的 vCard 擴充功能尋找服務
  • CardDAV 網址的開機程序必須根據第 6 節 ( rfc6764。
• 支援 caldav-ctag-02：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：

• 使用 OAuth 2.0 存取 Google API
• 針對已安裝的應用程式使用 OAuth 2.0

連線至 Google 的 CardDAV 伺服器

CardDAV 通訊協定允許搜尋通訊錄和聯絡資源 URI。請勿對任何 URI 進行硬式編碼，因為 URI 隨時可能變更。

用戶端應用程式必須使用 HTTPS，且必須採用 OAuth 2.0 驗證 儲存在使用者的 Google 帳戶中。CardDAV 伺服器不會 驗證要求 - 除非要求透過 OAuth 2.0 經由 HTTPS 到達 驗證，而您的應用程式已在 DevConsole。任何嘗試透過基本驗證或 如果與 Google 帳戶不相符的電子郵件/密碼，就會 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。

HTTP 301 回應中透過 PROPFIND 傳回的重新導向路徑。 已知的 URI 不得永久快取 ( 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