Notifikasi push

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 digemakan kembali di header HTTP X-Goog-Channel-Id di 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 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 tersebut untuk memverifikasi bahwa setiap pesan masuk ditujukan untuk saluran yang dibuat oleh aplikasi Anda—untuk memastikan bahwa notifikasi tidak di-spoofing—atau untuk mengarahkan pesan ke tujuan yang tepat dalam aplikasi 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) pada tanggal dan waktu saat Anda ingin Admin SDK API berhenti mengirim pesan untuk saluran notifikasi ini.

  Jika saluran memiliki waktu habis masa berlaku, itu 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.

Lihat respons

Jika permintaan watch berhasil membuat saluran notifikasi, permintaan ini akan menampilkan kode status HTTP 200 OK.

Isi pesan respons jam menyediakan informasi tentang saluran notifikasi yang baru saja Anda buat, seperti yang ditunjukkan pada 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 mencakup resourceId dan resourceUri untuk mengidentifikasi resource yang sedang dipantau 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 metode watch untuk resource Aktivitas di Referensi API.

Sinkronkan pesan

Setelah membuat saluran notifikasi untuk menonton 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 masalah pengaturan waktu jaringan, Anda dapat menerima pesan sync bahkan sebelum Anda menerima respons metode watch.

Anda dapat mengabaikan notifikasi sync, 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 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.

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 waktu habis masa berlaku, dengan nilai yang ditentukan oleh permintaan Anda atau oleh batas internal Admin SDK API atau default (nilai yang lebih ketat 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. Jika suatu saluran mendekati 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 ada kemungkinan periode waktu "tumpang-tindih" saat dua saluran notifikasi untuk resource yang sama aktif.

Menafsirkan format pesan notifikasi

Semua pesan notifikasi menyertakan sekumpulan header HTTP yang memiliki awalan X-Goog-. Beberapa jenis notifikasi juga dapat menyertakan isi pesan.

Pesan notifikasi untuk Aktivitas berisi informasi berikut dalam isi permintaan:

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
        }
      ]
    }
  ]
}

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 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 sync dan notifikasi peristiwa. Jenis pesan ditunjukkan di header HTTP X-Goog-Resource-State. Nilai yang memungkinkan untuk notifikasi peristiwa sama dengan nilai untuk metode activities.list. Setiap aplikasi memiliki peristiwa unik:

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