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

使用 Google Workspace Events API 訂閱活動

本頁提供 Google Workspace 事件 API 總覽，並說明如何使用 API 訂閱 Google Workspace 中的事件。

Google Workspace 事件代表 Google Workspace 資源的變更，例如建立、更新或刪除資源時。應用程式可以訂閱 Google Workspace 資源，讓您接收感興趣的相關活動。

應用程式如何接收事件

如要讓應用程式接收 Google Workspace 事件，請使用 Google Workspace Events API 建立 Google Workspace 資源的訂閱項目。

插圖：Google Workspace Events API 提供事件的方式。 — **圖 1.**範例說明 Google Workspace Events API 如何將事件傳送至 Chat 應用程式。

在以下範例中，以下是 Google Workspace Events API 如何透過訂閱項目，將事件傳送至 Google Chat 應用程式：

訂閱 Chat 聊天室的 Chat 應用程式。
Chat 聊天室有所變更。舉例來說，聊天室中會有新訊息。
Chat 會將事件傳送至 Google Cloud Pub/Sub 中的主題，該主題會做為訂閱項目的通知端點。該事件包含異動項目的相關資料。舉例來說，如果事件與新訊息有關，事件會包含所建立 Message 資源的詳細資料。
Chat 應用程式會處理包含該事件的 Google Cloud Pub/Sub 訊息，並在必要時採取行動。

重要術語

以下是 Google Workspace 事件 API 的常用詞彙清單：

Google Workspace 活動

Google Workspace 資源變更。事件會使用 CloudEvents 規格設定格式，可以是訂閱事件或生命週期事件：

訂閱事件: 您正在監控的 Google Workspace 資源變更，例如 Google Chat 聊天室中的新訊息。您可以指定對於已變更資源要接收的詳細資料。詳情請參閱「Google Workspace 事件結構」。
生命週期事件: 關於 Google Workspace 訂閱方案的活動。生命週期事件可以通知您問題和訂閱狀態，避免缺少訂閱事件。根據預設，訂閱項目一律會接收生命週期事件。詳情請參閱「Google Workspace 訂閱方案的生命週期事件」。

Google Workspace 訂閱方案

監控 Google Workspace 應用程式資源的具名實體。訂閱項目以 Subscription 資源表示。訂閱項目的定義如下：

目標資源: 您要監控的 Google Workspace 資源。這項資源會顯示在 Google Workspace 訂閱方案的 targetResource 欄位中。每個訂閱項目只能監控一項資源。如要查看 Google Workspace 事件 API 支援哪些 Google Workspace 資源，請參閱「支援的 Google Workspace 事件」一文。
事件類型: 接收目標資源相關通知的變更類型。舉例來說，如果您已訂閱 Google Chat 聊天室，即可選擇是否要接收與聊天室及其子資源 (例如成員資格和訊息) 相關的事件。
通知端點: Google Workspace 訂閱方案接收事件的端點。Google Workspace Events API 支援使用 Google Cloud Pub/Sub 主題做為通知端點。如要進一步瞭解如何使用 Google Cloud Pub/Sub，請參閱 Google Cloud Pub/Sub 說明文件。
酬載選項: 您想針對已變更資源接收的事件資料。

支援的 Google Workspace 事件

應用程式可接收事件的事件取決於訂閱項目的目標資源。下表顯示了每個可能的目標資源支援的事件。

目標資源	格式	支援的事件	限制 (如適用)
Google Chat
Google Chat 聊天室	如何訂閱特定聊天室： `//chat.googleapis.com/spaces/SPACE_ID` 如要訂閱使用者所屬的所有聊天室： `//chat.googleapis.com/spaces/-`	訊息頻道會員回應空格詳情請參閱「訂閱 Google Chat 事件」。	授權訂閱的 Google Chat 使用者必須是透過個人 Google Workspace 或 Google 帳戶加入的聊天室。
Google Chat 使用者	`//cloudidentity.googleapis.com/users/USER_ID`	頻道會員詳情請參閱「訂閱 Google Chat 事件」。	訂閱項目只會收到授權使用者的相關事件。使用者無法代表其他使用者授權訂閱項目。
Google Meet
Google Meet 會議空間	`//meet.googleapis.com/spaces/SPACE_ID`	會議參與者工作階段錄音檔轉錄稿詳情請參閱「訂閱 Google Meet 活動」。
Google Meet 使用者	`//cloudidentity.googleapis.com/users/USER_ID`	會議參與者工作階段錄音檔轉錄稿詳情請參閱「訂閱 Google Meet 活動」。	訂閱會收到有關會議空間的事件，且使用者屬於下列其中一種：會議空間的擁有者。與會議空間相關聯的 Google 日曆活動發起人。

Google Workspace 事件結構

Google Workspace 事件遵循 CloudEvents 規格，這是描述事件資料的業界標準。Google Workspace 事件包含下列事件：

CloudEvent 的屬性。
因事件而變更的 Google Workspace 資源資料

以下章節將說明 Google Workspace 事件的屬性和資料結構。

CloudEvent 屬性

Google Workspace 事件包含下列必要的 CloudEvents 屬性：

屬性	說明	範例
`datacontenttype`	在事件中傳遞的資料類型。	`application/json`
`id`	CloudEvent 的 ID。	`spaces/AAAABBBBBBB/spaceEvents/ABCDEFGHIJKLMNO`
`source`	事件的來源。如果是 Google Workspace 事件，則為訂閱項目的完整資源名稱。	`//workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg`
`specversion`	此事件使用的 CloudEvents 規格版本。	`1.0`
`subject`	發生事件的 Google Workspace 資源。	`//chat.googleapis.com/spaces/AAAABBBBBBB`
`time`	事件發生時間戳記，採用 RFC 3339 格式。	`2023-09-07T21:37:36.260127Z`
`type`	Google Workspace 事件的類型。	`google.workspace.chat.message.v1.created`

事件資料

事件資料是一個酬載，代表訂閱項目的目標資源變更，包括目標資源的子項資源。在訂閱項目中，您可以指定要在酬載中包含變更資源的資料，或只納入已變更資源的名稱。

舉例來說，如果訂閱了 Chat 聊天室，就能接收有關聊天室新訊息的事件。如為新訊息的事件，事件資料會包含已建立 Chat spaces.message 資源的酬載。

建立訂閱項目時，您可以指定應用程式接收的事件中要包含多少資源資料：

包含資源資料：包含資源變更的部分或所有欄位。如果選擇包含資源資料，訂閱時間最長可達 4 小時，若使用全網域委派功能，則訂閱時間上限為 24 小時。
排除資源資料：只包含已變更資源的名稱。您的訂閱期最長為 7 天。如要取得事件的詳細資料，您可以使用資源名稱查詢資源。

事件資料的選項會顯示在訂閱的 payloadOptions 欄位中。

將事件做為 Google Cloud Pub/Sub 訊息

Google Workspace Events API 訂閱項目使用 Google Cloud Pub/Sub 主題做為接收 Google Workspace 事件的通知端點。事件會編碼為 Google Cloud Pub/Sub 訊息。應用程式可以處理 Google Cloud Pub/Sub 訊息，以採取行動或回應事件。

下列範例顯示 Google Cloud Pub/Sub 訊息，其中包含與 Chat 聊天室中更新訊息相關的事件：

 {
    "message":
    {
        "attributes":
        {
            "ce-datacontenttype": "application/json",
            "ce-id": "spaces/SPACE_ID/spaceEvents/SPACE_EVENT_ID",
            "ce-source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
            "ce-specversion": "1.0",
            "ce-subject": "//chat.googleapis.com/spaces/SPACE_ID",
            "ce-time": "2023-09-07T21:37:53.274191Z",
            "ce-type": "google.workspace.chat.message.v1.updated"
        },
        "data": "EVENT_DATA",
        "messageId": "PUBSUB_MESSAGE_ID",
        "orderingKey": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
        "publishTime": "2023-09-07T21:37:53.713Z"
    }
}

請注意下列欄位：

attributes：CloudEvent 的屬性，包括事件類型。在這個情況下，事件是關於聊天室中的更新訊息。
data：事件資料，包含更新後的 spaces.message 資源相關詳細資料，格式為 Base64 編碼字串。
messageId：Google Cloud Pub/Sub 訊息的 ID。

如要進一步瞭解如何在 Google Cloud Pub/Sub 訊息中指定 CloudEvents，請參閱適用於 CloudEvents 的 Google Cloud Pub/Sub 通訊協定繫結。