REST Resource: subscriptions

資源：Subscription

訂閱項目，用於接收有關 Google Workspace 資源的事件。如要進一步瞭解訂閱項目，請參閱 Google Workspace Events 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 訂閱方案。