使用 Google Workspace Events API 訂閱活動

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

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

應用程式如何接收事件

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

插圖：Google Workspace Event API 如何傳送事件。

以下說明 Google Workspace Event API 如何透過訂閱傳送事件至應用程式：

  1. 您的應用程式會訂閱 Google Workspace 應用程式中的資源，例如 Google Chat 聊天室。
  2. 您訂閱的資源變更。
  3. Google Workspace 應用程式會將事件傳送至 Google Cloud Pub/Sub 中的主題，做為 Google Workspace 訂閱項目的通知端點。此事件包含資源變動的資料。
  4. 您的應用程式會處理含有該事件的 Google Cloud Pub/Sub 訊息，並視情況採取行動。

重要術語

以下是 Google Workspace Event 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 Event API 支援哪些 Google Workspace 資源，請參閱「支援的 Google Workspace 事件」一文。
事件類型
您想針對目標資源接收通知的變更類型。舉例來說，如果您已訂閱 Google Chat 聊天室，可以選擇是否接收該聊天室及其子項資源的相關事件，例如成員資格和訊息。
通知端點
Google Workspace 訂閱項目接收事件的端點。Google Workspace Event 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
  • 訊息
  • 頻道會員
  • 回應
  • 空間

詳情請參閱「訂閱 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 Event 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 通訊協定繫結。