使用 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. 聊天室會變更。例如有人在聊天室中張貼新訊息。
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 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，請參閱「CloudEvents 的 Google Cloud Pub/Sub 通訊協定繫結」。

相關主題

• 訂閱 Google Chat 事件
• 訂閱 Google Meet 活動
• Google Workspace 訂閱項目的生命週期事件
• 選擇 Google Workspace Events API 範圍
• 建立 Google Workspace 訂閱