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 dapat menggunakan CardDAV API untuk membuat kontak baru, mengedit atau menghapus kontak yang ada, dan mengajukan kueri kontak yang cocok dengan kriteria tertentu.
Spesifikasi
Spesifikasi lengkap tidak diterapkan, tetapi banyak klien seperti Apple iOSTM Contacts 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 Dataproc ke Pembuatan Versi dan Penulisan Versi Web (WebDAV)
- Mendukung metode HTTP
REPORT
, tetapi tidak semua laporan yang ditentukan diterapkan. - Mendukung penyediaan koleksi utama dan koleksi 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 Autentikasi HTTP OAuth 2.0. Google tidak mendukung metode autentikasi lainnya. Demi keamanan data kontak, kami memerlukan koneksi CardDAV untuk menggunakan HTTPS.
- rfc6764: Menemukan Layanan untuk Ekstensi Kalender ke WebDAV (CalDAV) dan Ekstensi VGT ke WebDAV (CardDAV)
- Bootstrap URL CardDAV harus dilakukan sesuai dengan bagian 6 rfc6764.
- Mendukung
caldav-ctag-02: Tag Calendar Collection Entity (CTag) di CalDAV,
yang digunakan bersama dengan spesifikasi CardDAV dan CalDAV. Kontak
ctag
seperti resourceETag
; yang berubah ketika sesuatu dalam buku alamat kontak telah berubah. Hal ini memungkinkan program klien untuk 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 dokumentasi tertaut di bawah untuk mendapatkan informasi tentang cara menggunakan OAuth 2.0 untuk mengakses Google API:
- Menggunakan OAuth 2.0 untuk Mengakses Google API
- Menggunakan OAuth 2.0 untuk Aplikasi yang Terinstal
Menghubungkan ke server CardDAV Google
Protokol CardDAV memungkinkan penemuan buku alamat dan URI resource kontak. Anda tidak boleh melakukan hardcode pada URI apa 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
mengautentikasi permintaan kecuali jika tiba melalui HTTPS dengan autentikasi
Akun Google OAuth 2.0, 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 ke jalur penemuan
kanonikal dengan melakukan PROPFIND
HTTP di:
https://www.googleapis.com/.well-known/carddav
Setelah dialihkan (HTTP 301
) ke Resource Buku Alamat, program klien Anda kemudian dapat melakukan PROPFIND
pada resource tersebut untuk menemukan properti DAV:current-user-principal
, DAV:principal-URL
, dan addressbook-home-set
. Program klien Anda kemudian dapat menemukan buku alamat utama dengan
melakukan PROPFIND
pada addressbook-home-set
dan mencari
resource addressbook
dan collection
. Deskripsi lengkap proses ini
berada di luar cakupan dokumen ini. Lihat
rfc6352 untuk detail selengkapnya.
Jalur pengalihan yang ditampilkan dalam respons HTTP 301
melalui PROPFIND
pada
URI yang sudah dikenal tidak boleh di-cache secara permanen (sesuai dengan
rfc6764). Perangkat harus mencoba kembali
penemuan URI yang terkenal secara berkala untuk memverifikasi apakah jalur yang di-cache masih terbaru dan
menyinkronkan ulang jika jalur pernah berubah. Google merekomendasikan tarif setiap 2-4 minggu.
Referensi
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. Struktur dapat berubah dan tidak boleh di-hardcode. Sebaliknya, resource 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 operasi yang didukung. Developer harus mencari detail dalam RFC yang relevan. Permintaan dan respons sebagian besar dienkode dalam XML. Ini adalah operasi utama yang digunakan oleh aplikasi klien untuk sinkronisasi:
- Menggunakan CTag
- Program klien menggunakan permintaan
getctag
PROPFIND
pada resource Buku Alamat untuk menentukan apakah ada kontak yang berubah di server, sehingga apakah sinkronisasi diperlukan. Nilai properti ini dijamin akan berubah jika ada kontak yang berubah. Aplikasi klien harus menyimpan nilai ini dan menggunakannya hanya pada sinkronisasi awal dan sebagai pengganti saatsync-token
menjadi tidak valid. Melakukan polling secara berkala untuk propertigetctag
akan menyebabkan throttling.
- Program klien menggunakan permintaan
- Menggunakan sync-token
- Program klien menggunakan permintaan
sync-token
PROPFIND
pada Buku Alamat untuk mendapatkansync-token
yang mewakili statusnya saat ini. Aplikasi klien harus menyimpan nilai ini dan mengeluarkansync-collection
permintaanREPORT
secara berkala untuk menentukan perubahan sejaksync-token
terakhir dikeluarkan. Token yang dikeluarkan berlaku selama 29 hari, dan responsREPORT
akan berisisync-token
baru.
- Program klien menggunakan permintaan
- Menggunakan ETag
- Aplikasi klien mengeluarkan permintaan
getetag
PROPFIND
pada resource Buku Alamat (dengan headerDEPTH
sama denganDEPTH_1
). Dengan mempertahankan nilaiETag
setiap kontak, program klien dapat meminta nilai kontak yangETag
-nya telah diubah.
- Aplikasi klien mengeluarkan permintaan
- Mengambil kontak
- Aplikasi klien mengambil kontak dengan mengeluarkan permintaan
addressbook-multiget
REPORT
. Dengan mempertimbangkan daftar URI kontak, laporan tersebut akan menampilkan semua kontak yang diminta sebagai nilai VCard 3.0. Setiap entri menyertakanETag
untuk kontak.
- Aplikasi klien mengambil kontak dengan mengeluarkan permintaan
- Menyisipkan kontak
- Aplikasi klien memberikan permintaan
POST
dengan kontak baru dalam format VCard 3.0. Respons akan berisi ID kontak baru.
- Aplikasi klien memberikan permintaan
- Memperbarui kontak
- Aplikasi klien mengeluarkan permintaan
PUT
dengan kontak yang diperbarui dalam format VCard 3.0. Kontak akan diperbarui jika kontak sudah ada di buku alamat. - Aplikasi klien harus menyertakan header
If-Match
denganETag
kontak yang saat ini diketahui. Server kemudian akan menolak permintaanPUT
(denganHTTP 412
) jikaETag
saat ini di server berbeda denganETag
yang dikirim oleh program klien. Hal ini memungkinkan serialisasi update yang optimis.
- Aplikasi klien mengeluarkan permintaan
- Menghapus kontak
- Aplikasi klien menghapus kontak dengan mengeluarkan permintaan
DELETE
pada URI kontak.
- Aplikasi klien menghapus kontak dengan mengeluarkan permintaan