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 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:

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.

  1. Kepala sekolah
    • https://www.googleapis.com/carddav/v1/principals/userEmail
  2. Home Set
    • 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 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.