Notifikasi untuk perubahan sumber daya

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

Ringkasan

Google Drive 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 Drive API 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 Drive API mengirimkan pesan notifikasi sebagai POST ke URL tersebut.

Catatan: Kata "channel" seperti yang digunakan dalam dokumen ini merujuk secara khusus ke saluran notifikasi dan bukan jenis yang digunakan dalam API atau layanan ini.

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 sumber daya yang ingin Anda pantau. Setelah saluran notifikasi Anda ditetapkan Google Drive API memberi tahu aplikasi Anda saat ada sumber daya yang dipantau perubahan.

Membuat permintaan smartwatch

Setiap resource Google Drive 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 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 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 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 URL tersebut harus menggunakan HTTPS.

  Perhatikan bahwa Google Drive 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.

  Catatan: Jika Anda harus mengirim respons data tersebut, pastikan dienkripsi sebelum menambahkannya ke Anda.

• String properti expiration yang disetel ke Stempel waktu Unix (dalam milidetik) tanggal dan waktu saat Google Drive 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.

Catatan: Untuk Google Drive API, waktu habis masa berlaku maksimumnya adalah 86.400 detik (1 hari) setelah waktu saat ini untuk resource files dan 604800 detik (1 minggu) untuk changes. Jika Anda tidak menyetel Properti expiration dalam permintaan Anda, masa berlaku default ke 3600 detik setelah waktu saat ini.

Untuk mengetahui detail selengkapnya tentang permintaan, lihat metode watch untuk metode files dan changes 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/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 Anda, informasi yang ditampilkan juga mencakup resourceId dan resourceUri untuk mengidentifikasi resource yang sedang ditonton di saluran notifikasi.

Catatan: Properti resourceId adalah ID stabil yang tidak bergantung pada versi untuk resource. Tujuan Properti resourceUri adalah URI kanonis dari objek yang ditonton resource dalam konteks versi API saat ini, jadi spesifik per versi.

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 metode files dan changes dalam Referensi API.

Sinkronkan pesan

Setelah membuat saluran notifikasi untuk melihat resource, Google Drive 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 Drive 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 Drive 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.

Terima notifikasi

Setiap kali sumber daya yang diawasi berubah, aplikasi Anda akan menerima pesan notifikasi yang menjelaskan perubahan tersebut. Google Drive API mengirimkan informasi pesan sebagai permintaan HTTPS POST ke URL yang Anda tentukan sebagai Properti address untuk notifikasi ini saluran TV Anda.

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

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 Drive API ke penerima URL mencakup header HTTP berikut:

Header	Deskripsi
Selalu presentasikan
X-Goog-Channel-ID	UUID atau string unik lainnya yang Anda berikan untuk mengidentifikasi hal ini saluran notifikasi.
X-Goog-Message-Number	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 tersebut, tetapi tidak berurutan.
X-Goog-Resource-ID	Nilai buram yang mengidentifikasi resource yang ditonton. ID ini adalah 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 kami.
X-Goog-Resource-URI	ID khusus versi API untuk resource yang ditonton.
Terkadang ada
X-Goog-Changed	Detail tambahan tentang perubahan tersebut. Nilai yang mungkin: content, parents, children, atau permissions kami. Tidak disertakan dengan sync pesan.
X-Goog-Channel-Expiration	Tanggal dan waktu habis masa berlaku saluran notifikasi, yang dinyatakan dalam 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 didefinisikan.

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 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 Drive API percobaan ulang dengan backoff eksponensial. Setiap kode status pengembalian lainnya dianggap sebagai kegagalan pesan.

Memahami peristiwa notifikasi Google Drive API

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

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

Peristiwa status resource tambahan mungkin ditambahkan ke daftar ini seiring waktu. Anda mungkin menerima jenis peristiwa yang tidak terduga. Pengendali peristiwa Anda harus mengabaikannya dengan baik.

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.

Jenis perubahan	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

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/drive/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 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 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/drive/v3/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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