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 memberi otorisasi aplikasi Anda untuk 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 peristiwa yang didukung bergantung pada resource target langganan Anda. Untuk mengetahui detailnya, lihat Peristiwa 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 peristiwa 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, selesaikan 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 pembaruan.
etag

string

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

Kolom union expiration. Waktu habis masa berlaku langganan.

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

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

Setelah masa berlakunya 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 habis masa berlakunya. 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 disetel ke 0, durasi maksimum yang memungkinkan akan digunakan.

PayloadOptions

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

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

boolean

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

string (FieldMask format)

Opsional. Jika includeResource ditetapkan ke true, daftar kolom yang akan disertakan dalam payload peristiwa. Pisahkan kolom dengan koma. Misalnya, untuk menyertakan pengirim pesan Google Chat dan membuat waktu, masukkan message.sender,message.createTime. Jika dihilangkan, payload akan menyertakan 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 Cloud Pub/Sub yang menerima peristiwa untuk langganan.

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

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

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

Negara Bagian

Kemungkinan status untuk 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. Guna mempelajari lebih lanjut otorisasi untuk Google Workspace, lihat Mengonfigurasi layar izin OAuth.
RESOURCE_DELETED Resource target untuk langganan tidak ada lagi.
USER_AUTHORIZATION_FAILURE Pengguna yang memberikan otorisasi pembuatan langganan tidak lagi memiliki akses ke resource target langganan.
ENDPOINT_PERMISSION_DENIED Aplikasi Google Workspace tidak memiliki akses untuk mengirimkan peristiwa ke endpoint notifikasi 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.