Notifikasi push

Properti wajib

Dengan setiap permintaan watch, Anda harus menyediakan kolom berikut:

• String properti id yang mengidentifikasi hal ini secara unik saluran notifikasi baru dalam project Anda. Sebaiknya gunakan ID unik universal, (UUID) atau platform sejenis string unik. Panjang maksimum: 64 karakter.

  Nilai ID yang Anda tetapkan akan dipantulkan kembali di X-Goog-Channel-Id header HTTP setiap notifikasi pesan 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 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 aplikasi dibuat—untuk memastikan bahwa notifikasi tidak dipalsukan—atau mengarahkan pesan ke tujuan yang benar 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 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.

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": "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 Anda, informasi yang ditampilkan juga mencakup resourceId dan resourceUri untuk mengidentifikasi resource yang sedang ditonton di saluran notifikasi.

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

Sinkronkan pesan

Setelah membuat saluran notifikasi untuk melihat resource, Admin SDK API mengirim pesan sync untuk menunjukkan bahwa notifikasi dimulai. HTTP X-Goog-Resource-State nilai header 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 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 HTTP X-Goog-Message-Number nilai header 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 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 menjadi "tumpang-tindih" periode waktu saat kedua saluran notifikasi untuk resource yang sama.

Menafsirkan format pesan notifikasi

Semua pesan notifikasi mencakup 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 mengembalikan 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:

• admin
• kalender
• mengemudi
• grup
• login
• seluler
• SAML
• token
• user_accounts