Quản lý danh bạ bằng giao thức CardDAV
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Bạn có thể xem và quản lý danh bạ của mình bằng giao thức CardDAV của Google.
Danh bạ được lưu trữ trong Tài khoản Google của người dùng; hầu hết các dịch vụ của Google đều có quyền truy cập vào danh bạ. Ứng dụng khách của bạn có thể sử dụng API CardDAV để tạo người liên hệ mới, chỉnh sửa hoặc xoá người liên hệ hiện có và truy vấn người liên hệ khớp với các tiêu chí cụ thể.
Thông số kỹ thuật
Không triển khai toàn bộ thông số kỹ thuật, nhưng nhiều ứng dụng như Danh bạ Apple iOS™ và macOS sẽ tương tác chính xác.
Đối với mỗi thông số kỹ thuật có liên quan, dịch vụ hỗ trợ CardDAV của Google như sau:
CardDAV của Google yêu cầu OAuth 2.0
Giao diện CardDAV của Google yêu cầu OAuth 2.0. Tham khảo
tài liệu bên dưới để biết thông tin về cách sử dụng OAuth 2.0 để truy cập Google API:
Kết nối với máy chủ CardDAV của Google
Giao thức CardDAV cho phép khám phá sổ địa chỉ và URI tài nguyên liên hệ. Bạn không được mã hoá cứng bất kỳ URI nào vì các URI này có thể thay đổi bất cứ lúc nào.
Ứng dụng phải sử dụng HTTPS và phải xác thực OAuth 2.0
được cung cấp cho Tài khoản Google của người dùng. Máy chủ CardDAV sẽ không
xác thực một yêu cầu trừ khi yêu cầu đó đến qua HTTPS bằng OAuth 2.0
xác thực Tài khoản Google và đăng ký ứng dụng trên
Bảng điều khiển dành cho nhà phát triển. Mọi nỗ lực kết nối qua HTTP bằng phương thức xác thực Cơ bản hoặc bằng email/mật khẩu không khớp với Tài khoản Google đều dẫn đến mã phản hồi HTTP 401 Unauthorized.
Để sử dụng CardDAV, ban đầu chương trình khách của bạn phải kết nối với trang chuẩn
khám phá bằng cách thực hiện HTTP PROPFIND trên:
https://www.googleapis.com/.well-known/carddav
Sau khi được chuyển hướng (HTTP 301) đến một Tài nguyên sổ địa chỉ, chương trình ứng dụng của bạn có thể thực hiện PROPFIND trên tài nguyên đó để khám phá các thuộc tính DAV:current-user-principal, DAV:principal-URL và addressbook-home-set. Sau đó, chương trình khách hàng của bạn có thể khám phá sổ địa chỉ chính bằng cách
biểu diễn PROPFIND trên addressbook-home-set và tìm
Các tài nguyên addressbook và collection. Thông tin mô tả đầy đủ về quy trình này
nằm ngoài phạm vi của tài liệu này. Xem
rfc6352 để biết thêm thông tin chi tiết.
Đường dẫn chuyển hướng được trả về trong phản hồi HTTP 301 thông qua PROPFIND trên
URI phổ biến không được lưu vào bộ nhớ đệm vĩnh viễn (theo mỗi
rfc6764). Thiết bị nên định kỳ thử lại việc khám phá URI phổ biến để xác minh xem đường dẫn được lưu vào bộ nhớ đệm có còn mới nhất hay không và đồng bộ hoá lại nếu đường dẫn đó thay đổi. Google đề xuất bạn nên thay đổi giá trong khoảng từ 2 đến 4 tuần.
Tài nguyên
CardDAV sử dụng các khái niệm REST. Ứng dụng khách hành động trên các tài nguyên
được chỉ định bởi URI của họ. Cấu trúc URI hiện tại được chỉ định tại đây để giúp
nhà phát triển hiểu các khái niệm trong phần sau. Cấu trúc có thể thay đổi và không được mã hoá cứng. Thay vào đó, các tài nguyên phải được phát hiện theo RFC.
- Hiệu trưởng
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- Bộ nhà riêng
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists
- Sổ địa chỉ
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists/default
- Liên hệ
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists/default/contactId
Sau đây là nội dung mô tả chung về các thao tác được hỗ trợ. Nhà phát triển
nên tìm thông tin chi tiết trong RFC có liên quan. Yêu cầu và phản hồi
chủ yếu được mã hoá dưới dạng XML. Đây là những thao tác chính mà khách hàng sử dụng
để đồng bộ hoá:
- Sử dụng CTag
- Các chương trình ứng dụng sử dụng yêu cầu
getctag PROPFIND trên tài nguyên Danh bạ để xác định xem có thay đổi nào đối với danh bạ trên máy chủ hay không và do đó, liệu có cần đồng bộ hoá hay không. Giá trị của thuộc tính này chắc chắn sẽ thay đổi nếu có bất kỳ thông tin liên hệ nào thay đổi. Ứng dụng
nên lưu trữ giá trị này và chỉ sử dụng nó trong lần đồng bộ hoá ban đầu và dưới dạng
dự phòng khi sync-token không hợp lệ. Thăm dò định kỳ
Thuộc tính getctag sẽ dẫn đến tình trạng điều tiết.
- Sử dụng mã thông báo đồng bộ hoá
- Các chương trình ứng dụng sử dụng yêu cầu
sync-token PROPFIND trên Address
Book để lấy sync-token thể hiện trạng thái hiện tại của ứng dụng. Ứng dụng
khách phải lưu trữ giá trị này và phát hành các yêu cầu sync-collection
REPORT định kỳ để xác định các thay đổi kể từ lần phát hành
sync-token gần đây nhất. Mã thông báo đã phát hành có hiệu lực trong 29 ngày và phản hồi REPORT sẽ chứa một sync-token mới.
- Sử dụng ETag
- Ứng dụng khách đưa ra yêu cầu
getetag PROPFIND trên tài nguyên Danh bạ (có tiêu đề DEPTH bằng DEPTH_1). Bằng cách duy trì giá trị ETag của mỗi người liên hệ, chương trình khách có thể yêu cầu giá trị của những người liên hệ đã thay đổi ETag.
- Truy xuất danh bạ
- Ứng dụng khách truy xuất thông tin liên hệ bằng cách đưa ra yêu cầu
addressbook-multiget REPORT. Khi cung cấp một danh sách URI liên hệ,
báo cáo trả về tất cả các địa chỉ liên hệ được yêu cầu dưới dạng giá trị VCard 3.0. Mỗi mục nhập bao gồm một ETag cho người liên hệ.
- Chèn người liên hệ
- Các ứng dụng đưa ra yêu cầu
POST với địa chỉ liên hệ mới trong VCard
Định dạng 3.0. Phản hồi sẽ chứa mã nhận dạng của người liên hệ mới.
- Cập nhật một người liên hệ
- Các ứng dụng khách đưa ra yêu cầu
PUT với thông tin liên hệ đã cập nhật ở định dạng VCard 3.0. Người liên hệ sẽ được cập nhật nếu người liên hệ đó đã tồn tại trong sổ địa chỉ.
- Ứng dụng khách phải bao gồm tiêu đề
If-Match với ETag hiện có của người liên hệ. Sau đó, máy chủ sẽ từ chối yêu cầu PUT (bằng HTTP 412) nếu ETag hiện tại trên máy chủ khác với ETag do chương trình ứng dụng gửi. Điều này cho phép
chuyển đổi tuần tự các bản cập nhật một cách lạc quan.
- Xoá người liên hệ
- Các ứng dụng khách xoá một người liên hệ bằng cách đưa ra yêu cầu
DELETE đối với URI liên hệ.
Trừ phi có lưu ý khác, nội dung của trang này được cấp phép theo Giấy phép ghi nhận tác giả 4.0 của Creative Commons và các mẫu mã lập trình được cấp phép theo Giấy phép Apache 2.0. Để biết thông tin chi tiết, vui lòng tham khảo Chính sách trang web của Google Developers. Java là nhãn hiệu đã đăng ký của Oracle và/hoặc các đơn vị liên kết với Oracle.
Cập nhật lần gần đây nhất: 2025-07-25 UTC.
[[["Dễ hiểu","easyToUnderstand","thumb-up"],["Giúp tôi giải quyết được vấn đề","solvedMyProblem","thumb-up"],["Khác","otherUp","thumb-up"]],[["Thiếu thông tin tôi cần","missingTheInformationINeed","thumb-down"],["Quá phức tạp/quá nhiều bước","tooComplicatedTooManySteps","thumb-down"],["Đã lỗi thời","outOfDate","thumb-down"],["Vấn đề về bản dịch","translationIssue","thumb-down"],["Vấn đề về mẫu/mã","samplesCodeIssue","thumb-down"],["Khác","otherDown","thumb-down"]],["Cập nhật lần gần đây nhất: 2025-07-25 UTC."],[[["\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."]]
