使用 Google Workspace Events API 訂閱活動

本頁提供 Google Workspace Event API 的總覽並說明做法 您可以使用這個 API 訂閱 Google Workspace 中的事件。

Google Workspace 事件代表 Google Workspace 資源的變更。 例如建立、更新或刪除資源的時間應用程式可以訂閱 附加至 Google Workspace 資源，以便收到

應用程式如何接收事件

如要讓應用程式接收 Google Workspace 事件，請使用 可透過 Google Workspace 事件 API 建立 Google Workspace 訂閱 再複習一下，機構節點 是所有 Google Cloud Platform 資源的根節點

插圖：Google Workspace Events API 提供事件的方式。
圖 1.以下舉例說明 Google Workspace Events API 提供事件給 Chat 應用程式。

在以下範例中，以下是 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 事件 API：

Google Workspace 活動

Google Workspace 資源變更。事件的格式是 CloudEvents 可以是訂閱事件或 生命週期事件：

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

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

目標資源
您要監控的 Google Workspace 資源。 這項資源會顯示在targetResource Google Workspace 訂閱方案。每個訂閱項目只能 只能監控一項資源如要查看哪些 Google Workspace 資源 Google Workspace Events API 支援，請參閱 支援的 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 活動。

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 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 通訊協定繫結。