Notifikasi untuk perubahan sumber daya (original) (raw)

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

Ringkasan

Google Drive API menyediakan notifikasi push yang memungkinkan Anda memantau perubahan pada resource. Anda dapat menggunakan fitur ini untuk meningkatkan performa aplikasi Anda. Dengan demikian, Anda dapat menghilangkan biaya jaringan dan komputasi tambahan yang terkait dengan 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 pantau.
Saluran menentukan informasi perutean untuk pesan notifikasi. Sebagai bagian dari penyiapan channel, Anda harus mengidentifikasi URL tertentu tempat Anda ingin menerima notifikasi. Setiap kali resource channel 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 disiapkan, Google Drive API akan memberi tahu aplikasi Anda saat ada perubahan pada resource yang dipantau.

Membuat permintaan jam

Setiap resource Google Drive API yang dapat ditonton memiliki metodewatch terkait di URI dengan format berikut:

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

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

Setiap saluran notifikasi dikaitkan dengan pengguna tertentu dan resource tertentu (atau sekumpulan resource). 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 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 serupa. Panjang maksimum: 64 karakter.
Nilai ID yang Anda tetapkan akan dikembalikan di header HTTP X-Goog-Channel-Id dari 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 hanya dapat mengirim notifikasi ke alamat HTTPS ini jika ada sertifikat SSL yang 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 cocok dengan nama host target.

Properti opsional

Anda juga dapat menentukan kolom opsional ini dengan permintaanwatch:

Properti token yang menentukan nilai string arbitrer untuk digunakan sebagai token channel. Anda dapat menggunakan token channel notifikasi untuk berbagai tujuan. Misalnya, Anda dapat menggunakan token untuk memverifikasi bahwa setiap pesan masuk ditujukan untuk saluran yang dibuat oleh aplikasi Anda—untuk memastikan bahwa notifikasi tidak dipalsukan—atau untuk merutekan pesan ke tujuan yang tepat dalam aplikasi Anda berdasarkan tujuan saluran ini. Panjang maksimum: 256 karakter.
Token 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:
- Gunakan format encoding yang dapat di-extend, seperti parameter kueri URL. Contoh: forwardTo=hr&createdBy=mobile
- Jangan sertakan data sensitif seperti token OAuth.
String properti expiration yang ditetapkan kestempel waktu Unix (dalam milidetik) tanggal dan waktu saat Anda ingin Google Drive API berhenti mengirim pesan untuk saluran notifikasi ini.
Jika channel memiliki waktu habis masa berlaku, waktu tersebut disertakan sebagai nilai header HTTP X-Goog-Channel-Expiration (dalam format yang mudah dibaca) di setiap pesan notifikasi yang diterima aplikasi Anda untuk channel ini.

Untuk mengetahui detail permintaan selengkapnya, lihat metode watch untuk metode files dan changes dalam Referensi API.

Menonton respons

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

Isi pesan respons smartwatch memberikan informasi tentang saluran notifikasi yang baru saja Anda buat, seperti yang ditunjukkan dalam contoh di bawah.

{ "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 mencakup resourceId dan resourceUri untuk mengidentifikasi resource yang dipantau di saluran notifikasi ini.

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

Untuk mengetahui detail respons selengkapnya, lihat metode watch untuk metode files dan changes di Referensi API.

Pesan sinkronisasi

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

Anda dapat mengabaikan notifikasi sync dengan aman, tetapi Anda juga dapat menggunakannya. Misalnya, jika Anda memutuskan tidak ingin mempertahankan saluran, Anda dapat menggunakan nilai X-Goog-Channel-ID danX-Goog-Resource-ID dalam panggilan keberhenti menerima notifikasi. Anda juga dapat menggunakan notifikasisync untuk melakukan beberapa inisialisasi sebagai persiapan untuk peristiwa berikutnya.

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. Setiap notifikasi berikutnya untuk saluran ini memiliki nomor pesan yang lebih besar dari sebelumnya, meskipun nomor pesan tidak akan berurutan.

Memperbarui saluran notifikasi

Channel notifikasi dapat memiliki waktu habis masa berlaku, dengan nilai ditentukan oleh permintaan Anda atau oleh batas internal atau default Google Drive API (nilai yang lebih ketat yang digunakan). Waktu habis masa berlaku channel, 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 channel hampir berakhir, Anda harus menggantinya dengan channel baru dengan memanggil metode watch. Seperti biasa, Anda harus menggunakan nilai unik untuk properti id saluran baru. Perhatikan bahwa kemungkinan ada periode waktu "tumpang-tindih" saat dua saluran notifikasi untuk resource yang sama aktif.

Terima notifikasi

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

Menafsirkan format pesan notifikasi

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

Pesan notifikasi untuk files dan changes kosong.

Contoh

Pesan notifikasi perubahan untuk resource files, yang tidak menyertakan 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

Pesan notifikasi perubahan 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 lagi dengan penundaan eksponensial. Setiap kode status pengembalian lainnya dianggap sebagai kegagalan pesan.

Memahami peristiwa notifikasi Google Drive API

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

X-Goog-Resource-State	Berlaku untuk	Dikirimkan saat
sync	files, changes	Channel berhasil dibuat. Anda akan mulai menerima notifikasi untuknya.
add	files	Sumber daya dibuat atau dibagikan.
remove	files	Resource yang ada telah dihapus atau tidak dibagikan.
update	files	Satu atau beberapa properti (metadata) resource telah diperbarui.
trash	files	Referensi telah dipindahkan ke sampah.
untrash	files	Resource telah dihapus dari sampah.
change	changes	Satu atau beberapa item log perubahan telah ditambahkan.

Untuk peristiwa update, header HTTP X-Goog-Changed mungkin disediakan. Header tersebut berisi daftar yang dipisahkan koma yang menjelaskan jenis perubahan yang telah terjadi.

Jenis perubahan	Menunjukkan
content	Konten resource telah diperbarui.
properties	Satu atau beberapa properti resource telah diperbarui.
parents	Satu atau beberapa induk resource 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

Hentikan notifikasi

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

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

Metode ini mengharuskan Anda memberikan setidaknya properti id dan resourceId channel, seperti yang 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. Khususnya:

Jika channel dibuat oleh akun pengguna biasa, hanya pengguna yang sama dari klien yang sama (seperti yang diidentifikasi oleh ID klien OAuth 2.0 dari token autentikasi) yang membuat channel yang dapat menghentikan channel.
Jika channel dibuat oleh akun layanan, pengguna mana pun dari klien yang sama dapat menghentikan channel 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" }