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 訂閱方案。