Notifikasi push

Dokumen ini menjelaskan cara menggunakan notifikasi push yang memberi tahu 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 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 resource yang dipantau berubah, Admin SDK API akan 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 resource berubah.

  • Siapkan (saluran notifikasi) untuk setiap endpoint resource yang ingin Anda amati.

    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 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 Anda ditetapkan ke atas, Admin SDK API akan memberi tahu aplikasi Anda saat ada resource yang dipantau perubahan.

Membuat permintaan smartwatch

Setiap resource Admin SDK API yang dapat ditonton memiliki metode watch terkait di URI dengan format 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

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", // 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.

Pantau semua aktivitas admin:

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

Mengamati semua aktivitas dokumen:

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

Perhatikan aktivitas admin dari 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

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 platform sejenis string unik. 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 URL tersebut harus menggunakan HTTPS.

    Perhatikan bahwa Admin SDK 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 nilai string arbitrer untuk digunakan sebagai token channel. 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-spoof—atau untuk merutekan pesan ke tujuan yang tepat 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.

  • String properti expiration yang disetel ke Stempel waktu Unix (dalam milidetik) tanggal dan waktu saat Admin SDK API ingin menghentikan pengiriman pesan untuk saluran notifikasi ini.

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

Untuk mengetahui detail selengkapnya tentang permintaan, lihat metode watch untuk resource Activities 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 dibuat, 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 sedang ditonton di saluran notifikasi ini.

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

Untuk detail selengkapnya tentang respons, lihat watch untuk resource Activities dalam Referensi API.

Pesan sinkronisasi

Setelah membuat saluran notifikasi untuk memantau resource, Admin SDK API akan 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 dengan aman, tetapi Anda juga dapat 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 Admin SDK 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 nilai header HTTP X-Goog-Message-Number sebesar 1. Setiap notifikasi berikutnya untuk saluran ini memiliki nomor pesan yang lebih besar dari nomor sebelumnya, meskipun nomor pesan tidak akan berurutan.

Memperpanjang saluran notifikasi

Saluran notifikasi bisa memiliki waktu habis masa berlaku, dengan nilai ditentukan oleh permintaan Anda atau batas internal Admin SDK 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 akan ada periode waktu "tumpang-tindih" saat dua saluran notifikasi untuk resource yang sama aktif.

Terima notifikasi

Setiap kali sumber daya yang diawasi berubah, aplikasi Anda akan menerima pesan notifikasi yang menjelaskan perubahan tersebut. Admin SDK API mengirim 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 kumpulan 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 penerima URL mencakup header HTTP berikut:

Header Deskripsi
Selalu ada
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 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 dipantau.
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 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. Nilainya sudah Format tanggal dan waktu ISO 8601. Waktu adalah tanggal lengkap plus jam, menit, dan detik dalam bentuk 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 yang mencakup peristiwa tersebut. 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. Dalam 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 unik Google Workspace 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 Internet Protocol (IP) pengguna saat login ke Google Workspace yang mungkin mencerminkan 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 administrator diidentifikasi di properti type yang mengidentifikasi peristiwa menggunakan properti eventName.
events[].name Nama peristiwa. Ini adalah nama spesifik aktivitas yang dilaporkan oleh API. Selain itu, 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 dari eventName.
  • Saat Anda meminta eventName, respons API akan menampilkan semua aktivitas yang berisi eventName tersebut. Aktivitas yang ditampilkan mungkin memiliki properti eventName lain selain yang diminta.
events[].parameters[] Pasangan parameter value untuk berbagai aplikasi.
events[].parameters[].name Nama parameter.
events[].parameters[].value Nilai parameter dalam string.
events[].parameters[].intValue Nilai bilangan bulat parameter.
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 percobaan ulang dengan backoff eksponensial. Setiap kode status pengembalian lainnya dianggap sebagai kegagalan pesan.

Memahami peristiwa notifikasi Admin SDK API

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

Notifikasi push Reports API berisi dua jenis pesan: pesan sinkronisasi dan notifikasi acara. Jenis pesan ditunjukkan di header HTTP X-Goog-Resource-State. Nilai yang mungkin untuk notifikasi peristiwa sama dengan nilai untuk metode activities.list. Setiap aplikasi memiliki peristiwa unik:

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

Metode ini mengharuskan Anda menyediakan setidaknya id dan properti resourceId, seperti yang ditunjukkan dalam contoh di bawah ini. 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 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/reports_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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