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 subscription_options can be only one of the following:
  "driveOptions": {
    object (DriveOptions)
  }
  // End of list of possible types for union field subscription_options.

  // Union field authority_info can be only one of the following:
  "userAuthority": string,
  "serviceAccountAuthority": string
  // End of list of possible types for union field authority_info.

  // 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 和 Google 雲端硬碟事件。
notificationEndpoint

object (NotificationEndpoint)

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

enum (State)

僅供輸出。訂閱狀態。判斷訂閱項目是否可以接收事件，並將事件傳送至通知端點。
suspensionReason

enum (ErrorType)

僅供輸出。導致訂閱方案停權的錯誤。

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

string

僅供輸出。授權建立訂閱方案的使用者。

使用者授權訂閱時，這個欄位和 userAuthority 欄位的值相同，格式如下：

格式：users/{user}

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

Chat 應用程式授權訂閱時，只有 serviceAccountAuthority 欄位會填入資料，這個欄位則會留空。
createTime

string (Timestamp format)

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

string (Timestamp format)

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

boolean

僅供輸出。如果為 true，表示系統正在更新訂閱方案。
etag

string

(選用步驟) 這個檢查碼是由伺服器根據其他欄位的值計算得出，可能會在更新要求中傳送，確保用戶端在繼續操作前擁有最新值。
聯集欄位 subscription_options。Google Workspace 訂閱方案的特定目標資源可使用其他訂閱方案。subscription_options 只能是下列其中一項：
driveOptions

object (DriveOptions)

(選用步驟) 僅適用於雲端硬碟資源訂閱的功能。
聯集欄位 authority_info。授權建立訂閱項目的身分。authority_info 只能是下列其中一項：
userAuthority

string

僅供輸出。授權建立訂閱方案的使用者。使用者必須能查看 targetResource。

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

格式：users/{user}
serviceAccountAuthority

string

僅供輸出。用於授權建立訂閱項目的服務帳戶。這個服務帳戶必須屬於您建立這項訂閱方案的 Google Cloud 專案。

格式：projects/{projectId}/serviceAccounts/{service_account_id}

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

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

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

訂閱方案到期後，系統會自動刪除。您會在訂閱方案到期前 12 小時和 1 小時收到生命週期事件。notification_endpoint詳情請參閱「接收及回應生命週期事件」。

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

string (Timestamp format)

預設值不得為空。訂閱方案到期時間的時間戳記 (以世界標準時間為準)。不論輸入什麼內容，這項資訊一律會顯示在輸出內容中。
ttl

string (Duration format)

僅限輸入。訂閱的存留時間 (TTL) 或時間長度。如果未指定或設為 0，則使用最長可能的時間長度。

DriveOptions

提供更多支援選項，可放送雲端硬碟事件。

JSON 表示法 
{
  "includeDescendants": boolean
}
欄位
includeDescendants

boolean

(選用步驟) 不可變更。訂閱 Google 雲端硬碟事件時，是否要接收目標資料夾或共用雲端硬碟子項的事件。

  • 如果為 false，訂閱項目只會接收指定為 targetResource 的資料夾或共用雲端硬碟變更事件。
  • 如果值為 true，則 file 資源的 mimeType 欄位必須設為 application/vnd.google-apps.folder。

詳情請參閱「Google 雲端硬碟事件類型」。

PayloadOptions

關於要在事件酬載中加入哪些資料的選項。僅支援 Google Chat 和 Google 雲端硬碟事件。

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

不可變更。接收訂閱項目事件的 Pub/Sub 主題。

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

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

注意：Google Workspace Events API 會使用排序鍵，確保事件順序正確。如果 Cloud Pub/Sub 主題的訊息儲存政策已設定為排除最接近的 Google Cloud 區域，則使用排序鍵發布事件會失敗。

主題收到事件時，事件會編碼為 Pub/Sub 訊息。詳情請參閱「Google Cloud Pub/Sub Protocol Binding for CloudEvents」。

州

訂閱項目的可能狀態。

列舉
STATE_UNSPECIFIED 預設值。這個值不會使用。
ACTIVE 訂閱項目處於有效狀態，可接收事件並傳送至通知端點。
SUSPENDED 訂閱項目發生錯誤，因此無法接收事件。如要找出錯誤，請查看 suspensionReason 欄位。
DELETED 訂閱項目已刪除。

ErrorType

訂閱方案可能發生的錯誤。

列舉
ERROR_TYPE_UNSPECIFIED 預設值。這個值不會使用。
USER_SCOPE_REVOKED 授權使用者已撤銷一或多個 OAuth 範圍的授權。如要進一步瞭解 Google Workspace 的授權，請參閱「設定 OAuth 同意畫面」。
APP_SCOPE_REVOKED 網域管理員已撤銷應用程式的一或多個 OAuth 範圍授權。
RESOURCE_DELETED 訂閱的目標資源已不存在。
USER_AUTHORIZATION_FAILURE 授權建立訂閱項目的使用者已無法存取訂閱項目的目標資源。
APP_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 訂閱方案。