Dokumen ini menjelaskan cara menggunakan notifikasi push yang memberi tahu aplikasi Anda saat resource berubah.
Ringkasan
Admin SDK API menyediakan notifikasi push yang memungkinkan Anda memantau perubahan resource. Anda dapat menggunakan fitur ini untuk meningkatkan performa aplikasi. Hal ini memungkinkan Anda menghilangkan jaringan tambahan dan menghitung biaya yang terkait dengan resource polling untuk menentukan apakah biaya tersebut telah berubah. Setiap kali resource yang dipantau berubah, Admin SDK 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 saluran, Anda harus mengidentifikasi URL spesifik tempat Anda ingin menerima notifikasi. Setiap kali resource saluran berubah, Admin SDK API akan mengirimkan pesan notifikasi sebagai permintaan
POST
ke URL tersebut.
Saat ini, Admin SDK API mendukung notifikasi untuk perubahan pada resource Activity.
Membuat saluran notifikasi
Untuk meminta notifikasi push, Anda harus menyiapkan saluran notifikasi untuk setiap resource yang ingin dipantau. Setelah saluran notifikasi disiapkan, Admin SDK API akan memberi tahu aplikasi Anda jika ada perubahan resource yang dipantau.
Membuat permintaan smartwatch
Setiap resource Admin SDK API yang dapat ditonton memiliki metode
watch
terkait 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 resource tertentu (atau sekumpulan resource). Permintaan watch
tidak akan berhasil kecuali jika pengguna atau akun layanan saat ini memiliki atau memiliki izin untuk mengakses resource ini.
Contoh
Semua permintaan pantauan untuk resource Activity memiliki bentuk umum:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/userKey or all/applications/applicationName/watch 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. "payload": true, // (Optional) Whether to include the payload (message body) in notifications. "expiration": 3600 // (Optional) Your requested channel expiration time. }
Anda dapat menggunakan parameter userKey, applicationName, eventName
, dan filters
untuk hanya menerima notifikasi untuk peristiwa, pengguna, atau aplikasi tertentu.
Catatan: Contoh berikut menghilangkan isi permintaan agar lebih jelas.
Perhatikan semua aktivitas admin:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch
Perhatikan semua aktivitas dokumen:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch
Perhatikan aktivitas admin pengguna tertentu:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch
Perhatikan peristiwa tertentu, seperti mengubah sandi pengguna:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD
Perhatikan perubahan pada dokumen tertentu:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch?eventName=EDIT&filters==doc_id=123456abcdef
Properti wajib
Untuk 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 yang serupa. Panjang maksimum: 64 karakter.Nilai ID yang Anda tetapkan akan ditampilkan 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 Admin SDK API dapat mengirimkan 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 cocok 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 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 Anda 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
yang ditetapkan ke stempel waktu Unix (dalam milidetik) dari tanggal dan waktu saat Anda ingin Admin SDK API berhenti mengirim pesan untuk saluran notifikasi ini.Jika saluran memiliki waktu habis masa berlaku, masa berlaku tersebut 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 resource Aktivitas dalam Referensi API.
Tonton respons
Jika permintaan watch
berhasil membuat saluran notifikasi, permintaan tersebut akan menampilkan kode status HTTP 200 OK
.
Isi pesan respons tonton menyediakan informasi tentang saluran notifikasi yang baru saja Anda buat, seperti yang ditunjukkan dalam contoh di bawah ini.
{ "kind": "api#channel", "id": "reportsApiId", // ID you specified for this channel. "resourceId": "o3hgv1538sdjfh", // ID of the watched resource. "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource. "token": "target=myApp-myFilesChannelDest", // Present only if one was provided. "expiration": 3600, // Actual expiration time as Unix timestamp (in ms), if applicable. }
Selain properti yang Anda kirim sebagai bagian dari permintaan, informasi yang ditampilkan juga menyertakan resourceId
dan resourceUri
untuk mengidentifikasi resource yang dipantau di saluran notifikasi ini.
Anda dapat meneruskan informasi yang ditampilkan ke operasi saluran notifikasi lainnya, seperti ketika Anda ingin berhenti menerima notifikasi.
Untuk detail selengkapnya tentang respons, lihat metode watch
untuk resource Aktivitas dalam Referensi API.
Sinkronkan pesan
Setelah membuat saluran notifikasi untuk mengamati resource, Admin SDK API mengirimkan pesan sync
untuk menunjukkan bahwa notifikasi dimulai. Nilai header HTTP X-Goog-Resource-State
untuk pesan ini adalah sync
. Karena masalah pengaturan waktu
jaringan, pesan sync
dapat diterima bahkan sebelum Anda menerima respons metode watch
.
Anda dapat mengabaikan notifikasi sync
, tetapi Anda juga dapat
menggunakannya. Misalnya, jika Anda 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 berikutnya.
Format pesan sync
yang dikirim Admin SDK API ke 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 nilai header HTTP X-Goog-Message-Number
dari 1
. Setiap notifikasi berikutnya untuk saluran ini memiliki nomor pesan yang lebih besar dari notifikasi sebelumnya, meskipun nomor pesan tidak akan berurutan.
Memperpanjang saluran notifikasi
Saluran notifikasi dapat memiliki masa berlaku, dengan nilai yang ditentukan oleh permintaan Anda atau oleh batas internal atau default Admin SDK API (nilai yang lebih ketat akan 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 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. Perhatikan bahwa mungkin 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. Admin SDK 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 sekumpulan header HTTP yang memiliki awalan X-Goog-
.
Beberapa jenis notifikasi juga dapat menyertakan
isi pesan.
Header
Pesan notifikasi yang diposting oleh Admin SDK API ke URL penerima Anda mencakup header HTTP berikut:
Header | Deskripsi |
---|---|
Selalu ada | |
|
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 dipantau. ID ini stabil di seluruh versi API. |
|
Status resource baru yang memicu notifikasi.
Nilai yang memungkinkan:
sync atau nama peristiwa.
|
|
ID khusus versi API untuk resource yang dipantau. |
Terkadang ada | |
|
Tanggal dan waktu habisnya 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 Aktivitas berisi informasi berikut dalam isi permintaan:
Properti | Deskripsi |
---|---|
kind |
Mengidentifikasi ini sebagai resource Activity. Nilai: string tetap "admin#reports#activity ". |
id |
ID unik catatan aktivitas. |
id.time |
Waktu terjadinya aktivitas. Nilai ini menggunakan format tanggal dan waktu ISO 8601. Waktu adalah tanggal lengkap plus jam, menit, dan detik dalam format YYYY-MM-DDThh:mm:ssTZD. Misalnya, 2010-04-05T17:30:04+01:00. |
id.uniqueQualifier |
Penentu unik jika beberapa peristiwa memiliki waktu yang sama. |
id.applicationName |
Nama aplikasi tempat peristiwa tersebut berada. Nilai yang memungkinkan mencakup: |
id.customerId |
ID unik untuk akun Google Workspace. |
actor |
Pengguna yang melakukan tindakan. |
actor.callerType |
Jenis penulis yang melakukan aktivitas yang tercantum dalam laporan. Di versi API ini, callerType adalah permintaan entity USER atau OAuth 2LO yang melakukan tindakan yang tercantum dalam laporan . |
actor.email |
Alamat email utama pengguna yang aktivitasnya dilaporkan. |
actor.profileId |
ID profil Google Workspace unik pengguna. |
ownerDomain |
Domain konsol Admin atau pemilik dokumen aplikasi Dokumen. Ini adalah domain yang terpengaruh oleh peristiwa laporan. |
ipAddress |
Alamat IP pengguna yang melakukan tindakan. Ini adalah alamat Protokol Internet (IP) pengguna saat login ke Google Workspace, yang mungkin atau tidak mencerminkan lokasi fisik pengguna. Misalnya, alamat IP dapat berupa alamat server proxy pengguna atau alamat virtual private network (VPN). API ini mendukung IPv4 dan IPv6. |
events[] |
Peristiwa aktivitas dalam laporan. |
events[].type |
Jenis peristiwa. Layanan atau fitur Google Workspace yang diubah oleh administrator diidentifikasi di properti type yang mengidentifikasi peristiwa menggunakan properti eventName . |
events[].name |
Nama peristiwa. Ini adalah nama spesifik aktivitas yang dilaporkan oleh API. Dan setiap eventName terkait dengan layanan atau fitur Google Workspace tertentu yang diatur API ke dalam jenis peristiwa.
Untuk parameter permintaan eventName secara umum:
|
events[].parameters[] |
Pasangan nilai parameter untuk berbagai aplikasi. |
events[].parameters[].name |
Nama parameter. |
events[].parameters[].value |
Nilai string parameter. |
events[].parameters[].intValue |
Nilai parameter yang berupa bilangan bulat. |
events[].parameters[].boolValue |
Nilai Boolean parameter. |
Contoh
Pesan notifikasi untuk peristiwa resource Aktivitas memiliki bentuk umum:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 0 X-Goog-Channel-ID: reportsApiId 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/reports/v1/activity/userKey/applications/applicationName X-Goog-Resource-State: eventName X-Goog-Message-Number: 10 { "kind": "admin#reports#activity", "id": { "time": datetime, "uniqueQualifier": long, "applicationName": string, "customerId": string }, "actor": { "callerType": string, "email": string, "profileId": long }, "ownerDomain": string, "ipAddress": string, "events": [ { "type": string, "name": string, "parameters": [ { "name": string, "value": string, "intValue": long, "boolValue": boolean } ] } ] }
Contoh peristiwa aktivitas admin:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 596 X-Goog-Channel-ID: reportsApiId X-Goog-Channel-Token: 245t1234tt83trrt333 X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT X-Goog-Resource-ID: ret987df98743md8g X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json X-Goog-Resource-State: CREATE_USER X-Goog-Message-Number: 23 { "kind": "admin#reports#activity", "id": { "time": "2013-09-10T18:23:35.808Z", "uniqueQualifier": "-0987654321", "applicationName": "admin", "customerId": "ABCD012345" }, "actor": { "callerType": "USER", "email": "admin@example.com", "profileId": "0123456789987654321" }, "ownerDomain": "apps-reporting.example.com", "ipAddress": "192.0.2.0", "events": [ { "type": "USER_SETTINGS", "name": "CREATE_USER", "parameters": [ { "name": "USER_EMAIL", "value": "liz@example.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
, Admin SDK API
akan mencoba kembali dengan backoff eksponensial.
Setiap kode status pengembalian lainnya akan dianggap gagal dalam pesan.
Memahami peristiwa notifikasi Admin SDK API
Bagian ini menjelaskan detail tentang pesan notifikasi yang dapat Anda terima saat menggunakan notifikasi push dengan Admin SDK API.
Notifikasi push Reports API berisi dua jenis pesan: pesan sync dan notifikasi peristiwa. Jenis pesan ditunjukkan dalam header HTTP X-Goog-Resource-State
. Nilai yang memungkinkan untuk notifikasi peristiwa sama dengan nilai untuk metode activities.list
. Setiap aplikasi memiliki peristiwa unik:
Menghentikan notifikasi
Properti expiration
mengontrol kapan notifikasi berhenti secara otomatis. Anda dapat memilih untuk berhenti menerima notifikasi saluran tertentu sebelum masa berlakunya habis dengan memanggil metode stop
di URI berikut:
https://www.googleapis.com/admin/reports_v1/channels/stop
Metode ini mengharuskan Anda menyediakan setidaknya properti
id
dan resourceId
saluran, seperti ditunjukkan dalam
contoh di bawah. Perhatikan bahwa jika Admin SDK 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 saluran dibuat oleh akun pengguna reguler, hanya pengguna yang sama dari klien yang sama (seperti yang diidentifikasi oleh client ID OAuth 2.0 dari token autentikasi) yang membuat saluran tersebut yang dapat menghentikan saluran.
- 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/admin/reports_v1/channels/stop Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66", "resourceId": "ret08u3rv24htgh289g" }