Notifikasi push

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 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, Admin SDK API akan memberi tahu aplikasi Anda.

Untuk menggunakan notifikasi push, Anda harus melakukan dua hal:

• Siapkan URL penerima atau penerima callback "webhook".

  Server HTTPS ini 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 saluran berubah, Admin SDK API mengirimkan pesan notifikasi sebagai permintaan POST ke URL tersebut.

Catatan: Kata "saluran" sebagaimana 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, Admin SDK API mendukung notifikasi untuk perubahan pada resource Activities.

Membuat saluran notifikasi

Untuk meminta notifikasi push, Anda harus menyiapkan saluran notifikasi untuk setiap resource yang ingin dipantau. Setelah saluran notifikasi Anda disiapkan, Admin SDK API akan memberi tahu aplikasi Anda saat ada perubahan pada resource yang dipantau.

Membuat permintaan jam

Setiap resource Admin SDK API yang dapat dipantau memiliki metode watch 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

Semua permintaan watch untuk resource Aktivitas 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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myFilesChannelDest",
  "payload": true,
  "expiration": 3600
}

Isi permintaan memiliki properti berikut:

• id: UUID atau string unik serupa yang mengidentifikasi saluran ini.
• type: Jenis mekanisme pengiriman. Nilai untuk kolom ini harus web_hook.
• address: URL tempat notifikasi dikirim.
• token: String arbitrer yang dikirim ke alamat target dengan setiap notifikasi, untuk tujuan memverifikasi bahwa notifikasi berasal dari sumber tepercaya.
• payload: Flag boolean yang menunjukkan apakah payload harus disertakan dalam notifikasi.
• expiration: Waktu aktif dalam detik untuk saluran notifikasi.

Anda dapat menggunakan parameter userKey, applicationName, eventName, dan filters untuk hanya menerima notifikasi untuk peristiwa, pengguna, atau aplikasi tertentu.

Catatan: Contoh berikut tidak menyertakan isi permintaan agar lebih jelas.

Memantau semua aktivitas admin:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch

Memantau semua aktivitas dokumen:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch

Memantau aktivitas admin pengguna tertentu:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/[e-mail]/applications/admin/watch

Pantau peristiwa tertentu, seperti perubahan sandi pengguna:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD

Memantau 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

Dengan setiap permintaan watch, Anda harus memberikan kolom berikut:

• 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 dikembalikan 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 Admin SDK 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 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 channel yang dibuat oleh aplikasi Anda—untuk memastikan bahwa notifikasi tidak dipalsukan—atau untuk merutekan pesan ke tujuan yang tepat dalam aplikasi Anda berdasarkan tujuan channel 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.

  Catatan: Jika Anda harus mengirimkan data yang sangat sensitif, pastikan data tersebut dienkripsi sebelum ditambahkan ke token.

• String properti expiration yang ditetapkan ke stempel waktu Unix (dalam milidetik) tanggal dan waktu saat Anda ingin Admin SDK 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.

Catatan: Untuk Admin SDK API, waktu habis masa berlaku maksimum adalah 21600 detik. Jika Anda tidak menetapkan properti expiration dalam permintaan, waktu berakhir akan ditetapkan secara default menjadi 21600 detik setelah waktu saat ini.

Untuk mengetahui detail selengkapnya tentang permintaan, lihat metode watch untuk resource Activities di Referensi API.

Tonton 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": "reportsApiId",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 3600
}

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 tidak bergantung pada versi untuk resource. Properti resourceUri adalah URI kanonis dari resource yang ditonton dalam konteks versi API saat ini, sehingga spesifik per versi.

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

Untuk mengetahui detail selengkapnya tentang respons, lihat metode watch untuk resource Aktivitas di Referensi API.

Pesan sinkronisasi

Setelah membuat saluran notifikasi untuk memantau resource, Admin SDK 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 dan X-Goog-Resource-ID dalam panggilan ke berhenti menerima notifikasi. Anda juga dapat menggunakan notifikasi sync untuk melakukan beberapa inisialisasi sebagai persiapan untuk peristiwa berikutnya.

Format pesan sync yang dikirimkan Admin SDK API ke URL penerima Anda ditunjukkan 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 yang ditentukan oleh permintaan Anda atau oleh batas internal atau default Admin SDK 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. Saat 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. Admin SDK API mengirim pesan ini sebagai permintaan HTTPS POST 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 API Google.

Menafsirkan format pesan notifikasi

Semua pesan notifikasi menyertakan serangkaian 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
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. Message numbers 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 dipantau.
Kadang-kadang hadir
X-Goog-Channel-Expiration	Tanggal dan waktu berakhirnya channel notifikasi, 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 Aktivitas berisi informasi berikut dalam isi permintaan:

Properti	Deskripsi
kind	Mengidentifikasi ini sebagai resource Aktivitas. Nilai: string tetap "admin#reports#activity".
id	ID unik catatan aktivitas.
id.time	Waktu terjadinya aktivitas. Nilai dalam 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 acara memiliki waktu yang sama.
id.applicationName	Nama aplikasi tempat peristiwa terjadi. Nilai yang memungkinkan mencakup: admin kalender drive grup groups_enterprise login seluler saml token user_accounts
id.customerId	ID unik untuk akun Google Workspace.
actor	Pengguna yang melakukan tindakan.
actor.callerType	Jenis penulis yang melakukan aktivitas yang tercantum dalam laporan. Dalam versi API ini, callerType adalah USER atau permintaan entitas 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 mungkin tidak mencerminkan lokasi fisik pengguna. Misalnya, alamat IP tersebut 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 dalam properti type yang mengidentifikasi peristiwa menggunakan properti eventName.
events[].name	Nama acara. Ini adalah nama spesifik aktivitas yang dilaporkan oleh API. Setiap eventName terkait dengan layanan atau fitur Google Workspace tertentu yang diatur API ke dalam jenis peristiwa. Untuk parameter permintaan eventName secara umum: Jika tidak ada eventName yang diberikan, laporan akan menampilkan semua kemungkinan instance eventName. Saat Anda meminta eventName, respons API akan menampilkan semua aktivitas yang berisi eventName tersebut. Mungkin saja aktivitas yang ditampilkan akan memiliki properti eventName lain selain yang diminta.
events[].parameters[]	Pasangan nilai parameter untuk berbagai aplikasi.
events[].parameters[].name	Nama parameter.
events[].parameters[].value	Nilai string parameter.
events[].parameters[].intValue	Nilai parameter bilangan bulat.
events[].parameters[].boolValue	Nilai boolean parameter.

Contoh

Pesan notifikasi untuk peristiwa resource Aktivitas memiliki bentuk umum:

POST https://mydomain.com/notifications
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
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": "[e-mail]",
    "profileId": "0123456789987654321"
  },
  "ownerDomain": "apps-reporting.example.com",
  "ipAddress": "192.0.2.0",
  "events": [
    {
      "type": "USER_SETTINGS",
      "name": "CREATE_USER",
      "parameters": [
        {
          "name": "USER_EMAIL",
          "value": "[e-mail]"
        }
      ]
    }
  ]
}

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 lagi dengan penundaan eksponensial. Kode status pengembalian lainnya dianggap sebagai kegagalan pesan.

Memahami peristiwa notifikasi Admin SDK API

Bagian ini memberikan 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 sinkronisasi dan notifikasi peristiwa. Jenis pesan ditunjukkan di header HTTP X-Goog-Resource-State. Kemungkinan nilai untuk notifikasi acara sama dengan nilai untuk metode activities.list. Setiap aplikasi memiliki peristiwa unik:

• admin
• kalender
• drive
• grup
• login
• seluler
• saml
• token
• user_accounts

Catatan: Peristiwa status resource tambahan dapat ditambahkan dari waktu ke waktu. Handler pesan notifikasi Anda harus mengabaikan nilai yang tidak terduga dengan baik.

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

Metode ini mengharuskan Anda memberikan setidaknya properti id dan resourceId channel, seperti yang 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. 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/admin/reports_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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

Pertimbangan Khusus

Saat menggunakan notifikasi push, perhatikan hal berikut:

Notifikasi tidak 100% dapat diandalkan. Sebagian kecil pesan akan dihapus dalam kondisi kerja normal. Pastikan untuk menangani pesan yang hilang ini dengan baik, sehingga aplikasi tetap disinkronkan meskipun tidak ada pesan push yang diterima.

Notifikasi mungkin tidak dikirimkan dalam urutan terjadinya peristiwa.