Halaman ini diterjemahkan oleh Cloud Translation API.

Notifikasi Push

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

Ringkasan

Directory API menyediakan notifikasi push yang memungkinkan Anda memantau perubahan pada resource. Anda dapat menggunakan fitur ini untuk meningkatkan performa aplikasi Anda. Hal 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, Directory 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 sumber daya berubah.
Siapkan (saluran notifikasi) untuk setiap endpoint resource yang ingin smartwatch.
Saluran menentukan informasi pemilihan rute untuk pesan notifikasi. Sebagai bagian dari penyiapan saluran, Anda harus mengidentifikasi URL tertentu tempat Anda ingin menerima notifikasi. Setiap kali sumber daya saluran berubah, Directory API mengirimkan pesan notifikasi sebagai POST ke URL tersebut.

Saat ini, Directory API mendukung notifikasi untuk perubahan pada resource Users.

Membuat saluran notifikasi

Untuk meminta notifikasi push, Anda harus menyiapkan saluran notifikasi untuk setiap sumber daya yang ingin Anda pantau. Setelah saluran notifikasi disiapkan, Directory API akan memberi tahu aplikasi Anda saat resource yang dipantau berubah.

Membuat permintaan smartwatch

Setiap resource Directory API yang dapat dipantau 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 resource tertentu, kirim permintaan POST ke metode watch untuk resource tersebut.

Setiap saluran notifikasi dikaitkan dengan pengguna tertentu dan sumber daya tertentu (atau serangkaian sumber daya). Permintaan watch tidak akan berhasil kecuali jika pengguna saat ini atau akun layanan memiliki atau memiliki izin untuk mengakses resource ini.

Contoh

Semua permintaan watch untuk resource User untuk satu domain memiliki bentuk umum:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=domain&event=event
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-myFilesChannelDest", // (Optional) Your channel token.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

Gunakan parameter domain dan event untuk menentukan domain dan jenis peristiwa yang notifikasinya ingin Anda terima.

Semua permintaan watch untuk resource Pengguna bagi pelanggan memiliki bentuk umum:

POST https://admin.googleapis.com/admin/directory/users/v1/watch?customer=customer&event=event
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-myFilesChannelDest", // (Optional) Your channel token.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

Gunakan parameter customer dan event untuk menentukan ID unik Akun Google pelanggan dan jenis peristiwa yang notifikasinya ingin Anda terima.

Nilai yang mungkin untuk event adalah:

add: peristiwa yang dibuat pengguna
delete: peristiwa dihapus pengguna
makeAdmin: peristiwa perubahan status admin pengguna
undelete: peristiwa pengguna yang dibatalkan penghapusannya
update: peristiwa yang diperbarui pengguna

Catatan: Contoh berikut menghilangkan isi permintaan agar lebih jelas.

Perhatikan peristiwa yang dibuat pengguna untuk domain mydomain.com:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=mydomain.com&event=add

Perhatikan peristiwa yang dibuat pengguna untuk pelanggan my_customer:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?customer=my_customer&event=add

Properti wajib

Dengan setiap permintaan watch, Anda harus menyediakan 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 ditampilkan kembali di header HTTP X-Goog-Channel-Id dari setiap pesan notifikasi 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 Directory API dapat mengirim notifikasi ke alamat HTTPS ini hanya 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 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 dibuat aplikasi Anda—untuk memastikan bahwa notifikasi tidak di-spoof—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 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.
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 Directory API ingin 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 Users di 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": "B4ibMJiIhTjAQd7Ff2K2bexk8G4", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1384823632000, // 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.

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 resource Users dalam Referensi API.

Pesan sinkronisasi

Setelah membuat saluran notifikasi untuk memantau resource, Directory API mengirim pesan sync untuk menunjukkan bahwa notifikasi dimulai. Nilai header HTTP X-Goog-Resource-State 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 notifikasi sync untuk melakukan beberapa inisialisasi guna mempersiapkan peristiwa berikutnya.

Format pesan sync yang dikirim Directory 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 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 Directory 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 habis masa berlaku disertakan (dalam format yang dapat dibaca manusia) dalam 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. Kapan saluran akan kedaluwarsa, Anda harus menggantinya dengan yang baru dengan memanggil metode watch. Seperti biasa, Anda harus menggunakan nilai 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 resource yang dipantau berubah, aplikasi Anda akan menerima pesan notifikasi yang menjelaskan perubahan tersebut. Directory API mengirim 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 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 pemberitahuan yang diposting oleh Directory API ke penerima URL 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. Nilainya selalu `1` untuk pesan `sync`. Kirim pesan jumlahnya meningkat 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` atau nama peristiwa.
`X-Goog-Resource-URI`	ID khusus versi API untuk resource yang ditonton.
Terkadang ada
`X-Goog-Channel-Expiration`	Tanggal dan waktu berakhirnya 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 didefinisikan.

Pesan notifikasi untuk pengguna berisi informasi berikut dalam isi permintaan:

Properti	Deskripsi
`kind`	Mengidentifikasinya sebagai resource Pengguna. Nilai: string tetap "`admin#directory#user`".
`id`	ID unik resource pengguna.
`etag`	ETag pesan notifikasi. Berbeda dengan ETag resource Pengguna.
`primaryEmail`	Alamat email utama pengguna.

Contoh

Pesan notifikasi untuk peristiwa resource User memiliki bentuk umum:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: directoryApiId
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: 'https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event
X-Goog-Resource-State:  event
X-Goog-Message-Number: 10

{
  "kind": "admin#directory#user",
  "id": long,
  "etag": string,
  "primaryEmail": string
}

Contoh peristiwa yang dihapus pengguna:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 189
X-Goog-Channel-ID: deleteChannel
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Mon, 09 Dec 2013 22:24:23 GMT
X-Goog-Resource-ID:  B4ibMJiIhTjAQd7Ff2K2bexk8G4
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=mydomain.com&event=delete&alt=json
X-Goog-Resource-State:  delete
X-Goog-Message-Number: 236440

{
  "kind": "admin#directory#user",
  "id": "111220860655841818702",
  "etag": "\"Mf8RAmnABsVfQ47MMT_18MHAdRE/evLIDlz2Fd9zbAqwvIp7Pzq8UAw\"",
  "primaryEmail": "user@mydomain.com"
}

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, Directory API akan mencoba lagi dengan backoff eksponensial. Setiap kode status pengembalian lainnya dianggap sebagai kegagalan pesan.

Hentikan 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/admin/directory_v1/channels/stop

Metode ini mengharuskan Anda memberikan setidaknya properti id dan resourceId saluran, seperti yang ditunjukkan dalam contoh di bawah. Perhatikan bahwa jika Directory 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 channel dibuat oleh akun layanan, pengguna mana pun dari klien yang sama dapat menghentikan channel.

Contoh kode berikut menunjukkan cara berhenti menerima notifikasi:

POST https://www.googleapis.com/admin/directory_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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