REST Resource: subscriptions

Resource: Subscription

Langganan untuk menerima peristiwa tentang resource Google Workspace. Untuk mempelajari langganan lebih lanjut, lihat ringkasan Google Workspace Events API.

Representasi JSON 
{
  "name": string,
  "uid": string,
  "targetResource": string,
  "eventTypes": [
    string
  ],
  "payloadOptions": {
    object (PayloadOptions)
  },
  "notificationEndpoint": {
    object (NotificationEndpoint)
  },
  "state": enum (State),
  "suspensionReason": enum (ErrorType),
  "authority": string,
  "createTime": string,
  "updateTime": string,
  "reconciling": boolean,
  "etag": string,

  // Union field expiration can be only one of the following:
  "expireTime": string,
  "ttl": string
  // End of list of possible types for union field expiration.
}
Kolom
name

string

ID. Nama resource langganan.

Format: subscriptions/{subscription}
uid

string

Hanya output. ID unik yang ditetapkan sistem untuk langganan.
targetResource

string

Wajib. Tidak dapat diubah. Resource Google Workspace yang dipantau untuk peristiwa, diformat sebagai nama resource lengkap. Untuk mempelajari resource target dan peristiwa yang didukungnya, lihat Peristiwa Google Workspace yang didukung.

Pengguna hanya dapat mengizinkan aplikasi Anda membuat satu langganan untuk resource target tertentu. Jika aplikasi Anda mencoba membuat langganan lain dengan kredensial pengguna yang sama, permintaan akan menampilkan error ALREADY_EXISTS.
eventTypes[]

string

Wajib. Daftar yang tidak diurutkan. Input untuk membuat langganan. Jika tidak, hanya output. Satu atau beberapa jenis peristiwa yang akan diterima tentang resource target. Diformat sesuai dengan spesifikasi CloudEvents.

Jenis acara yang didukung bergantung pada resource target langganan Anda. Untuk mengetahui detailnya, lihat Acara Google Workspace yang didukung.

Secara default, Anda juga menerima peristiwa tentang siklus proses langganan. Anda tidak perlu menentukan peristiwa siklus proses untuk kolom ini.

Jika Anda menentukan jenis peristiwa yang tidak ada untuk resource target, permintaan akan menampilkan kode status HTTP 400 Bad Request.
payloadOptions

object (PayloadOptions)

Opsional. Opsi tentang data yang akan disertakan dalam payload peristiwa. Hanya didukung untuk acara Google Chat.
notificationEndpoint

object (NotificationEndpoint)

Wajib. Tidak dapat diubah. Endpoint tempat langganan mengirimkan peristiwa, seperti topik Pub/Sub.
state

enum (State)

Hanya output. Status langganan. Menentukan apakah langganan dapat menerima peristiwa dan mengirimkannya ke endpoint notifikasi.
suspensionReason

enum (ErrorType)

Hanya output. Error yang menangguhkan langganan.

Untuk mengaktifkan kembali langganan, atasi error dan panggil metode subscriptions.reactivate.
authority

string

Hanya output. Pengguna yang mengizinkan pembuatan langganan.

Format: users/{user}

Untuk pengguna Google Workspace, nilai {user} adalah kolom user.id dari Directory API.
createTime

string (Timestamp format)

Hanya output. Waktu saat langganan dibuat.
updateTime

string (Timestamp format)

Hanya output. Terakhir kali langganan diperbarui.
reconciling

boolean

Hanya output. Jika true, langganan sedang dalam proses diperbarui.
etag

string

Opsional. Checksum ini dihitung oleh server berdasarkan nilai kolom lain, dan mungkin dikirim pada permintaan update untuk memastikan klien memiliki nilai terbaru sebelum melanjutkan.

Kolom union expiration. Waktu saat langganan berakhir.

Waktu habis masa berlaku maksimum bergantung pada apakah langganan Anda menyertakan data resource dalam payload peristiwa (ditentukan dalam kolom PayloadOptions):

  • Jika payload tidak menyertakan data resource, hingga 7 hari.
  • Jika payload menyertakan data resource, hingga 4 jam. Jika organisasi Google Workspace Anda memberikan akses ke resource melalui delegasi di seluruh domain, Anda dapat memperpanjang waktu habis masa berlaku langganan hingga 24 jam.

Setelah langganan berakhir, langganan akan otomatis dihapus. Anda menerima peristiwa siklus proses ke notification_endpoint 12 jam dan satu jam sebelum langganan berakhir. Untuk mengetahui detailnya, lihat Menerima dan merespons peristiwa siklus proses.

Untuk mencegah langganan berakhir, Anda dapat menggunakan metode UpdateSubscription untuk memperpanjang tanggal berakhirnya. Untuk mengetahui detailnya, lihat Memperbarui atau memperpanjang langganan. expiration hanya dapat berupa salah satu dari hal berikut:
expireTime

string (Timestamp format)

Default tidak kosong. Stempel waktu dalam UTC saat langganan berakhir. Selalu ditampilkan pada output, terlepas dari apa yang digunakan pada input.
ttl

string (Duration format)

Hanya input. Time-to-live (TTL) atau durasi untuk langganan. Jika tidak ditentukan atau ditetapkan ke 0, durasi maksimum yang mungkin akan digunakan.

PayloadOptions

Opsi tentang data yang akan disertakan dalam payload peristiwa. Hanya didukung untuk acara Google Chat.

Representasi JSON 
{
  "includeResource": boolean,
  "fieldMask": string
}
Kolom
includeResource

boolean

Opsional. Apakah payload peristiwa menyertakan data tentang resource yang berubah. Misalnya, untuk peristiwa saat pesan Google Chat dibuat, apakah payload berisi data tentang resource Message. Jika salah (false), payload peristiwa hanya menyertakan nama resource yang diubah.
fieldMask

string (FieldMask format)

Opsional. Jika includeResource disetel ke true, daftar kolom yang akan disertakan dalam payload peristiwa. Pisahkan kolom dengan koma. Misalnya, untuk menyertakan pengirim dan waktu pembuatan pesan Google Chat, masukkan message.sender,message.createTime. Jika tidak disertakan, payload akan mencakup semua kolom untuk resource.

Jika Anda menentukan kolom yang tidak ada untuk resource, sistem akan mengabaikan kolom tersebut.

NotificationEndpoint

Endpoint tempat langganan mengirimkan peristiwa.

Representasi JSON 
{

  // Union field endpoint can be only one of the following:
  "pubsubTopic": string
  // End of list of possible types for union field endpoint.
}
Kolom

Kolom union endpoint.

endpoint hanya dapat berupa salah satu dari hal berikut:
pubsubTopic

string

Tidak dapat diubah. Topik Pub/Sub yang menerima peristiwa untuk langganan.

Format: projects/{project}/topics/{topic}

Anda harus membuat topik di project Google Cloud yang sama tempat Anda membuat langganan ini.

Catatan: Workspace Events API menggunakan kunci pengurutan untuk manfaat peristiwa berurutan. Jika topik Cloud Pub/Sub memiliki kebijakan penyimpanan pesan yang dikonfigurasi untuk mengecualikan region Google Cloud terdekat, maka memublikasikan peristiwa dengan kunci pengurutan akan gagal.

Saat topik menerima peristiwa, peristiwa tersebut dienkode sebagai pesan Pub/Sub. Untuk mengetahui detailnya, lihat Pengikatan Protokol Google Cloud Pub/Sub untuk CloudEvents.

Negara Bagian

Kemungkinan status langganan.

Enum
STATE_UNSPECIFIED Nilai default. Nilai ini tidak digunakan.
ACTIVE Langganan aktif dan dapat menerima serta mengirimkan peristiwa ke endpoint notifikasinya.
SUSPENDED Langganan tidak dapat menerima peristiwa karena terjadi error. Untuk mengidentifikasi error, lihat kolom suspensionReason.
DELETED Langganan dihapus.

ErrorType

Kemungkinan error untuk langganan.

Enum
ERROR_TYPE_UNSPECIFIED Nilai default. Nilai ini tidak digunakan.
USER_SCOPE_REVOKED Pengguna yang memberikan otorisasi telah mencabut pemberian satu atau beberapa cakupan OAuth. Untuk mempelajari lebih lanjut otorisasi untuk Google Workspace, lihat Mengonfigurasi layar izin OAuth.
RESOURCE_DELETED Target resource untuk langganan tidak ada lagi.
USER_AUTHORIZATION_FAILURE Pengguna yang mengizinkan pembuatan langganan tidak lagi memiliki akses ke resource target langganan.
ENDPOINT_PERMISSION_DENIED Aplikasi Google Workspace tidak memiliki akses untuk mengirimkan peristiwa ke notification endpoint langganan Anda.
ENDPOINT_NOT_FOUND Endpoint notifikasi langganan tidak ada, atau endpoint tidak dapat ditemukan di project Google Cloud tempat Anda membuat langganan.
ENDPOINT_RESOURCE_EXHAUSTED Endpoint notifikasi langganan gagal menerima peristiwa karena kuota tidak mencukupi atau mencapai pembatasan kapasitas.
OTHER Terjadi error yang tidak teridentifikasi.

Metode

create

 Membuat langganan Google Workspace.

delete

 Menghapus langganan Google Workspace.

get

 Mendapatkan detail tentang langganan Google Workspace.

list

 Mencantumkan langganan Google Workspace.

patch

 Memperbarui atau memperpanjang langganan Google Workspace.

reactivate

 Mengaktifkan kembali langganan Google Workspace yang ditangguhkan.