Notifikasi untuk perubahan sumber daya

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. Fitur ini memungkinkan Anda menghilangkan biaya jaringan dan komputasi tambahan yang terkait dengan resource polling 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:

• Menyiapkan URL penerima atau penerima callback "webhook".

  Ini adalah server HTTPS yang menangani pesan notifikasi API yang dipicu saat resource berubah.

• Menyiapkan (saluran notifikasi) untuk setiap endpoint resource yang ingin Anda pantau.

  Saluran menentukan informasi perutean untuk pesan notifikasi pesan. Sebagai bagian dari penyiapan saluran, Anda harus mengidentifikasi URL tertentu tempat Anda ingin menerima notifikasi. Setiap kali resource saluran berubah, Google Drive API akan mengirimkan pesan notifikasi sebagai POST permintaan ke URL tersebut.

Catatan: Kata "saluran" seperti yang digunakan dalam dokumen ini secara khusus merujuk ke saluran notifikasi dan bukan ke jenis saluran lain yang digunakan dalam API atau layanan ini. Beberapa saluran notifikasi dapat aktif secara bersamaan untuk resource yang sama.

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 saat ada resource yang dipantau berubah.

Membuat permintaan pantau

Setiap resource Google Drive API yang dapat dipantau memiliki metode watch terkait di URI dengan bentuk 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 kumpulan resource). Permintaan watch tidak akan berhasil kecuali jika pengguna atau akun layanan saat ini 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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 1426325213000
}

Di isi permintaan, berikan id saluran Anda, type sebagai web_hook, dan URL penerima Anda di address. Anda juga dapat secara opsional memberikan:

• token untuk digunakan sebagai token saluran Anda.
• Waktu expiration dalam milidetik untuk waktu habis masa berlaku saluran yang Anda minta.

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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myChangesChannelDest",
  "expiration": 1426325213000
}

Di isi permintaan, berikan id saluran Anda, type sebagai web_hook, dan URL penerima Anda di address. Anda juga dapat secara opsional memberikan:

• token untuk digunakan sebagai token saluran Anda.
• Waktu expiration dalam milidetik untuk waktu habis masa berlaku saluran yang Anda minta.

Properti wajib

Dengan setiap permintaan watch, Anda harus memberikan kolom ini:

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

  Nilai ID yang Anda tetapkan akan ditampilkan kembali di X-Goog-Channel-Id header HTTP dari setiap notifikasi pesan 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 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 watch permintaan:

• Properti token yang menentukan nilai string arbitrer untuk digunakan sebagai token saluran. Anda dapat menggunakan token saluran notifikasi untuk berbagai tujuan. Misalnya, Anda dapat menggunakan token untuk memverifikasi bahwa setiap pesan masuk ditujukan untuk saluran yang dibuat 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 X-Goog-Channel-Token header HTTP di setiap pesan notifikasi yang diterima aplikasi Anda untuk saluran ini.

  Jika Anda menggunakan token saluran notifikasi, sebaiknya:

  • 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) dari tanggal dan waktu saat Anda ingin Google Drive API berhenti mengirim pesan untuk saluran notifikasi ini.

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

Catatan: Untuk Google Drive API, waktu habis masa berlaku maksimum adalah 86.400 detik (1 hari) setelah waktu saat ini untuk resource files dan 604.800 detik (1 minggu) untuk changes. Jika Anda tidak menetapkan properti expiration dalam permintaan, waktu habis masa berlaku akan ditetapkan secara default ke 3.600 detik setelah waktu saat ini.

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

Respons pantau

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

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

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://www.googleapis.com/drive/v3/files/o3hgv1538sdjfh",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 1426325213000
}

Isi respons memberikan detail saluran seperti:

• kind: Mengidentifikasi ini sebagai resource saluran API.
• id: ID yang Anda tentukan untuk saluran ini.
• resourceId: ID resource yang dipantau.
• resourceUri: ID khusus versi dari resource yang dipantau.
• token: Token yang diberikan di isi permintaan.
• expiration: Waktu habis masa berlaku saluran sebagai stempel waktu Unix dalam milidetik.

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.

Catatan: Properti resourceId adalah ID yang stabil dan independen dari versi untuk resource. Properti resourceUri adalah URI kanonis dari resource yang dipantau dalam konteks versi API saat ini, sehingga bersifat khusus versi.

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

Untuk mengetahui detail selengkapnya tentang respons, 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 dimulai. Nilai header X-Goog-Resource-State HTTP untuk pesan ini adalah sync. Karena masalah waktu jaringan, Anda mungkin menerima pesan sync bahkan sebelum 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 mendatang.

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.

Memperpanjang masa berlaku saluran notifikasi

Saluran notifikasi dapat memiliki waktu habis masa berlaku, dengan nilai ditentukan oleh permintaan Anda atau oleh batas atau default internal Google Drive 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 X-Goog-Channel-Expiration header HTTP.

Saat ini, tidak ada cara otomatis untuk memperpanjang masa berlaku saluran notifikasi. Saat saluran hampir habis masa berlakunya, Anda harus menggantinya dengan saluran baru dengan memanggil metode watch. Seperti biasa, Anda harus menggunakan nilai unik untuk properti id saluran baru. Perhatikan bahwa kemungkinan akan ada periode waktu "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.

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 kumpulan header HTTP yang memiliki X-Goog- awalan. Beberapa jenis notifikasi juga dapat menyertakan a isi pesan.

Header

Pesan notifikasi yang diposting oleh Google Drive 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. Nilai selalu 1 untuk pesan sync. Nomor pesan bertambah 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, add, remove, update, trash, untrash, atau change .
X-Goog-Resource-URI	ID khusus versi API untuk resource yang dipantau.
Terkadang ada
X-Goog-Changed	Detail tambahan tentang perubahan. Nilai yang mungkin: content, parents, children, atau permissions . Tidak disediakan dengan pesan sync.
X-Goog-Channel-Expiration	Tanggal dan waktu habis masa berlaku 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 Anda, dan yang dapat Anda gunakan untuk memverifikasi sumber notifikasi. Hanya ada jika ditentukan.

Pesan notifikasi untuk resource files (termasuk peristiwa add, remove, update, trash, dan untrash) dan resource changes selalu kosong (isi permintaan HTTP kosong, yaitu Content-Length: 0).

Catatan: Notifikasi push tidak berisi metadata resource, konten, atau jalur direktori (seperti awalan jalur folder). Untuk mendapatkan detail atau status saat ini dari resource yang diubah atau ditambahkan, aplikasi Anda harus memanggil Drive API menggunakan ID resource atau token perubahan yang diberikan (misalnya, dengan memanggil files.get atau changes.list).

Contoh

Pesan notifikasi untuk resource files saat resource ditambahkan (isi permintaan kosong):

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 3a98f1a2b3c4d5e6f7
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:  add
X-Goog-Message-Number: 10

Pesan notifikasi perubahan untuk resource files saat resource diupdate (isi permintaan kosong):

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 3a98f1a2b3c4d5e6f7
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: 11

Pesan notifikasi perubahan untuk resource changes (isi permintaan kosong):

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
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

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 Google API dan menampilkan 500,502, 503, atau 504, Google Drive API akan mencoba lagi dengan backoff eksponensial. Setiap kode status hasil 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	Dikirim saat
sync	files, changes	Saluran berhasil dibuat. Anda dapat mulai menerima notifikasi untuk saluran tersebut.
add	files	Resource dibuat atau dibagikan.
remove	files	Resource yang ada dihapus atau tidak dibagikan.
update	files	Satu atau beberapa properti (metadata) resource telah diupdate.
trash	files	Resource telah dipindahkan ke sampah.
untrash	files	Resource telah dihapus dari sampah.
change	changes	Satu atau beberapa item log perubahan telah ditambahkan.

Peristiwa status resource tambahan mungkin akan ditambahkan ke daftar ini dari waktu ke waktu. Anda mungkin menerima jenis peristiwa yang tidak terduga. Penanganan peristiwa Anda harus mengabaikan peristiwa ini dengan baik.

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	Artinya
content	Konten resource telah diupdate.
properties	Satu atau beberapa properti resource telah diupdate.
parents	Satu atau beberapa induk resource telah ditambahkan atau dihapus.
children	Satu atau beberapa turunan resource telah ditambahkan atau dihapus.
permissions	Izin resource telah diupdate.

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 berakhir dengan memanggil metode stop di URI berikut:

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

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

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

• Jika saluran 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 saluran yang dapat menghentikan saluran.
• Jika saluran dibuat oleh akun layanan, pengguna mana pun dari klien yang sama dapat menghentikan saluran.

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"
}

Topik terkait

• Bekerja dengan peristiwa dari Google Drive