本頁面由 Cloud Translation API 翻譯而成。

REST Resource: subscriptions

資源：Subscription
- JSON 表示法
PayloadOptions
- JSON 表示法
NotificationEndpoint
- JSON 表示法
狀態
ErrorType
方法

資源：Subscription

訂閱後，即可接收 Google Workspace 資源的相關事件。如要進一步瞭解訂閱項目，請參閱 Google Workspace Events API 總覽。

JSON 表示法

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,
  "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`。如果省略，酬載會包含資源的所有欄位。如果您指定的欄位不存在於資源中，系統會忽略該欄位。

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」。

聯集欄位 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 同意畫面」。
`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 訂閱方案。

REST Resource: subscriptions

資源：Subscription

PayloadOptions

NotificationEndpoint

州

ErrorType

方法

`create`

`delete`

`get`

`list`

`patch`

`reactivate`