Dokumen ini menjelaskan cara menggunakan notifikasi push yang memberi tahu saat resource berubah.
Ringkasan
Google Calendar API menyediakan notifikasi push yang memungkinkan Anda memantau perubahan resource. Anda dapat menggunakan fitur ini untuk meningkatkan performa aplikasi Anda. Dengan cara ini, Anda dapat menghilangkan jaringan dan komputasi tambahan biaya yang terkait dengan sumber daya polling untuk menentukan apakah sumber daya tersebut telah berubah. Setiap kali sumber daya yang diawasi berubah, Google Calendar API akan memberi tahu aplikasi.
Untuk menggunakan notifikasi push, Anda harus melakukan dua hal:
Siapkan URL penerima atau "webhook" Anda penerima callback.
Ini adalah server HTTPS yang menangani pesan notifikasi API yang dipicu saat sumber daya berubah.
Siapkan (saluran notifikasi) untuk setiap endpoint resource yang ingin smartwatch.
Saluran menentukan informasi pemilihan rute untuk notifikasi membuat pesan teks. Sebagai bagian dari penyiapan saluran, Anda harus mengidentifikasi URL spesifik yang Anda inginkan untuk menerima notifikasi. Setiap kali sumber daya saluran berubah, Google Calendar API mengirim pesan notifikasi sebagai
POST
ke URL tersebut.
Saat ini, Google Calendar API mendukung notifikasi untuk perubahan pada resource Acl, CalendarList, Events, dan Settings.
Membuat saluran notifikasi
Untuk meminta notifikasi push, Anda harus menyiapkan saluran notifikasi untuk setiap sumber daya yang ingin Anda pantau. Setelah saluran notifikasi Anda ditetapkan ke atas, Google Calendar API akan memberi tahu aplikasi Anda saat ada sumber daya yang dipantau perubahan.
Membuat permintaan smartwatch
Setiap resource Google Calendar API yang dapat ditonton memiliki
Metode watch
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
ke resource tertentu, kirim permintaan POST
ke
Metode watch
untuk resource.
Setiap saluran notifikasi dikaitkan
dengan pengguna tertentu dan
sumber daya tertentu (atau serangkaian sumber daya). Permintaan watch
tidak akan berhasil kecuali
pengguna saat ini
memiliki atau memiliki izin untuk mengakses resource ini.
Contoh
Mulailah memperhatikan perubahan pada koleksi acara di kalender tertentu:
POST https://www.googleapis.com/calendar/v3/calendars/[email protected]/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
Dengan setiap permintaan watch
, Anda harus menyediakan kolom berikut:
-
String properti
id
yang mengidentifikasi hal ini secara unik saluran notifikasi baru dalam project Anda. Sebaiknya gunakan ID unik universal, (UUID) atau platform sejenis string unik. Panjang maksimum: 64 karakter.Nilai ID yang Anda tetapkan akan dipantulkan kembali di
X-Goog-Channel-Id
header HTTP setiap notifikasi pesan yang Anda terima untuk saluran ini. -
String properti
type
yang ditetapkan ke nilaiweb_hook
. -
String properti
address
yang ditetapkan ke URL yang memproses dan merespons notifikasi untuk saluran notifikasi ini. Ini adalah URL callback webhook Anda, dan URL tersebut harus menggunakan HTTPS.Perhatikan bahwa Google Calendar API dapat mengirim notifikasi ke alamat HTTPS ini hanya jika ada sertifikat SSL yang valid 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 sesuai dengan target nama host.
Properti opsional
Anda juga dapat menentukan kolom opsional ini dengan
Permintaan watch
:
-
Properti
token
yang menentukan string arbitrer untuk digunakan sebagai token channel. Anda dapat menggunakan saluran notifikasi token untuk berbagai tujuan. Misalnya, Anda dapat menggunakan token untuk memverifikasi bahwa setiap pesan masuk ditujukan untuk saluran yang aplikasi dibuat—untuk memastikan bahwa notifikasi tidak dipalsukan—atau mengarahkan pesan ke tujuan yang benar dalam aplikasi Anda berdasarkan tujuan saluran ini. Panjang maksimum: 256 karakter.Token tersebut disertakan dalam
X-Goog-Channel-Token
header HTTP di setiap notifikasi yang diterima aplikasi Anda untuk saluran ini.Jika Anda menggunakan token saluran notifikasi, sebaiknya Anda:
Gunakan format encoding yang dapat diperluas, seperti kueri URL parameter. Contoh:
forwardTo=hr&createdBy=mobile
Jangan sertakan data sensitif seperti token OAuth.
-
String properti
expiration
yang disetel ke Stempel waktu Unix (dalam milidetik) tanggal dan waktu saat Google Calendar API ingin diaktifkan berhenti mengirim pesan untuk saluran notifikasi ini.Jika saluran memiliki masa berlaku, nilai tersebut akan disertakan sebagai nilai dari header HTTP
X-Goog-Channel-Expiration
(dalam format ) di setiap pesan notifikasi yang yang diterima aplikasi untuk saluran ini.
Untuk mengetahui detail selengkapnya tentang permintaan, lihat metode watch
untuk resource Acl, CalendarList, Events, dan Settings dalam Referensi API.
Tonton respons
Jika permintaan watch
berhasil membuat notifikasi
, maka akan menghasilkan
kode status HTTP 200 OK
.
Isi pesan respons watch memberikan informasi tentang saluran notifikasi yang baru saja Anda buat, seperti yang ditunjukkan dalam 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/[email protected]/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 Anda,
informasi yang ditampilkan juga mencakup resourceId
dan
resourceUri
untuk mengidentifikasi resource yang sedang ditonton di
saluran notifikasi.
Anda dapat meneruskan informasi yang ditampilkan ke saluran notifikasi lain seperti ketika Anda ingin berhenti menerima notifikasi.
Untuk detail selengkapnya tentang respons, lihat watch
untuk resource Acl, CalendarList, Events, dan Settings dalam Referensi API.
Sinkronkan pesan
Setelah membuat saluran notifikasi untuk melihat resource,
Google Calendar API mengirim pesan sync
untuk menunjukkan bahwa
notifikasi dimulai. HTTP X-Goog-Resource-State
nilai header untuk pesan ini adalah sync
. Karena jaringan
masalah waktu, pesan sync
mungkin akan diterima
bahkan sebelum Anda menerima respons metode watch
.
Anda dapat mengabaikan notifikasi sync
, tetapi Anda dapat melakukannya
Anda juga bisa menggunakannya. Misalnya, jika Anda memutuskan
tidak ingin menyimpan
Anda dapat menggunakan X-Goog-Channel-ID
dan
X-Goog-Resource-ID
nilai dalam panggilan ke
berhenti menerima notifikasi. Anda juga dapat menggunakan
sync
notifikasi untuk melakukan inisialisasi untuk mempersiapkan
acara selanjutnya.
Format pesan sync
yang dikirim Google Calendar API
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 HTTP X-Goog-Message-Number
nilai header 1
. Setiap notifikasi berikutnya untuk saluran ini memiliki
nomor pesan yang lebih besar dari yang sebelumnya, meskipun
angka tidak akan berurutan.
Memperpanjang saluran notifikasi
Saluran notifikasi bisa memiliki waktu habis masa berlaku, dengan nilai
ditentukan oleh permintaan Anda atau batas internal Google Calendar API
atau default (nilai yang lebih ketat digunakan). Masa berlaku channel
waktu, jika ada, akan disertakan sebagai stempel waktu Unix
(dalam milidetik) dalam informasi yang ditampilkan oleh metode watch
. Selain itu,
tanggal dan waktu kedaluwarsa disertakan (dalam format yang dapat dibaca manusia) di setiap
pesan notifikasi yang diterima aplikasi Anda untuk saluran ini dalam
Header HTTP X-Goog-Channel-Expiration
.
Saat ini tidak ada cara otomatis untuk memperpanjang saluran notifikasi. Kapan
saluran akan kedaluwarsa, Anda harus menggantinya dengan yang baru dengan memanggil
metode watch
. Seperti biasa, Anda harus
menggunakan nilai yang unik untuk
properti id
saluran baru. Perhatikan bahwa kemungkinan
menjadi "tumpang-tindih" periode waktu saat kedua saluran notifikasi untuk
resource yang sama.
Menerima notifikasi
Setiap kali sumber daya yang diawasi berubah, aplikasi akan menerima
pesan notifikasi yang menjelaskan perubahan tersebut. Google Calendar API akan mengirim
pesan sebagai permintaan HTTPS POST
ke URL yang Anda tentukan sebagai
Properti address
untuk notifikasi ini
saluran TV Anda.
Menafsirkan format pesan notifikasi
Semua pesan notifikasi mencakup 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 penerima Anda URL mencakup header HTTP berikut:
Header | Deskripsi |
---|---|
Selalu presentasikan | |
|
UUID atau string unik lainnya yang Anda berikan untuk mengidentifikasi hal ini saluran notifikasi. |
|
Bilangan bulat yang mengidentifikasi pesan ini untuk notifikasi ini
saluran TV Anda. Nilai selalu 1 untuk pesan sync . Kirim pesan
jumlahnya meningkat untuk setiap pesan berikutnya di saluran, tetapi
tidak berurutan. |
|
Nilai buram yang mengidentifikasi resource yang ditonton. ID ini adalah stabil di seluruh versi API. |
|
Status resource baru yang memicu notifikasi.
Nilai yang mungkin:
sync , exists , atau
not_exists .
|
|
ID khusus versi API untuk resource yang ditonton. |
Terkadang ada | |
|
Tanggal dan waktu habis masa berlaku saluran notifikasi, yang dinyatakan dalam dapat dibaca manusia. Hanya ada jika ditentukan. |
|
Token saluran notifikasi yang ditetapkan oleh aplikasi Anda, dan yang dapat Anda gunakan untuk memverifikasi sumber notifikasi. Hanya ada jika didefinisikan. |
Pesan notifikasi yang diposting oleh Google Calendar API ke URL penerima Anda tidak menyertakan isi pesan. Pesan ini tidak berisi informasi khusus tentang resource yang diupdate, Anda perlu melakukan panggilan API lain untuk melihat detail perubahan lengkap.
Contoh
Mengubah pesan notifikasi untuk kumpulan 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/[email protected]/events X-Goog-Resource-State: exists X-Goog-Message-Number: 10
Menanggapi pemberitahuan
Untuk menunjukkan keberhasilan, Anda dapat mengembalikan 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
percobaan ulang dengan backoff eksponensial.
Setiap kode status pengembalian lainnya dianggap sebagai kegagalan pesan.
Memahami peristiwa notifikasi Google Calendar API
Bagian ini menjelaskan secara detail tentang pesan notifikasi yang dapat terima saat menggunakan notifikasi push dengan Google Calendar API.
Dikirim saat | ||
---|---|---|
sync |
ACL, Daftar kalender, Acara, Setelan. | Channel baru berhasil dibuat. Anda akan mulai menerima notifikasi untuk itu. |
exists |
ACL, Daftar kalender, Acara, Setelan. | Terjadi perubahan pada resource. Perubahan yang mungkin terjadi mencakup pembuatan resource baru, atau modifikasi atau penghapusan resource yang ada. |
Hentikan notifikasi
Properti expiration
mengontrol kapan notifikasi berhenti secara otomatis. Anda dapat
memilih untuk berhenti menerima notifikasi untuk channel tertentu sebelum channel tersebut
berakhir dengan memanggil metode stop
pada
URI berikut:
https://www.googleapis.com/calendar/v3/channels/stop
Metode ini mengharuskan Anda menyediakan setidaknya
id
dan properti resourceId
, seperti yang ditunjukkan dalam
contoh di bawah ini. Perhatikan bahwa jika Google Calendar API memiliki beberapa jenis
resource 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 biasa, hanya akun yang sama dari klien yang sama (seperti yang diidentifikasi oleh ID klien OAuth 2.0 dari token autentikasi) yang membuat channel dapat menghentikan channel tersebut.
- Jika saluran dibuat oleh akun layanan, setiap pengguna dari klien 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" }