REST Resource: subscriptions

Resource: Langganan

Langganan untuk menerima peristiwa terkait 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

Opsional. Tidak dapat diubah. ID. Nama resource langganan.

Format: subscriptions/{subscription}
uid

string

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

string

Wajib diisi. Tidak dapat diubah. Resource Google Workspace yang dipantau untuk peristiwa, yang diformat sebagai nama lengkap resource. 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 diisi. Tidak dapat diubah. Daftar yang tidak diurutkan. Input untuk membuat langganan. Jika tidak, hanya output. Satu atau beberapa jenis peristiwa yang akan diterima tentang resource target. Diformat menurut 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. Anda tidak perlu menentukan peristiwa siklus proses untuk kolom ini.

Jika Anda menetapkan 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 diisi. 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 memberi otorisasi 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 langganan dibuat.
updateTime

string (Timestamp format)

Hanya output. Waktu terakhir kali langganan diperbarui.
reconciling

boolean

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

string

Opsional. Checksum ini dihitung oleh server berdasarkan nilai kolom lainnya, dan mungkin 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 menghapus data resource, maksimal 7 hari.
  • Jika payload menyertakan data resource, durasinya hingga 4 jam. Jika organisasi Google Workspace Anda memberikan akses ke resource melalui delegasi tingkat domain, Anda dapat memperpanjang waktu habis masa berlaku langganan hingga 24 jam.

Setelah masa berlakunya habis, 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 masa berlaku 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 yang berikut:
expireTime

string (Timestamp format)

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

string (Duration format)

Input saja. Time-to-live (TTL) atau durasi 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 acara 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 tempat pesan Google Chat dibuat, apakah payload berisi data tentang resource Message atau tidak. Jika salah (false), payload peristiwa hanya akan 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 menetapkan 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 yang 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 tempat Anda membuat langganan ini.

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

Negara Bagian

Status yang mungkin 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 error. Untuk mengidentifikasi error, lihat kolom suspensionReason.
DELETED Langganan dihapus.

ErrorType

Kemungkinan error pada langganan.

Enum
ERROR_TYPE_UNSPECIFIED Nilai default. Nilai ini tidak digunakan.
USER_SCOPE_REVOKED Pengguna yang memberi 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 sudah tidak ada.
USER_AUTHORIZATION_FAILURE Pengguna yang memberi otorisasi pembuatan langganan tidak lagi memiliki akses ke resource target langganan.
ENDPOINT_PERMISSION_DENIED Aplikasi Google Workspace tidak memiliki akses untuk mengirim 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.