Mengelola kontak dengan protokol CardDAV

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:

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:

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.

  1. Kepala Sekolah
    • https://www.googleapis.com/carddav/v1/principals/userEmail
  2. Set Rumah
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists
  3. Buku Alamat
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
  4. Kontak
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default/contactId

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 saat sync-token menjadi tidak valid. Melakukan polling secara berkala untuk properti getctag akan menyebabkan throttling.
  • Menggunakan sync-token
    • Program klien menggunakan permintaan sync-token PROPFIND pada Buku Alamat untuk mendapatkan sync-token yang mewakili statusnya saat ini. Aplikasi klien harus menyimpan nilai ini dan mengeluarkan sync-collection permintaan REPORT secara berkala untuk menentukan perubahan sejak sync-token terakhir dikeluarkan. Token yang dikeluarkan berlaku selama 29 hari, dan respons REPORT akan berisi sync-token baru.
  • Menggunakan ETag
    • Aplikasi klien mengeluarkan permintaan getetag PROPFIND pada resource Buku Alamat (dengan header DEPTH sama dengan DEPTH_1). Dengan mempertahankan nilai ETag 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 tersebut akan menampilkan semua kontak yang diminta sebagai nilai VCard 3.0. Setiap entri menyertakan ETag untuk kontak.
  • Menyisipkan kontak
    • Aplikasi klien memberikan permintaan POST dengan kontak baru dalam format VCard 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 sudah ada di buku alamat.
    • Aplikasi klien harus menyertakan header If-Match dengan ETag kontak yang saat ini diketahui. 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 pada URI kontak.