จัดการรายชื่อติดต่อด้วยโปรโตคอล CardDAV
จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน
บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ
คุณสามารถดูและจัดการรายชื่อติดต่อโดยใช้โปรโตคอล CardDAV ของ Google
รายชื่อติดต่อจะจัดเก็บไว้ในบัญชี Google ของผู้ใช้ โดยบริการส่วนใหญ่ของ Google จะมีสิทธิ์เข้าถึงรายชื่อติดต่อ แอปพลิเคชันไคลเอ็นต์ของคุณสามารถใช้ CardDAV API เพื่อ
สร้างรายชื่อติดต่อใหม่ แก้ไขหรือลบรายชื่อติดต่อที่มีอยู่ และค้นหารายชื่อติดต่อ
ที่ตรงกับเกณฑ์หนึ่งๆ
ข้อกำหนดเฉพาะ
ไม่ได้ใช้ข้อกำหนดฉบับเต็ม แต่ไคลเอ็นต์จำนวนมาก เช่น รายชื่อติดต่อของ Apple iOS™ และ macOS ควรทำงานร่วมกันได้อย่างถูกต้อง
สำหรับข้อกำหนดเฉพาะที่เกี่ยวข้องแต่ละรายการ การรองรับ CardDAV ของ Google มีดังนี้
CardDAV ของ Google ต้องใช้ OAuth 2.0
อินเทอร์เฟซ CardDAV ของ Google ต้องใช้ OAuth 2.0 ดูข้อมูลที่ลิงก์
เอกสารด้านล่างนี้สำหรับข้อมูลเกี่ยวกับการใช้ OAuth 2.0 เพื่อเข้าถึง Google APIs
กำลังเชื่อมต่อกับเซิร์ฟเวอร์ CardDAV ของ Google
โปรโตคอล CardDAV จะช่วยให้ค้นพบสมุดที่อยู่และทรัพยากรสำหรับการติดต่อ
URI คุณต้องไม่กำหนด URI แบบฮาร์ดโค้ด เนื่องจาก URI อาจเปลี่ยนแปลงได้ทุกเมื่อ
แอปพลิเคชันไคลเอ็นต์ต้องใช้ HTTPS และการตรวจสอบสิทธิ์ OAuth 2.0 ต้องใช้
สำหรับบัญชี Google ของผู้ใช้ เซิร์ฟเวอร์ CardDAV จะไม่ตรวจสอบสิทธิ์คำขอ เว้นแต่คำขอจะส่งผ่าน HTTPS พร้อมการตรวจสอบสิทธิ์ OAuth 2.0 ของบัญชี Google และแอปพลิเคชันของคุณได้รับการลงทะเบียนใน DevConsole การพยายามเชื่อมต่อผ่าน HTTP ด้วยการตรวจสอบสิทธิ์พื้นฐานหรือด้วยอีเมล/รหัสผ่านที่ไม่ตรงกับบัญชี Google จะส่งผลให้เกิดรหัสการตอบกลับ HTTP401 Unauthorized
หากต้องการใช้ CardDAV โปรแกรมไคลเอ็นต์ของคุณต้องเชื่อมต่อกับหน้า Canonical ตั้งแต่แรก
เส้นทางการค้นพบโดยใช้ HTTP PROPFIND ใน:
https://www.googleapis.com/.well-known/carddav
เมื่อเปลี่ยนเส้นทาง (HTTP 301) ไปยังทรัพยากรของสมุดที่อยู่ โปรแกรมไคลเอ็นต์
สามารถดำเนินการ PROPFIND บนโค้ดนั้น เพื่อค้นหา
DAV:current-user-principal DAV:principal-URL และ addressbook-home-set
พร็อพเพอร์ตี้ จากนั้นโปรแกรมไคลเอ็นต์จะค้นหาสมุดที่อยู่หลักได้โดยทำ PROPFIND ใน addressbook-home-set และมองหาแหล่งข้อมูล addressbook และ collection คำอธิบายกระบวนการนี้แบบเต็ม
อยู่นอกเหนือขอบเขตของเอกสารนี้ โปรดดู
rfc6352 สำหรับรายละเอียดเพิ่มเติม
เส้นทางการเปลี่ยนเส้นทางที่แสดงในการตอบกลับ HTTP 301 ผ่าน PROPFIND ใน URI ที่รู้จักต้องไม่แคชไว้อย่างถาวร (ตาม rfc6764) อุปกรณ์ควรเป็นที่รู้จักกันดีอีกครั้ง
การค้นพบ URI เป็นระยะเพื่อยืนยันว่าเส้นทางที่แคชไว้ยังเป็นข้อมูลล่าสุดอยู่หรือไม่ และ
ซิงค์ใหม่หากเส้นทางเปลี่ยนแปลง Google ขอแนะนำให้คิดค่าบริการทุก 2-4 สัปดาห์
แหล่งข้อมูล
CardDAV ใช้แนวคิด REST แอปพลิเคชันไคลเอ็นต์จะดำเนินการกับทรัพยากรที่ระบุด้วย URI มีการระบุโครงสร้าง URI ปัจจุบันที่นี่เพื่อช่วย
เข้าใจแนวคิดในส่วนต่อไป โครงสร้างอาจเปลี่ยนแปลงได้และต้องไม่เขียนโค้ดไว้อย่างตายตัว แต่ควรค้นพบแหล่งข้อมูล
ตาม RFC
- หลัก
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- Home Set
- 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 PROPFIND กับที่อยู่
หนังสือเพื่อรับ sync-token ที่แสดงถึงสถานะปัจจุบันของหนังสือ แอปพลิเคชันไคลเอ็นต์ต้องจัดเก็บค่านี้และส่งคําขอ sync-collection
REPORT เป็นระยะๆ เพื่อระบุการเปลี่ยนแปลงนับจาก sync-token ที่ส่งครั้งล่าสุด โทเค็นที่ออกจะมีผลเป็นเวลา 29 วัน และการตอบกลับREPORTจะมีsync-tokenใหม่
- การใช้ ETag
- แอปพลิเคชันไคลเอ็นต์จะส่งคำขอ
getetag PROPFIND ในที่อยู่
แหล่งข้อมูลหนังสือ (ที่มีส่วนหัว DEPTH เท่ากับ DEPTH_1) โดยการรักษา
ค่า ETag ของรายชื่อติดต่อแต่ละรายการ โปรแกรมของไคลเอ็นต์สามารถขอมูลค่าได้
ของรายชื่อติดต่อที่มี ETag มีการเปลี่ยนแปลง
- กำลังดึงข้อมูลรายชื่อติดต่อ
- แอปพลิเคชันไคลเอ็นต์จะเรียกข้อมูลที่อยู่ติดต่อด้วยการออก
คำขอ
REPORT addressbook-multiget รายการ เมื่อระบุรายการ URI ของรายชื่อติดต่อแล้ว รายงานจะแสดงรายชื่อติดต่อทั้งหมดที่ขอเป็นค่า VCard 3.0 ชิ้น
รายการมี ETag สำหรับรายชื่อติดต่อนั้น
- การแทรกรายชื่อติดต่อ
- แอปพลิเคชันไคลเอ็นต์จะส่งคำขอ
POST พร้อมรายชื่อติดต่อใหม่ในรูปแบบ VCard 3.0 การตอบกลับจะมีรหัสของรายชื่อติดต่อใหม่
- การอัปเดตรายชื่อติดต่อ
- แอปพลิเคชันไคลเอ็นต์ส่งคำขอ
PUT พร้อมรายชื่อติดต่อที่อัปเดตในรูปแบบ VCard 3.0 ผู้ติดต่อจะอัปเดตหากมีอยู่แล้ว
ในสมุดที่อยู่
- แอปพลิเคชันไคลเอ็นต์ควรมีส่วนหัว
If-Match ที่มี ETag ที่รู้จักในปัจจุบันของรายชื่อติดต่อ จากนั้นเซิร์ฟเวอร์จะปฏิเสธ PUT
(ที่มี HTTP 412) ถ้า ETag ปัจจุบันบนเซิร์ฟเวอร์คือ
แตกต่างจาก ETag ที่โปรแกรมลูกค้าส่งมา วิธีนี้ช่วยให้สามารถจัดเรียงข้อมูลอัปเดตแบบมองโลกในแง่ดีได้
- การลบรายชื่อติดต่อ
- แอปพลิเคชันไคลเอ็นต์จะลบรายชื่อติดต่อโดยการส่งคำขอ
DELETE กับ URI ของรายชื่อติดต่อ
เนื้อหาของหน้าเว็บนี้ได้รับอนุญาตภายใต้ใบอนุญาตที่ต้องระบุที่มาของครีเอทีฟคอมมอนส์ 4.0 และตัวอย่างโค้ดได้รับอนุญาตภายใต้ใบอนุญาต Apache 2.0 เว้นแต่จะระบุไว้เป็นอย่างอื่น โปรดดูรายละเอียดที่นโยบายเว็บไซต์ Google Developers Java เป็นเครื่องหมายการค้าจดทะเบียนของ Oracle และ/หรือบริษัทในเครือ
อัปเดตล่าสุด 2025-07-25 UTC
[null,null,["อัปเดตล่าสุด 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."]]
