Dokumen ini menjelaskan cara menggunakan notifikasi push yang memberi tahu aplikasi Anda saat resource berubah.
Ringkasan
Google Drive API menyediakan notifikasi push yang dapat Anda gunakan untuk memantau perubahan resource. Anda dapat menggunakan fitur ini untuk meningkatkan performa aplikasi. Ini memungkinkan Anda menghilangkan jaringan tambahan dan biaya komputasi yang terlibat dalam polling resource untuk menentukan apakah resource tersebut telah berubah. Setiap kali resource yang dipantau berubah, Google Drive 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 Drive API akan mengirimkan pesan notifikasi sebagai permintaan
POST
ke URL tersebut.
Saat ini, Google Drive API mendukung notifikasi untuk perubahan pada metode files
dan changes
.
Membuat saluran notifikasi
Untuk meminta notifikasi push, Anda harus menyiapkan saluran notifikasi untuk setiap resource yang ingin dipantau. Setelah saluran notifikasi Anda disiapkan, Google Drive API akan memberi tahu aplikasi Anda jika ada perubahan resource yang dipantau.
Membuat permintaan smartwatch
Setiap resource Google Drive API yang dapat dipantau memiliki metode
watch
terkait pada URI dengan bentuk berikut:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
Untuk menyiapkan saluran notifikasi pesan tentang perubahan pada
resource tertentu, kirim permintaan POST
ke
metode watch
untuk resource tersebut.
Setiap saluran notifikasi terkait dengan pengguna tertentu dan resource (atau kumpulan resource) tertentu. Permintaan watch
tidak akan berhasil kecuali jika pengguna saat ini atau akun layanan memiliki atau memiliki izin untuk mengakses resource ini.
Contoh
Contoh kode berikut menunjukkan cara menggunakan resource channels
untuk mulai memantau perubahan pada satu resource files
menggunakan metode files.watch
:
POST https://www.googleapis.com/drive/v3/files/fileId/watch Authorization: Bearer CURRENT_USER_AUTH_TOKEN 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-myFilesChannelDest", // (Optional) Your files channel token. "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time. }
Contoh kode berikut menunjukkan cara menggunakan resource channels
untuk mulai memantau semua changes
menggunakan metode changes.watch
:
POST https://www.googleapis.com/drive/v3/changes/watch Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a77", // Your channel ID. "type": "web_hook", "address": "https://mydomain.com/notifications", // Your receiving URL. ... "token": "target=myApp-myChangesChannelDest", // (Optional) Your changes channel token. "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time. }
Properti wajib
Dengan setiap permintaan watch
, Anda harus menyediakan kolom berikut:
-
String properti
id
yang mengidentifikasi secara unik saluran notifikasi baru ini dalam project Anda. Sebaiknya gunakan ID unik universal (UUID) atau string unik yang serupa. Panjang maksimum: 64 karakter.Nilai ID yang Anda tetapkan akan dipantulkan kembali di header HTTP
X-Goog-Channel-Id
pada setiap pesan notifikasi 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 harus menggunakan HTTPS.Perhatikan bahwa Google Drive API dapat mengirim notifikasi ke alamat HTTPS ini hanya jika ada sertifikat SSL valid yang diinstal 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 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 ini untuk memverifikasi bahwa setiap pesan masuk ditujukan untuk saluran yang dibuat 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.
-
String properti
expiration
disetel ke stempel waktu Unix (dalam milidetik) dari tanggal dan waktu saat Anda ingin Google Drive API berhenti mengirim pesan untuk saluran notifikasi ini.Jika saluran memiliki waktu habis masa berlaku, saluran tersebut akan 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 metode files
dan changes
dalam Referensi API.
Tonton respons
Jika permintaan watch
berhasil membuat saluran notifikasi, permintaan akan menampilkan kode status HTTP 200 OK
.
Isi pesan respons watch memberikan informasi tentang saluran notifikasi yang baru saja Anda buat, seperti 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/drive/v3/files/o3hgv1538sdjfh", // Version-specific ID of the watched resource. "token": "target=myApp-myFilesChannelDest", // Present only if one was provided. "expiration": 1426325213000, // Actual expiration date and time as UNIX timestamp (in milliseconds), if applicable. }
Selain properti yang Anda kirim sebagai bagian dari permintaan, informasi yang ditampilkan juga menyertakan resourceId
dan resourceUri
untuk mengidentifikasi resource yang sedang dipantau di saluran notifikasi ini.
Anda dapat meneruskan informasi yang ditampilkan ke operasi saluran notifikasi lainnya, seperti waktu Anda ingin berhenti menerima notifikasi.
Untuk detail selengkapnya tentang respons, lihat metode watch
untuk metode files
dan changes
dalam Referensi API.
Sinkronkan pesan
Setelah membuat saluran notifikasi untuk melihat resource, Google Drive API akan mengirimkan pesan sync
untuk menunjukkan bahwa
notifikasi dimulai. Nilai header HTTP X-Goog-Resource-State
untuk pesan ini adalah sync
. Karena masalah waktu
jaringan, pesan sync
mungkin saja diterima
bahkan sebelum Anda menerima respons metode watch
.
Anda dapat mengabaikan notifikasi sync
, tetapi Anda juga dapat
menggunakannya. Misalnya, jika memutuskan bahwa Anda 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 selanjutnya.
Format pesan sync
yang dikirim Google Drive API ke
URL penerima Anda ditampilkan di bawah.
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
sebesar 1
. Tiap notifikasi berikutnya untuk saluran ini memiliki nomor pesan yang lebih besar dari yang 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 batas internal atau default Google Drive API (nilai yang lebih ketat digunakan). Waktu habis masa berlaku channel, jika ada, akan 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. Ketika
saluran hampir habis masa berlakunya, Anda harus menggantinya dengan yang baru dengan memanggil
metode watch
. Seperti biasa, Anda harus menggunakan nilai unik untuk properti id
saluran baru. Perlu diperhatikan bahwa kemungkinan
akan ada periode waktu yang "tumpang-tindih" saat dua saluran notifikasi untuk
resource yang sama aktif.
Menerima notifikasi
Setiap kali resource yang dipantau berubah, aplikasi Anda akan menerima pesan notifikasi yang menjelaskan perubahan tersebut. Google Drive API mengirimkan
pesan ini sebagai permintaan POST
HTTPS ke URL yang Anda tentukan sebagai
properti address
untuk saluran
notifikasi ini.
Menafsirkan format pesan notifikasi
Semua pesan notifikasi menyertakan kumpulan header HTTP yang memiliki awalan X-Goog-
.
Beberapa jenis notifikasi juga dapat menyertakan
isi pesan.
Header
Pesan notifikasi yang diposting oleh Google Drive API ke URL penerima Anda menyertakan header HTTP berikut:
Header | Deskripsi |
---|---|
Selalu presentasikan | |
|
UUID atau string unik lainnya yang Anda berikan untuk mengidentifikasi saluran notifikasi ini. |
|
Bilangan bulat yang mengidentifikasi pesan ini untuk saluran notifikasi
ini. Nilai selalu 1 untuk pesan sync . Jumlah pesan meningkat untuk setiap pesan berikutnya di saluran, tetapi tidak berurutan. |
|
Nilai buram yang mengidentifikasi resource yang ditonton. ID ini stabil di seluruh versi API. |
|
Status resource baru yang memicu notifikasi.
Nilai yang mungkin:
sync , add , remove , update ,
trash , untrash , atau change
.
|
|
ID khusus versi API untuk resource yang ditonton. |
Terkadang ada | |
|
Detail tambahan tentang perubahan tersebut.
Nilai yang mungkin:
content ,
parents ,
children , atau
permissions
.
Tidak disertakan dengan sync pesan. |
|
Tanggal dan waktu habis masa berlaku saluran notifikasi, yang dinyatakan dalam format yang 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 ditentukan. |
Pesan notifikasi untuk files
dan changes
kosong.
Contoh
Ubah pesan notifikasi untuk resource files
, yang tidak termasuk isi permintaan:
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/drive/v3/files/ret08u3rv24htgh289g X-Goog-Resource-State: update X-Goog-Changed: content,properties X-Goog-Message-Number: 10
Ubah pesan notifikasi untuk resource changes
, yang mencakup isi permintaan:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 118 X-Goog-Channel-ID: 8bd90be9-3a58-3122-ab43-9823188a5b43 X-Goog-Channel-Token: 245t1234tt83trrt333 X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT X-Goog-Resource-ID: ret987df98743md8g X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/changes X-Goog-Resource-State: changed X-Goog-Message-Number: 23 { "kind": "drive#changes" }
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 Drive API
akan mencoba kembali dengan backoff eksponensial.
Setiap kode status pengembalian lainnya dianggap sebagai kegagalan pesan.
Memahami peristiwa notifikasi Google Drive API
Bagian ini menjelaskan detail tentang pesan notifikasi yang dapat Anda terima saat menggunakan notifikasi push dengan Google Drive API.
Dikirim saat | ||
---|---|---|
sync |
files , changes |
Channel berhasil dibuat. Anda akan mulai menerima notifikasi untuknya. |
add |
files |
Referensi telah dibuat atau dibagikan. |
|
files |
Referensi yang ada telah dihapus atau tidak dibagikan. |
|
files |
Satu atau beberapa properti (metadata) resource telah diupdate. |
|
files |
Referensi telah dipindahkan ke sampah. |
|
files |
Referensi telah dihapus dari sampah. |
|
changes |
Satu atau beberapa item log perubahan telah ditambahkan. |
Untuk peristiwa update
, header HTTP X-Goog-Changed
mungkin akan disediakan. {i>Header<i} tersebut berisi daftar yang dipisahkan koma yang menjelaskan jenis perubahan yang telah terjadi.
Ubah jenis | Menunjukkan |
---|---|
content |
Konten referensi telah diperbarui. |
properties |
Satu atau beberapa properti resource telah diperbarui. |
parents |
Satu atau beberapa resource induk telah ditambahkan atau dihapus. |
children |
Satu atau beberapa turunan resource telah ditambahkan atau dihapus. |
permissions |
Izin resource telah diperbarui. |
Contoh dengan header X-Goog-Changed
:
X-Goog-Resource-State: update X-Goog-Changed: content, permissions
Menghentikan notifikasi
Properti expiration
mengontrol kapan notifikasi berhenti secara otomatis. Anda dapat memilih untuk berhenti menerima notifikasi untuk saluran tertentu sebelum masa berlakunya habis dengan memanggil metode stop
di URI berikut:
https://www.googleapis.com/drive/v3/channels/stop
Metode ini mengharuskan Anda menyediakan setidaknya id
dan properti resourceId
saluran, seperti ditunjukkan dalam contoh di bawah. Perhatikan bahwa jika Google Drive API memiliki beberapa jenis
resource yang memiliki metode watch
, hanya ada satu
metode stop
.
Hanya pengguna dengan izin yang tepat yang dapat menghentikan channel. Pada khususnya:
- Jika channel dibuat oleh akun pengguna biasa, hanya pengguna yang sama dari klien yang sama (seperti yang diidentifikasi oleh client ID OAuth 2.0 dari token autentikasi) yang membuat channel yang dapat menghentikan channel tersebut.
- 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/drive/v3/channels/stop Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66", "resourceId": "ret08u3rv24htgh289g" }