REST Resource: subscriptions

資源：Subscription

訂閱項目，用於接收 Google Workspace 資源相關事件。如要進一步瞭解訂閱，請參閱「Google Workspace Event API 總覽」一文。

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.
}
欄位
name

string

選用設定。不可變動。ID。訂閱項目的資源名稱。

格式︰subscriptions/{subscription}
uid

string

僅供輸出。系統為訂閱項目指派的專屬 ID。
targetResource

string

必要欄位。不可變動。監控事件的 Google Workspace 資源，格式為「完整資源名稱」。如要瞭解目標資源及其支援的事件，請參閱「支援的 Google Workspace 活動」。

使用者只能授權應用程式為特定目標資源建立一個訂閱項目。如果應用程式嘗試使用相同的使用者憑證建立另一個訂閱項目，要求會傳回 ALREADY_EXISTS 錯誤。
eventTypes[]

string

必要欄位。不可變動。未排序的清單。用於建立訂閱項目的輸入內容。否則系統只會輸出。要接收與目標資源相關的一或多個事件類型。根據 CloudEvents 規格格式化。

支援的事件類型取決於訂閱項目的目標資源。詳情請參閱「支援的 Google Workspace 事件」。

根據預設，您也會收到訂閱生命週期的相關事件。您不需要為這個欄位指定生命週期事件。

如果目標資源沒有指定的事件類型，要求會傳回 HTTP 400 Bad Request 狀態碼。
payloadOptions

object (PayloadOptions)

選用設定。關於要在事件酬載中包含哪些資料的選項。僅適用於 Google Chat 活動。
notificationEndpoint

object (NotificationEndpoint)

必要欄位。不可變動。訂閱項目傳送事件 (例如 Pub/Sub 主題) 的端點。
state

enum (State)

僅供輸出。訂閱的狀態。決定訂閱項目是否能接收事件，並將事件傳送至通知端點。
suspensionReason

enum (ErrorType)

僅供輸出。暫停訂閱的錯誤。

如要重新啟用訂閱項目，請解決錯誤並呼叫 subscriptions.reactivate 方法。
authority

string

僅供輸出。授權建立訂閱項目的使用者。

格式︰users/{user}

如果是 Google Workspace 使用者，{user} 值是 Directory API 中的 user.id 欄位。
createTime

string (Timestamp format)

僅供輸出。訂閱項目的建立時間。
updateTime

string (Timestamp format)

僅供輸出。訂閱項目的上次更新時間。
reconciling

boolean

僅供輸出。如為 true，代表訂閱項目正在更新中。
etag

string

選用設定。這個總和檢查碼是由伺服器根據其他欄位的值計算，而且可能會在更新要求時傳送，以確保用戶端有最新的值再繼續。

聯集欄位 expiration。訂閱到期的時間。

最長到期時間取決於訂閱項目是否在事件酬載中包含資源資料 (在 PayloadOptions 欄位中指定)：

  • 如果酬載省略資源資料，最長為 7 天。
  • 如果酬載包含資源資料，最長 4 小時。如果 Google Workspace 機構是透過全網域委派授予資源的存取權，您可以將訂閱項目的到期時間延長為 24 小時。

訂閱到期後，系統會自動刪除該項目。您會在訂閱到期前 12 小時又 1 小時收到 notification_endpoint 的生命週期事件。詳情請參閱「接收及回應生命週期事件」一文。

如要避免訂閱項目到期，您可以使用 UpdateSubscription 方法延長其到期日。詳情請參閱「更新或續訂訂閱項目」。expiration 只能採用下列其中一種設定：
expireTime

string (Timestamp format)

非空白的預設值。訂閱到期時的時間戳記 (採用世界標準時間)。無論輸入內容使用何種輸入方式，一律在輸出時顯示。
ttl

string (Duration format)

僅限輸入。訂閱項目的存留時間 (TTL) 或持續時間。如果未指定或設為 0，請使用可能的時間長度上限。

PayloadOptions

關於要在事件酬載中包含哪些資料的選項。僅適用於 Google Chat 活動。

JSON 表示法 
{
  "includeResource": boolean,
  "fieldMask": string
}
欄位
includeResource

boolean

選用設定。事件酬載是否包含變更的資源相關資料。例如，對於建立 Google Chat 訊息的事件，無論酬載是否包含 Message 資源相關資料都適用此規則。如果為 false，事件酬載只會包含已變更資源的名稱。
fieldMask

string (FieldMask format)

選用設定。如果將 includeResource 設為 true，系統就會列出要納入事件酬載的欄位。以半形逗號隔開欄位。舉例來說，如要加入 Google Chat 訊息的傳送者並建立時間，請輸入 message.sender,message.createTime。如果省略，酬載會包含資源的所有欄位。

如果該資源沒有您指定的欄位，系統會忽略該欄位。

NotificationEndpoint

訂閱傳送事件的端點。

JSON 表示法 
{

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

聯集欄位 endpoint。

endpoint 只能採用下列其中一種設定：
pubsubTopic

string

不可變動。接收訂閱事件的 Cloud Pub/Sub 主題。

格式︰projects/{project}/topics/{topic}

您必須在建立這個訂閱項目的同一個 Google Cloud 專案中建立主題。

當主題收到事件時，系統會將事件編碼為 Cloud Pub/Sub 訊息。詳情請參閱適用於 CloudEvents 的 Google Cloud Pub/Sub 通訊協定繫結。

狀態

訂閱項目的可能狀態。

列舉
STATE_UNSPECIFIED 預設值。未使用這個值。
ACTIVE 訂閱有效，可以接收事件並傳送至通知端點。
SUSPENDED 發生錯誤，訂閱項目無法接收事件。如要找出錯誤，請參閱 suspensionReason 欄位。
DELETED 已刪除訂閱項目。

ErrorType

可能發生訂閱錯誤。

列舉
ERROR_TYPE_UNSPECIFIED 預設值。未使用這個值。
USER_SCOPE_REVOKED 授權使用者已撤銷一或多個 OAuth 範圍的授權。如要進一步瞭解 Google Workspace 的授權，請參閱「設定 OAuth 同意畫面」。
RESOURCE_DELETED 訂閱項目的目標資源已不存在。
USER_AUTHORIZATION_FAILURE 授權建立訂閱項目的使用者無法再存取訂閱項目的目標資源。
ENDPOINT_PERMISSION_DENIED Google Workspace 應用程式無法存取將事件傳送至訂閱項目的通知端點。
ENDPOINT_NOT_FOUND 訂閱項目的通知端點不存在，或是您在建立訂閱項目的 Google Cloud 專案中找不到端點。
ENDPOINT_RESOURCE_EXHAUSTED 由於配額不足或達到頻率限制，訂閱項目的通知端點無法接收事件。
OTHER 發生無法識別的錯誤。

方法

create

 建立 Google Workspace 訂閱方案。

delete

 刪除 Google Workspace 訂閱方案。

get

 取得 Google Workspace 訂閱方案的詳細資訊。

list

 列出 Google Workspace 訂閱方案。

patch

 更新或續訂 Google Workspace 訂閱方案。

reactivate

 重新啟用已停權的 Google Workspace 訂閱方案。