Mengelola kontak dengan protokol CardDAV
Tetap teratur dengan koleksi
Simpan dan kategorikan konten berdasarkan preferensi Anda.
Anda dapat melihat dan mengelola kontak menggunakan protokol CardDAV Google.
Kontak disimpan di Akun Google pengguna; sebagian besar layanan Google memiliki
akses ke daftar kontak. Aplikasi klien Anda dapat menggunakan CardDAV API untuk
membuat kontak baru, mengedit atau menghapus kontak yang ada, dan membuat kueri untuk kontak
yang cocok dengan kriteria tertentu.
Spesifikasi
Spesifikasi lengkap tidak diterapkan, tetapi banyak klien seperti
Kontak Apple iOS™
dan macOS harus beroperasi dengan benar.
Untuk setiap spesifikasi yang relevan, dukungan CardDAV Google adalah sebagai berikut:
- rfc2518: HTTP Extensions for Distributed Authoring (WebDAV)
- Mendukung metode HTTP
GET, PUT, DELETE, OPTIONS, dan
PROPFIND.
- Tidak mendukung metode HTTP
LOCK, UNLOCK, COPY, MOVE, atau
MKCOL.
- Tidak mendukung properti WebDAV arbitrer (ditentukan pengguna).
- Tidak mendukung Kontrol Akses WebDAV (rfc3744).
- rfc5995: Menggunakan POST untuk Menambahkan Anggota ke Koleksi WebDAV
- Mendukung pembuatan kontak baru tanpa menentukan ID.
- rfc6352: CardDAV: Ekstensi Programs Dengan Perluasan Web, serta
Pembuatan Versi (WebDAV)
- Mendukung metode HTTP
REPORT, tetapi tidak semua laporan yang ditentukan
diimplementasikan.
- Dukungan penyediaan kumpulan akun utama dan kumpulan kontak.
- rfc6578: Collection Synchronization for WebDAV
- Aplikasi klien harus beralih ke mode operasi ini setelah
sinkronisasi awal.
- rfc6749: Framework Otorisasi OAuth 2.0 dan
rfc6750: Framework Otorisasi OAuth 2.0: Penggunaan Token Pembawa
- Mendukung autentikasi program klien CardDAV menggunakan Autentikasi HTTP
OAuth 2.0. Google tidak mendukung metode autentikasi lainnya.
Demi keamanan data kontak, kami mewajibkan koneksi CardDAV untuk menggunakan
HTTPS.
- rfc6764: Menemukan Layanan untuk Ekstensi Kalender ke WebDAV (CalDAV) dan Ekstensi Vitals ke WebDAV (CardDAV)
- Bootstrapping URL CardDAV harus dilakukan sesuai dengan bagian 6
rfc6764.
- Mendukung
caldav-ctag-02: Calendar Collection Entity Tag (CTag) di CalDAV,
yang digunakan bersama oleh spesifikasi CardDAV dan CalDAV. Kontak
ctag seperti resource ETag; itu berubah ketika ada
apa pun di dalam kontak
buku alamat telah berubah. Hal ini memungkinkan program klien dengan cepat menentukan
bahwa program tidak perlu menyinkronkan kontak yang diubah.
- Google menggunakan VCard 3.0 sebagai format encoding kontak. Lihat:
rfc6350: VCard 3.0.
CardDAV Google memerlukan OAuth 2.0
Antarmuka CardDAV Google memerlukan OAuth 2.0. Lihat tautan
dokumentasi di bawah ini untuk informasi tentang penggunaan OAuth 2.0 untuk mengakses Google API:
Menghubungkan ke server CardDAV Google
Protokol CardDAV memungkinkan penemuan URI resource buku alamat dan kontak. Anda tidak boleh melakukan hardcode pada URI mana pun karena URI dapat berubah kapan saja.
Aplikasi klien harus menggunakan HTTPS, dan autentikasi OAuth 2.0 harus
disediakan untuk Akun Google pengguna. Server CardDAV tidak akan
melakukan otentikasi permintaan kecuali diterima melalui HTTPS dengan OAuth 2.0
autentikasi akun Google, dan aplikasi Anda terdaftar di
DevConsole. Setiap upaya untuk terhubung melalui HTTP dengan Autentikasi dasar atau dengan
email/sandi yang tidak cocok dengan akun Google akan menghasilkan kode respons
401 Unauthorized HTTP.
Untuk menggunakan CardDAV, program klien Anda harus terhubung terlebih dahulu ke jalur penemuan
kanonik dengan melakukan PROPFIND HTTP di:
https://www.googleapis.com/.well-known/carddav
Setelah dialihkan (HTTP 301) ke Resource Buku Alamat, program klien Anda
dapat melakukan PROPFIND untuk menemukan
DAV:current-user-principal, DAV:principal-URL, dan addressbook-home-set
properti baru. Program klien Anda kemudian dapat
menemukan buku alamat utama dengan
melakukan PROPFIND pada addressbook-home-set dan mencari
addressbook, dan collection. Deskripsi lengkap proses ini
berada di luar cakupan dokumen ini. Lihat
rfc6352 untuk mengetahui detail selengkapnya.
Jalur pengalihan yang ditampilkan dalam respons HTTP 301 melalui PROPFIND di
URI yang dikenal tidak boleh di-cache secara permanen (sesuai dengan
rfc6764). Perangkat harus mencoba lagi
Penemuan URI secara berkala untuk memverifikasi apakah jalur yang di-cache masih terbaru dan
menyinkronkan ulang jika
jalur pernah berubah. Google merekomendasikan rasio setiap 2-4 minggu.
Resource
CardDAV menggunakan konsep REST. Aplikasi klien bertindak pada resource yang
ditetapkan oleh URI-nya. Struktur URI saat ini ditentukan di sini untuk membantu
developer memahami konsep di bagian berikut ini. Struktur dapat
berubah dan tidak boleh di-hardcode. Sebaliknya, sumber daya harus ditemukan
sesuai dengan RFC.
- Kepala sekolah
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- Home Set
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists
- Buku Alamat
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists/default
- Kontak
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists/default/contactId
Berikut adalah deskripsi umum dari operasi yang didukung. Developer
harus mencari detail dalam RFC yang relevan. Permintaan dan respons
sebagian besar dikodekan dalam XML. Berikut adalah operasi utama yang digunakan oleh aplikasi
klien untuk sinkronisasi:
- Menggunakan CTag
- Program klien menggunakan permintaan
getctag PROPFIND pada resource Alamat Buku
untuk menentukan apakah ada kontak yang telah berubah di server dan
karenanya apakah sinkronisasi diperlukan. Nilai properti ini
dijamin berubah jika ada perubahan kontak. Aplikasi klien
harus menyimpan nilai ini dan menggunakannya hanya pada sinkronisasi awal dan sebagai
jika sync-token tidak valid. Mengambil sampel properti getctag secara berkala akan menyebabkan throttling.
- Menggunakan token sinkronisasi
- Program klien menggunakan permintaan
sync-token PROPFIND di Alamat
Buku untuk mendapatkan sync-token yang mewakili statusnya saat ini. Aplikasi
klien harus menyimpan nilai ini dan mengeluarkan permintaan sync-collection
REPORT berkala untuk menentukan perubahan sejak sync-token
terakhir dikeluarkan. Token yang diterbitkan berlaku selama 29 hari, dan REPORT
akan berisi sync-token baru.
- Menggunakan ETag
- Aplikasi klien mengeluarkan permintaan
getetag PROPFIND pada resource Alamat
Buku (dengan header DEPTH sama dengan DEPTH_1). Dengan mempertahankan
nilai ETag dari setiap kontak, program klien dapat meminta nilai
kontak yang ETag-nya telah diubah.
- Mengambil kontak
- Aplikasi klien mengambil kontak dengan mengeluarkan
permintaan
addressbook-multiget REPORT. Dengan mempertimbangkan daftar URI kontak,
laporan mengembalikan semua kontak
yang diminta sebagai nilai VCard 3.0. Masing-masing
entri menyertakan ETag untuk kontak.
- Menyisipkan kontak
- Aplikasi klien mengirimkan permintaan
POST dengan kontak baru di VCard
dalam format 3.0. Respons akan berisi ID kontak baru.
- Memperbarui kontak
- Aplikasi klien mengeluarkan permintaan
PUT dengan kontak yang diperbarui dalam format VCard 3.0. Kontak akan diperbarui jika kontak tersebut sudah ada
di buku alamat.
- Aplikasi klien harus menyertakan header
If-Match dengan atribut
kontak yang saat ini dikenal ETag. Server kemudian akan menolak permintaan PUT
(dengan HTTP 412) jika ETag saat ini di server
berbeda dengan ETag yang dikirim oleh program klien. Hal ini memungkinkan
serialisasi update yang optimis.
- Menghapus kontak
- Aplikasi klien menghapus kontak dengan mengeluarkan permintaan
DELETE
terhadap URI kontak.
Kecuali dinyatakan lain, konten di halaman ini dilisensikan berdasarkan Lisensi Creative Commons Attribution 4.0, sedangkan contoh kode dilisensikan berdasarkan Lisensi Apache 2.0. Untuk mengetahui informasi selengkapnya, lihat Kebijakan Situs Google Developers. Java adalah merek dagang terdaftar dari Oracle dan/atau afiliasinya.
Terakhir diperbarui pada 2025-07-25 UTC.
[[["Mudah dipahami","easyToUnderstand","thumb-up"],["Memecahkan masalah saya","solvedMyProblem","thumb-up"],["Lainnya","otherUp","thumb-up"]],[["Informasi yang saya butuhkan tidak ada","missingTheInformationINeed","thumb-down"],["Terlalu rumit/langkahnya terlalu banyak","tooComplicatedTooManySteps","thumb-down"],["Sudah usang","outOfDate","thumb-down"],["Masalah terjemahan","translationIssue","thumb-down"],["Masalah kode / contoh","samplesCodeIssue","thumb-down"],["Lainnya","otherDown","thumb-down"]],["Terakhir diperbarui pada 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."]]
