Halaman ini diterjemahkan oleh Cloud Translation API.

Notifikasi push

Dokumen ini menjelaskan cara menggunakan notifikasi push yang menginformasikan aplikasi Anda saat resource berubah.

Ringkasan

Google Calendar API menyediakan notifikasi push yang memungkinkan Anda memantau perubahan fasilitas. Anda dapat menggunakan fitur ini untuk meningkatkan performa aplikasi. Cara ini memungkinkan Anda menghilangkan jaringan ekstra dan biaya komputasi yang terkait dengan resource polling untuk menentukan apakah resource tersebut telah berubah. Setiap kali fasilitas yang dipantau berubah, Google Calendar API akan memberi tahu aplikasi Anda.

Untuk menggunakan notifikasi push, Anda harus melakukan dua hal:

Siapkan URL penerima atau penerima callback "webhook".
Ini adalah server HTTPS yang menangani pesan notifikasi API yang dipicu saat resource berubah.
Siapkan saluran notifikasi untuk setiap endpoint resource yang ingin Anda tonton.
Saluran menentukan informasi perutean untuk pesan notifikasi. Sebagai bagian dari penyiapan saluran, Anda harus mengidentifikasi URL spesifik tempat Anda ingin menerima notifikasi. Setiap kali resource saluran berubah, Google Calendar API akan mengirimkan pesan notifikasi sebagai permintaan POST ke URL tersebut.

Saat ini, Google Calendar API mendukung notifikasi untuk perubahan pada resource Acl, CalendarList, Events, dan Setelan.

Membuat saluran notifikasi

Untuk meminta notifikasi push, Anda harus menyiapkan saluran notifikasi untuk setiap resource yang ingin dipantau. Setelah saluran notifikasi disiapkan, Google Calendar API akan memberi tahu aplikasi Anda jika ada perubahan pada resource yang dipantau.

Membuat permintaan smartwatch

Setiap resource Google Calendar API yang dapat ditonton memiliki metode watch terkait di URI dengan bentuk berikut:

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

Untuk menyiapkan saluran notifikasi bagi pesan tentang perubahan pada resource tertentu, kirim permintaan POST ke metode watch untuk resource tersebut.

Setiap saluran notifikasi terkait dengan pengguna tertentu dan resource tertentu (atau serangkaian resource). Permintaan watch tidak akan berhasil kecuali pengguna saat ini memiliki atau memiliki izin untuk mengakses resource ini.

Contoh

Mulai pantau perubahan pada kumpulan acara di kalender tertentu:

POST https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events/watch
Authorization: Bearer auth_token_for_current_user
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myCalendarChannelDest", // (Optional) Your channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration time.
}

Properti wajib

Untuk setiap permintaan watch, Anda harus memberikan kolom berikut:

String properti id yang mengidentifikasi saluran notifikasi baru ini secara unik dalam project Anda. Sebaiknya gunakan ID unik universal (UUID) atau string unik yang serupa. Panjang maksimum: 64 karakter.

Nilai ID yang Anda tetapkan akan digemakan kembali di header HTTP X-Goog-Channel-Id di setiap pesan notifikasi yang Anda terima untuk saluran ini.
String properti type yang ditetapkan ke nilai web_hook.
String properti address yang ditetapkan ke URL yang memproses dan merespons notifikasi untuk saluran notifikasi ini. Ini adalah URL callback webhook Anda, dan harus menggunakan HTTPS.

Perhatikan bahwa Google Calendar API dapat mengirimkan notifikasi ke alamat HTTPS ini hanya jika ada sertifikat SSL valid yang terinstal di server web Anda. Sertifikat yang tidak valid mencakup:
- Sertifikat yang ditandatangani sendiri.
- Sertifikat yang ditandatangani oleh sumber tidak tepercaya.
- Sertifikat yang telah dicabut.
- Sertifikat yang memiliki subjek yang tidak cocok dengan nama host target.

Properti opsional

Anda juga dapat menentukan kolom opsional ini dengan permintaan watch:

Properti token yang menentukan nilai string arbitrer yang akan digunakan sebagai token saluran. Anda dapat menggunakan token saluran notifikasi untuk berbagai tujuan. Misalnya, Anda dapat menggunakan token tersebut untuk memverifikasi bahwa setiap pesan masuk ditujukan untuk saluran yang dibuat oleh aplikasi Anda—untuk memastikan bahwa notifikasi tidak di-spoofing—atau untuk mengarahkan pesan ke tujuan yang tepat dalam aplikasi berdasarkan tujuan saluran ini. Panjang maksimum: 256 karakter.
Token tersebut disertakan dalam header HTTP X-Goog-Channel-Token di setiap pesan notifikasi yang diterima aplikasi Anda untuk saluran ini.

Jika Anda menggunakan token saluran notifikasi, sebaiknya Anda:
- Gunakan format encoding yang dapat diperluas, seperti parameter kueri URL. Contoh: forwardTo=hr&createdBy=mobile
- Jangan sertakan data sensitif seperti token OAuth.
Catatan: Jika Anda harus mengirim data yang sangat sensitif, pastikan data tersebut dienkripsi sebelum menambahkannya ke token.
String properti expiration yang ditetapkan ke stempel waktu Unix (dalam milidetik) pada tanggal dan waktu saat Anda ingin Google Calendar API berhenti mengirim pesan untuk saluran notifikasi ini.

Jika saluran memiliki waktu habis masa berlaku, itu disertakan sebagai nilai header HTTP X-Goog-Channel-Expiration (dalam format yang dapat dibaca manusia) dalam setiap pesan notifikasi yang diterima aplikasi Anda untuk saluran ini.

Untuk detail selengkapnya tentang permintaan, lihat metode watch untuk resource Acl, CalendarList, Events, dan Setelan di Referensi API.

Lihat respons

Jika permintaan watch berhasil membuat saluran notifikasi, permintaan ini akan menampilkan kode status HTTP 200 OK.

Isi pesan respons jam menyediakan informasi tentang saluran notifikasi yang baru saja Anda buat, seperti yang ditunjukkan pada contoh di bawah ini.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events", // Version-specific ID of the watched resource.
  "token": "target=myApp-myCalendarChannelDest", // Present only if one was provided.
  "expiration": 1426325213000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

Selain properti yang Anda kirim sebagai bagian dari permintaan, informasi yang ditampilkan juga mencakup resourceId dan resourceUri untuk mengidentifikasi resource yang sedang dipantau di saluran notifikasi ini.

Catatan: Properti resourceId adalah ID stabil dan tidak bergantung pada versi untuk resource tersebut. Properti resourceUri adalah URI kanonis dari resource yang ditonton dalam konteks versi API saat ini, sehingga berlaku khusus untuk versi.

Anda dapat meneruskan informasi yang ditampilkan ke operasi saluran notifikasi lainnya, seperti saat Anda ingin berhenti menerima notifikasi.

Untuk detail selengkapnya tentang respons, lihat metode watch untuk resource Acl, CalendarList, Events, dan Setelan di Referensi API.

Sinkronkan pesan

Setelah membuat saluran notifikasi untuk menonton resource, Google Calendar API akan mengirimkan pesan sync untuk menunjukkan bahwa notifikasi dimulai. Nilai header HTTP X-Goog-Resource-State untuk pesan ini adalah sync. Karena masalah pengaturan waktu jaringan, Anda dapat menerima pesan sync bahkan sebelum Anda menerima respons metode watch.

Anda dapat mengabaikan notifikasi sync, tetapi Anda juga dapat menggunakannya. Misalnya, jika Anda memutuskan tidak ingin mempertahankan saluran, Anda dapat menggunakan nilai X-Goog-Channel-ID dan X-Goog-Resource-ID dalam panggilan untuk berhenti menerima notifikasi. Anda juga dapat menggunakan notifikasi sync untuk melakukan beberapa inisialisasi guna mempersiapkan peristiwa berikutnya.

Format pesan sync yang dikirim Google Calendar API ke URL penerima ditampilkan di bawah ini.

POST https://mydomain.com/notifications // Your receiving URL.
X-Goog-Channel-ID: channel-ID-value
X-Goog-Channel-Token: channel-token-value
X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires.
X-Goog-Resource-ID: identifier-for-the-watched-resource
X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource
X-Goog-Resource-State: sync
X-Goog-Message-Number: 1

Pesan sinkronisasi selalu memiliki nilai header HTTP X-Goog-Message-Number dari 1. Setiap notifikasi berikutnya untuk saluran ini memiliki nomor pesan yang lebih besar dari notifikasi sebelumnya, meskipun nomor pesan tidak akan berurutan.

Memperpanjang saluran notifikasi

Saluran notifikasi dapat memiliki waktu habis masa berlaku, dengan nilai yang ditentukan oleh permintaan Anda atau oleh batas internal Google Calendar API atau default (nilai yang lebih ketat digunakan). Waktu habis masa berlaku saluran, jika ada, disertakan sebagai stempel waktu Unix (dalam milidetik) dalam informasi yang ditampilkan oleh metode watch. Selain itu, tanggal dan waktu habis masa berlaku disertakan (dalam format yang dapat dibaca manusia) di setiap pesan notifikasi yang diterima aplikasi Anda untuk saluran ini di header HTTP X-Goog-Channel-Expiration.

Saat ini, tidak ada cara otomatis untuk memperpanjang saluran notifikasi. Jika suatu saluran mendekati masa berlakunya, Anda harus menggantinya dengan yang baru dengan memanggil metode watch. Seperti biasa, Anda harus menggunakan nilai unik untuk properti id saluran baru. Perhatikan bahwa ada kemungkinan periode waktu "tumpang-tindih" saat dua saluran notifikasi untuk resource yang sama aktif.

Terima notifikasi

Setiap kali resource yang dipantau berubah, aplikasi Anda akan menerima pesan notifikasi yang menjelaskan perubahan tersebut. Google Calendar API mengirimkan pesan ini sebagai permintaan POST HTTPS ke URL yang Anda tentukan sebagai properti address untuk saluran notifikasi ini.

Catatan: Permintaan HTTPS pengiriman notifikasi menentukan agen pengguna APIs-Google dan mematuhi perintah robots.txt, seperti yang dijelaskan dalam Agen Pengguna Google API.

Menafsirkan format pesan notifikasi

Semua pesan notifikasi menyertakan sekumpulan header HTTP yang memiliki awalan X-Goog-. Beberapa jenis notifikasi juga dapat menyertakan isi pesan.

Header

Pesan notifikasi yang diposting oleh Google Calendar API ke URL penerima Anda mencakup header HTTP berikut:

Header	Deskripsi
Selalu ada
`X-Goog-Channel-ID`	UUID atau string unik lainnya yang Anda berikan untuk mengidentifikasi saluran notifikasi ini.
`X-Goog-Message-Number`	Bilangan bulat yang mengidentifikasi pesan ini untuk saluran notifikasi ini. Nilainya selalu `1` untuk `sync` pesan. Jumlah pesan meningkat untuk setiap pesan berikutnya di saluran, tetapi tidak berurutan.
`X-Goog-Resource-ID`	Nilai buram yang mengidentifikasi resource yang dipantau. ID ini stabil di seluruh versi API.
`X-Goog-Resource-State`	Status resource baru yang memicu notifikasi. Nilai yang mungkin: `sync`, `exists`, atau `not_exists`.
`X-Goog-Resource-URI`	ID khusus versi API untuk resource yang dipantau.
Terkadang hadir
`X-Goog-Channel-Expiration`	Tanggal dan waktu berakhirnya saluran notifikasi, yang dinyatakan dalam format yang dapat dibaca manusia. Hanya ada jika ditentukan.
`X-Goog-Channel-Token`	Token saluran notifikasi yang ditetapkan oleh aplikasi, dan yang dapat Anda gunakan untuk memverifikasi sumber notifikasi. Hanya ada jika ditentukan.

Pesan notifikasi yang diposting oleh Google Calendar API ke URL penerima tidak menyertakan isi pesan. Pesan ini tidak berisi informasi spesifik tentang resource yang diperbarui, Anda harus melakukan panggilan API lagi untuk melihat detail perubahan lengkap.

Contoh

Mengubah pesan notifikasi untuk pengumpulan peristiwa yang diubah:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events
X-Goog-Resource-State:  exists
X-Goog-Message-Number: 10

Menanggapi pemberitahuan

Untuk menunjukkan keberhasilan, Anda dapat menampilkan salah satu kode status berikut: 200, 201, 202, 204, atau 102.

Jika layanan Anda menggunakan library klien API Google dan menampilkan 500,502, 503, atau 504, Google Calendar API akan mencoba lagi dengan backoff eksponensial. Setiap kode status pengembalian lainnya akan dianggap sebagai kegagalan pesan.

Memahami peristiwa notifikasi Google Calendar API

Bagian ini memberikan detail tentang pesan notifikasi yang dapat Anda terima saat menggunakan notifikasi push dengan Google Calendar API.

X-Goog-Resource-State	Berlaku untuk	Dikirim saat
`sync`	ACL, Daftar kalender, Acara, Setelan.	Channel baru berhasil dibuat. Anda akan mulai menerima notifikasi untuk hal tersebut.
`exists`	ACL, Daftar kalender, Acara, Setelan.	Terjadi perubahan pada resource. Perubahan yang memungkinkan mencakup pembuatan resource baru, atau modifikasi atau penghapusan resource yang ada.

Menghentikan notifikasi

Properti expiration mengontrol kapan notifikasi berhenti secara otomatis. Anda dapat memilih untuk berhenti menerima notifikasi saluran tertentu sebelum habis masa berlakunya dengan memanggil metode stop di URI berikut:

https://www.googleapis.com/calendar/v3/channels/stop

Metode ini mengharuskan Anda menyediakan setidaknya id dan properti resourceId saluran, seperti ditunjukkan pada contoh di bawah ini. Perhatikan bahwa jika Google Calendar API memiliki beberapa jenis fasilitas yang memiliki metode watch, hanya ada satu metode stop.

Hanya pengguna dengan izin yang tepat yang dapat menghentikan channel. Khususnya:

Jika channel dibuat oleh akun pengguna reguler, hanya pengguna yang sama dari klien yang sama (seperti yang diidentifikasi oleh client ID OAuth 2.0 dari token autentikasi) yang membuat channel tersebut yang dapat menghentikan saluran.
Jika saluran dibuat oleh akun layanan, setiap pengguna dari klien yang sama dapat menghentikan saluran tersebut.

Contoh kode berikut menunjukkan cara berhenti menerima notifikasi:

POST https://www.googleapis.com/calendar/v3/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}

Pertimbangan khusus

Saat menggunakan notifikasi push, perhatikan hal berikut:

Acara dan ACL adalah per kalender Jika Anda ingin mendapatkan notifikasi tentang semua perubahan acara atau ACL untuk kalender A dan B, Anda harus berlangganan koleksi acara/ACL secara terpisah untuk A dan untuk B.

Setelan dan daftar kalender tersedia per pengguna Setelan dan daftar kalender hanya memiliki satu koleksi per pengguna, sehingga Anda hanya dapat berlangganan sekali.

Selain itu, Anda tidak akan mendapatkan notifikasi saat mendapatkan akses ke koleksi baru (misalnya, kalender baru), meskipun Anda akan diberi tahu jika kalender tersebut ditambahkan ke daftar kalender (dengan asumsi Anda berlangganan koleksi daftar kalender).

Notifikasi tidak 100% andal. Sejumlah kecil pesan mungkin akan dihapus dalam kondisi kerja normal. Pastikan untuk menangani pesan yang hilang ini dengan baik, sehingga aplikasi tetap disinkronkan meskipun tidak ada pesan push yang diterima.