REST Resource: subscriptions

資源:Subscription

訂閱,可接收 Google Workspace 資源相關活動。如要進一步瞭解訂閱項目,請參閱 Google Workspace 事件 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 訂閱方案。