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 kontak yang cocok dengan kriteria tertentu.
Spesifikasi
Spesifikasi lengkap tidak diterapkan, tetapi banyak klien seperti Kontak Apple iOSTM dan macOS harus dapat beroperasi dengan benar.
Untuk setiap spesifikasi yang relevan, dukungan CardDAV Google adalah sebagai berikut:
- rfc2518: Ekstensi HTTP untuk Penulisan Terdistribusi (WebDAV)
- Mendukung metode HTTP
GET
,PUT
,DELETE
,OPTIONS
, danPROPFIND
. - Tidak mendukung metode HTTP
LOCK
,UNLOCK
,COPY
,MOVE
, atauMKCOL
. - Tidak mendukung properti WebDAV arbitrer (ditentukan oleh pengguna).
- Tidak mendukung Kontrol Akses WebDAV (rfc3744).
- Mendukung metode HTTP
- rfc5995: Menggunakan POST untuk Menambahkan Anggota ke Koleksi WebDAV
- Mendukung pembuatan kontak baru tanpa menentukan ID.
- rfc6352: CardDAV: Ekstensi Vitals ke Penulisan yang Didistribusikan Web dan
Pembuatan Versi (WebDAV)
- Mendukung metode HTTP
REPORT
, tetapi tidak semua laporan yang ditentukan diimplementasikan. - Dukungan penyediaan kumpulan akun utama dan kumpulan kontak.
- Mendukung metode HTTP
- rfc6578: Sinkronisasi Koleksi untuk 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 HTTP OAuth 2.0 Autentikasi. 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)
- Bootstrap pada URL CardDAV harus dilakukan sesuai dengan pasal 6 dari rfc6764.
- Mendukung
caldav-ctag-02: Calendar Collection Entity Tag (CTag) di CalDAV,
yang digunakan bersama oleh spesifikasi CardDAV dan CalDAV. Kontak
ctag
seperti resourceETag
; itu berubah ketika apa pun di kontak buku alamat telah berubah. Hal ini memungkinkan program klien untuk dengan cepat menentukan bahwa tidak perlu menyinkronkan setiap kontak yang berubah. - 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 buku alamat dan referensi kontak URI. 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
yang 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. Segala upaya untuk terhubung melalui HTTP dengan
otentikasi Dasar atau dengan
email/kata sandi yang tidak cocok dengan akun Google menghasilkan permintaan HTTP
Kode respons 401 Unauthorized
.
Untuk menggunakan CardDAV, program klien Anda harus terlebih dahulu terhubung ke versi kanonis
jalur penemuan dengan menjalankan PROPFIND
HTTP pada:
https://www.googleapis.com/.well-known/carddav
Setelah dialihkan (HTTP 301
) ke Resource Buku Alamat, program klien Anda
kemudian 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
di luar cakupan dokumen ini. Lihat
rfc6352 untuk 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 sumber daya yang yang ditentukan oleh URI-nya. Struktur URI saat ini ditentukan di sini untuk membantu developer memahami konsep di bagian berikut ini. Strukturnya mungkin diubah dan tidak boleh di-hardcode. Sebaliknya, sumber daya harus ditemukan sesuai dengan RFC.
- Kepala sekolah
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- https://www.googleapis.com/carddav/v1/principals/
- Set Rumah
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists
- https://www.googleapis.com/carddav/v1/principals/
- Buku Alamat
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default
- https://www.googleapis.com/carddav/v1/principals/
- Kontak
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default/contactId
- https://www.googleapis.com/carddav/v1/principals/
Menyinkronkan Kontak
Berikut adalah deskripsi umum dari operasi yang didukung. Developer harus mencari detail dalam RFC yang relevan. Permintaan dan respons sebagian besar dikodekan dalam XML. Ini adalah operasi utama yang digunakan oleh klien aplikasi untuk sinkronisasi:
- Menggunakan CTag
- Program klien menggunakan permintaan
getctag
PROPFIND
di Buku Alamat sumber daya untuk menentukan apakah ada kontak yang berubah di server dan sehingga perlu mengetahui 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 jikasync-token
tidak valid. Lakukan polling secara berkala untuk Propertigetctag
akan menyebabkan throttling.
- Program klien menggunakan permintaan
- Menggunakan token sinkronisasi
- Program klien menggunakan permintaan
sync-token
PROPFIND
di Alamat Buku untuk mendapatkansync-token
yang mewakili statusnya saat ini. Klien aplikasi harus menyimpan nilai ini dan menerbitkansync-collection
berkalaREPORT
permintaan untuk menentukan perubahan sejak terakhir diterbitkansync-token
. Token yang diterbitkan berlaku selama 29 hari, danREPORT
akan berisisync-token
baru.
- Program klien menggunakan permintaan
- Menggunakan ETag
- Aplikasi klien mengajukan permintaan
PROPFIND
getetag
di Alamat Referensi buku (dengan headerDEPTH
sama denganDEPTH_1
). Dengan mempertahankan nilaiETag
dari setiap kontak, program klien dapat meminta nilai tersebut kontak yangETag
-nya berubah.
- Aplikasi klien mengajukan permintaan
- Mengambil kontak
- Aplikasi klien mengambil kontak dengan mengeluarkan
addressbook-multiget
permintaanREPORT
. Dengan mempertimbangkan daftar URI kontak, laporan mengembalikan semua kontak yang diminta sebagai nilai VCard 3.0. Masing-masing entri menyertakanETag
untuk kontak.
- Aplikasi klien mengambil kontak dengan mengeluarkan
- Menyisipkan kontak
- Aplikasi klien mengirimkan permintaan
POST
dengan kontak baru di VCard dalam format 3.0. Respons akan berisi ID kontak baru.
- Aplikasi klien mengirimkan permintaan
- Memperbarui kontak
- Aplikasi klien mengajukan permintaan
PUT
dengan kontak yang diperbarui di Format VCard 3.0. Kontak akan diperbarui jika kontak sudah ada di buku alamat. - Aplikasi klien harus menyertakan header
If-Match
dengan atribut kontak yang saat ini dikenalETag
. Server kemudian akan menolakPUT
(denganHTTP 412
) jikaETag
saat ini di server berbeda dariETag
yang dikirim oleh program klien. Hal ini memungkinkan serialisasi update optimistis.
- Aplikasi klien mengajukan permintaan
- Menghapus kontak
- Aplikasi klien menghapus kontak dengan mengeluarkan permintaan
DELETE
terhadap URI kontak.
- Aplikasi klien menghapus kontak dengan mengeluarkan permintaan