您可以使用 Google 的 CardDAV 通訊協定,查看及管理聯絡人。
聯絡人會儲存在使用者的 Google 帳戶中,大多數 Google 服務都能存取聯絡人清單。您的用戶端應用程式可以使用 CardDAV API 進行以下操作: 建立新聯絡人、編輯或刪除現有聯絡人,以及查詢聯絡人 與特定條件相符的廣告
規格
雖然未實作完整規格,但許多用戶端 (例如 Apple iOS™ 聯絡人和 macOS) 應可正確互通。
針對各項相關規格,Google 提供的 CardDAV 支援如下:
- rfc2518:分散式製作工具的 HTTP 擴充功能 (WebDAV)
- 支援 HTTP 方法
GET
、PUT
、DELETE
、OPTIONS
和PROPFIND
。 - 不支援 HTTP 方法
LOCK
、UNLOCK
、COPY
、MOVE
或MKCOL
。 - 「不」支援任意 (使用者定義) WebDAV 屬性。
- 「不」支援 WebDAV 存取控制 (rfc3744)。
- 支援 HTTP 方法
- rfc5995:使用 POST 將成員新增至 WebDAV 集合
- 支援在不指定 ID 的情況下建立新聯絡人。
- rfc6352:CardDAV: vCard Extensions to Web Distributed Authoring,以及
版本管理 (WebDAV)
- 支援 HTTP 方法
REPORT
,但並非所有定義的報表 - 支援提供主要收件者集合和聯絡人集合。
- 支援 HTTP 方法
- 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:
連線至 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-principal
、DAV:principal-URL
和 addressbook-home-set
資源。這樣一來,您的客戶程式就能根據
在 addressbook-home-set
上執行 PROPFIND
,然後找出
addressbook
和 collection
資源。這項程序的完整說明
不在本文件的說明範圍內。詳情請參閱 rfc6352。
在已知 URI 上透過 PROPFIND
傳回的 HTTP 301
回應中,重新導向路徑不得永久快取 (依據 rfc6764)。裝置應重試已知
定期探索 URI,藉此驗證快取路徑是否仍為最新版本,
如果路徑有所變更,請重新同步處理。Google 建議每 2 到 4 週更新一次。
資源
CardDAV 使用 REST 概念。用戶端應用程式 指定的名稱我們在此處指定目前的 URI 結構,協助開發人員瞭解後續章節中的概念。建築物結構 不能使用硬式編碼相反地, 的 RFC 19
- 校長
- 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
- 用戶端應用程式會向地址發出
getetag
PROPFIND
要求 書籍資源 (DEPTH
標頭等於DEPTH_1
)。藉由維護 每位聯絡人的ETag
值,用戶端程式就能要求 的ETag
聯絡人有所變化。
- 用戶端應用程式會向地址發出
- 擷取聯絡人
- 用戶端應用程式會透過發出
addressbook-multiget
REPORT
要求。系統會根據聯絡人 URI 清單,以 VCard 3.0 值的形式傳回所有要求的聯絡人。每個項目都包含聯絡人的ETag
。
- 用戶端應用程式會透過發出
- 插入聯絡人
- 用戶端應用程式會向 VCard 中的新聯絡人發出
POST
要求 3.0 格式。回應中會包含新聯絡人的 ID。
- 用戶端應用程式會向 VCard 中的新聯絡人發出
- 更新聯絡人
- 用戶端應用程式會發出
PUT
要求,並以 VCard 3.0 格式傳送更新的聯絡資訊。如果聯絡人已存在,系統會更新聯絡人資料 。 - 用戶端應用程式應包含
If-Match
標頭,其中包含聯絡人的目前已知ETag
。接著,伺服器會拒絕PUT
要求 (使用HTTP 412
),如果伺服器上目前的ETag
為 和用戶端程式傳送的ETag
不同。這可讓更新內容以樂觀序列化。
- 用戶端應用程式會發出
- 刪除聯絡人
- 用戶端應用程式會透過發出
DELETE
要求來刪除聯絡人 並傳送給聯絡 URI
- 用戶端應用程式會透過發出