使用 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-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/
userEmail/lists
- 通訊錄
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists/default
- 聯絡
- 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
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-07-25 (世界標準時間)。
[null,null,["上次更新時間：2025-07-25 (世界標準時間)。"],[[["\u003cp\u003eGoogle Contacts can be accessed and managed using the CardDAV protocol, enabling client applications to create, edit, delete, and query contacts.\u003c/p\u003e\n"],["\u003cp\u003eGoogle's CardDAV implementation requires OAuth 2.0 for authentication and HTTPS for secure connections.\u003c/p\u003e\n"],["\u003cp\u003eClient applications should discover resource URIs dynamically instead of hardcoding them, as they are subject to change.\u003c/p\u003e\n"],["\u003cp\u003eContact synchronization can be achieved using CTag, sync-token, or ETags to efficiently track and update changes.\u003c/p\u003e\n"],["\u003cp\u003eGoogle's CardDAV utilizes VCard 3.0 for encoding contact data.\u003c/p\u003e\n"]]],["Google's CardDAV protocol allows managing contacts stored in a Google Account. Client applications can create, edit, delete, and query contacts using the CardDAV API. Key actions include using `PROPFIND` for discovery and obtaining `sync-token` and `getctag` for synchronization. Retrieving contacts is done with `addressbook-multiget REPORT`, while inserting, updating, and deleting contacts utilize `POST`, `PUT` (with `If-Match`), and `DELETE` requests, respectively. Authentication requires HTTPS and OAuth 2.0, and VCard 3.0 is the contact encoding format.\n"],null,["# Manage contacts with the CardDAV protocol\n\nYou can view and manage your contacts using Google's CardDAV protocol.\n\nContacts are stored in the user's Google Account; most Google services have\naccess to the contact list. Your client application can use the CardDAV API to\ncreate new contacts, edit or delete existing contacts, and query for contacts\nthat match particular criteria.\n\nSpecifications\n--------------\n\nThe full specification is not implemented, but many clients such as\n[Apple iOS™ Contacts](https://support.google.com/contacts/answer/2753077?co=GENIE.Platform%3DiOS)\nand macOS should interoperate correctly.\n\nFor each relevant specification, Google's CardDAV support is as follows:\n\n- [rfc2518: HTTP Extensions for Distributed Authoring (WebDAV)](https://tools.ietf.org/html/rfc2518)\n - Supports the HTTP methods `GET`, `PUT`, `DELETE`, `OPTIONS`, and `PROPFIND`.\n - Does *not* support the HTTP methods `LOCK`, `UNLOCK`, `COPY`, `MOVE`, or `MKCOL`.\n - Does *not* support arbitrary (user-defined) WebDAV properties.\n - Does *not* support WebDAV Access Control (rfc3744).\n- [rfc5995: Using POST to Add Members to WebDAV Collections](https://tools.ietf.org/html/rfc5995)\n - Supports creating new contacts without specifying an ID.\n- [rfc6352: CardDAV: vCard Extensions to Web Distributed Authoring and\n Versioning (WebDAV)](https://tools.ietf.org/html/rfc6352)\n - Supports the HTTP method `REPORT`, but not all defined reports are implemented.\n - Supports providing a principal collection and a contacts collection.\n- [rfc6578: Collection Synchronization for WebDAV](https://tools.ietf.org/html/rfc6578)\n - Client applications must switch to this mode of operation after the initial sync.\n- [rfc6749: The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749) and [rfc6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750)\n - Supports authenticating CardDAV client programs using OAuth 2.0 HTTP Authentication. Google does not support any other authentication method. For security of contact data, we require CardDAV connections to use [HTTPS](https://en.wikipedia.org/wiki/HTTPS).\n- [rfc6764: Locating Services for Calendaring Extensions to WebDAV (CalDAV) and vCard Extensions to WebDAV (CardDAV)](https://tools.ietf.org/html/rfc6764)\n - Bootstrapping of CardDAV URLs must take place according to section 6 of rfc6764.\n- Supports [caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV](https://github.com/apple/ccs-calendarserver/blob/master/doc/Extensions/caldav-ctag.txt), which is shared between the CardDAV and CalDAV specifications. The contacts `ctag` is like a resource `ETag`; it changes when anything in the contact address book has changed. This allows the client program to quickly determine that it does not need to synchronize any changed contacts.\n- Google uses VCard 3.0 as the contact encoding format. See: [rfc6350: VCard 3.0](https://tools.ietf.org/html/rfc6350).\n\nGoogle's CardDAV requires OAuth 2.0\n-----------------------------------\n\nGoogle's CardDAV interface requires OAuth 2.0. Refer to the linked\ndocumentation below for information on using OAuth 2.0 to access Google APIs:\n\n- [Using OAuth 2.0 to Access Google APIs](https://developers.google.com/identity/protocols/oauth2)\n- [Using OAuth 2.0 for Installed Applications](https://developers.google.com/identity/protocols/oauth2/native-app)\n\nConnecting to Google's CardDAV server\n-------------------------------------\n\nThe CardDAV protocol allows discovery of the address book and contact resources\nURIs. You must not hardcode any URI as they could change at any time.\n\nClient applications must use HTTPS, and `OAuth 2.0` authentication must be\nprovided for the user's Google account. The CardDAV server will not\nauthenticate a request unless it arrives over HTTPS with OAuth 2.0\nauthentication of a Google account, and your application is registered on\nDevConsole. Any attempt to connect over HTTP with Basic authentication or with\nan email/password that doesn't match a Google account results in an HTTP\n`401 Unauthorized` response code.\n\nTo use CardDAV, your client program must initially connect to the canonical\ndiscovery path by performing an HTTP `PROPFIND` on: \n\n https://www.googleapis.com/.well-known/carddav\n\nOnce redirected (`HTTP 301`) to an Address Book Resource, your client program\ncan then perform a `PROPFIND` on it to discover the\n`DAV:current-user-principal`, `DAV:principal-URL`, and `addressbook-home-set`\nproperties. Your client program can then discover the principal address book by\nperforming a `PROPFIND` on the `addressbook-home-set` and looking for the\n`addressbook` and `collection` resources. A full description of this process\nis beyond the scope of this document. See\n[rfc6352](https://tools.ietf.org/html/rfc6352) for more details.\n\nThe redirect path returned in the `HTTP 301` response through a `PROPFIND` on\nthe well-known URI must **not** be permanently cached (as per\n[rfc6764](https://tools.ietf.org/html/rfc6764)). Devices should retry well-known\nURI discovery periodically to verify if the cached path is still up to date and\nresync if the path ever changes. Google recommends a rate of every 2-4 weeks.\n\nResources\n---------\n\nCardDAV uses REST concepts. Client applications act on resources that are\ndesignated by their URIs. The current URI structure is specified here to help\ndevelopers understand the concepts in the following section. The structure may\nchange and must not be hardcoded. Rather, the resources should be discovered\naccording to the RFC.\n\n1. **Principal**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e\n2. **Home Set**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e/lists\n3. **Address Book**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e/lists/default\n4. **Contact**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e/lists/default/\u003cvar class=\"apiparam\" translate=\"no\"\u003econtactId\u003c/var\u003e\n\nSynchronizing Contacts\n----------------------\n\nThe following is a general description of the operations supported. Developers\nshould look for the details in the relevant RFC. Requests and responses are\nmostly encoded in XML. These are the main operations used by client\napplications for synchronization:\n\n- **Using CTag**\n - Client programs use the `getctag` `PROPFIND` request on the Address Book resource to determine if any contact has changed on the server and therefore whether a synchronization is needed. The value of this property is guaranteed to change if any contact changes. Client applications should store this value and use it only on the initial sync and as a fallback when a `sync-token` is invalidated. Periodically polling for the `getctag` property will result in throttling.\n- **Using sync-token**\n - Client programs use the `sync-token` `PROPFIND` request on the Address Book to obtain the `sync-token` representing its current state. Client applications must store this value and issue periodic `sync-collection` `REPORT` requests to determine changes since the last issued `sync-token`. Issued tokens are valid for 29 days, and the `REPORT` response will contain a new `sync-token`.\n- **Using ETags**\n - Client applications issue a `getetag` `PROPFIND` request on the Address Book resource (with `DEPTH` header equal to `DEPTH_1`). By maintaining the `ETag` value of each contact, a client program can request the value of contacts that had their `ETag` changed.\n- **Retrieving contacts**\n - Client applications retrieve contacts by issuing an `addressbook-multiget` `REPORT` request. Given a list of contact URIs, the report returns all the requested contacts as VCard 3.0 values. Each entry includes an `ETag` for the contact.\n- **Inserting a contact**\n - Client applications issue a `POST` request with the new contact in VCard 3.0 format. The response will contain the ID of the new contact.\n- **Updating a contact**\n - Client applications issue a `PUT` request with the updated contact in VCard 3.0 format. The contact is updated if the contact already exists in the address book.\n - Client applications should include an `If-Match` header with the contact's currently known `ETag`. The server will then reject the `PUT` request (with `HTTP 412`) if the current `ETag` on the server is different from the `ETag` sent by the client program. This allows for optimistic serialization of updates.\n- **Deleting a contact**\n - Client applications delete a contact by issuing a `DELETE` request against the contact URI."]]
