使用 Google Workspace Events API 訂閱活動

本頁提供 Google Workspace Events API 的概略說明，並說明如何使用該 API 訂閱 Google Workspace 中的事件。

Google Workspace 事件是指對 Google Workspace 資源進行的變更，例如建立、更新或刪除。應用程式可以訂閱 Google Workspace 資源，掌握您感興趣的相關事件資訊。

應用程式如何接收事件

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

在下列範例中，Google Workspace Events API 會透過訂閱功能，將事件傳送至 Google Chat 應用程式：

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

重要術語

以下列出 Google Workspace Events 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 Events 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 雲端硬碟事件
• 訂閱 Google Meet 活動

Google Workspace 事件的結構

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

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

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

CloudEvent 屬性

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

事件資料

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

舉例來說，如果您訂閱了 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，請參閱 Google Cloud Pub/Sub Protocol Binding for CloudEvents。

相關主題

• 選擇 Google Workspace Events API 範圍
• 建立 Google Workspace 訂閱方案