REST Resource: subscriptions

Referensi: Langganan

Langganan untuk menerima acara 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

Opsional. Tidak dapat diubah. Pengenal. 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 acara, yang diformat sebagai nama referensi 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. 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 menentukan jenis peristiwa yang tidak ada untuk resource target, permintaan akan menampilkan kode status 400 Bad Request HTTP.
payloadOptions

object (PayloadOptions)

Opsional. Opsi tentang data apa saja 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 memberikan 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 pembuatan langganan.
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 masa berlaku langganan berakhir.

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

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

Setelah masa berlaku langganan berakhir, langganan tersebut 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 yang tidak kosong. Stempel waktu dalam UTC saat masa berlaku langganan berakhir. Selalu ditampilkan di output, apa pun yang digunakan pada input.
ttl

string (Duration format)

Hanya input. Time to live (TTL) atau durasi langganan. Jika tidak ditentukan atau disetel ke 0, akan menggunakan durasi maksimum yang memungkinkan.

PayloadOptions

Opsi tentang data apa saja 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 tempat pesan Google Chat dibuat, apakah payload berisi data tentang resource Message atau tidak. Jika nilainya adalah salah (false), 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 mencakup 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

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 acara karena terjadi 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 otorisasi Google Workspace lebih lanjut, lihat Mengonfigurasi layar izin OAuth.
RESOURCE_DELETED Resource target 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 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.