创建 Google Workspace 订阅

本页介绍了如何使用 Google Workspace Events API 创建 Google Workspace 资源的订阅。通过 Google Workspace 订阅，您的应用可以接收有关 Google Workspace 事件的信息，这些事件代表 Google Workspace 资源的更改。如需了解 Google Workspace Events API 支持哪些资源和事件类型，请参阅 Google Workspace Events API 概览。

本页面介绍了创建 Google Workspace 订阅的以下步骤：

1. 设置环境。
2. 创建并订阅 Google Cloud Pub/Sub 主题。您可以将此主题用作端点来接收 Google Workspace 事件。
3. 对 Subscription 资源调用 Google Workspace Events API 的 create() 方法。
4. 测试您的 Google Workspace 订阅，确保您的 Pub/Sub 主题会收到您订阅的事件。
5. 您可以选择配置如何将事件推送到应用的端点，以便应用能够处理事件，并在必要时采取措施。

前提条件

Apps 脚本

• 如需使用本指南中的 Google Cloud CLI 命令，请执行以下操作：
  1. 安装 Google Cloud CLI。
  2. 如需 初始化 gcloud CLI，请运行以下代码：

    gcloud init
    

• 已启用结算功能的 Google Cloud 项目。对于 Chat 订阅，您还必须在 Cloud 项目中启用 Chat API，并配置应用名称、头像网址和说明字段。如需了解详情，请参阅构建 Google Chat 应用。
• 需要使用为应用配置的 OAuth 同意屏幕进行用户身份验证。在配置同意屏幕时，您必须指定一个范围，以支持订阅的每种事件类型。如需配置意见征求页面并确定所需的范围，请参阅选择范围。

• Apps 脚本项目：
  • 使用您的 Google Cloud 项目，而不是 Apps Script 自动创建的默认项目。
  • 对于您添加以配置 OAuth 同意屏幕的任何范围，您还必须将这些范围添加到 Apps Script 项目中的 appsscript.json 文件。 例如：

  "oauthScopes": [
    "https://www.googleapis.com/auth/chat.messages.readonly"
  ]
      

  • 启用 Google Workspace Events 高级服务。

Python

• Python 3.6 或更高版本
• pip 软件包管理工具
• 最新的 Python 版 Google 客户端库。如需安装或更新这些软件包，请在命令行界面中运行以下命令：

    pip3 install --upgrade google-api-python-client google-auth-oauthlib
    

• 如需使用本指南中的 Google Cloud CLI 命令，请执行以下操作：
  1. 安装 Google Cloud CLI。
  2. 如需 初始化 gcloud CLI，请运行以下代码：

    gcloud init
    

• 已启用结算功能的 Google Cloud 项目。对于 Chat 订阅，您还必须在 Cloud 项目中启用 Chat API，并配置应用名称、头像网址和说明字段。如需了解详情，请参阅构建 Google Chat 应用。
• 需要使用为应用配置的 OAuth 同意屏幕进行用户身份验证。在配置同意屏幕时，您必须指定一个范围，以支持订阅的每种事件类型。如需配置意见征求页面并确定所需的范围，请参阅选择范围。

设置环境

以下部分介绍了如何在创建 Google Workspace 订阅之前设置环境。

启用 Google Workspace Events API 和 Google Cloud Pub/Sub API

在使用 Google API 之前，您需要先在 Google Cloud 项目中启用它们。您可以在单个 Google Cloud 项目中启用一个或多个 API。

Google Cloud 控制台

在 Google Cloud 控制台中，打开应用的 Google Cloud 项目，然后启用 Google Workspace Events API 和 Pub/Sub API：

启用 API

gcloud

1. 在工作目录中，登录您的 Google 账号：

   gcloud auth login

2. 将您的项目设置为应用的 Cloud 项目：

   gcloud config set project PROJECT_ID

   将 PROJECT_ID 替换为应用的 Cloud 项目的项目 ID。

3. 启用 Google Workspace Events API 和 Google Cloud Pub/Sub API：

   gcloud services enable pubsub.googleapis.com workspaceevents.googleapis.com

创建 OAuth 客户端 ID 凭据

注意 ：如果您使用的是 Apps Script，则可以跳过此步骤。

选择您的应用类型，查看有关如何创建 OAuth 客户端 ID 的具体说明：

注意 ：如需运行本指南中的代码示例，请选择桌面应用，然后按照说明操作。

Web 应用

1. 在 Google Cloud 控制台中，依次选择“菜单”图标 > API 和服务 > 凭据。

   进入“凭据”页面

2. 依次点击创建凭据 > OAuth 客户端 ID。
3. 依次点击应用类型 > Web 应用。
4. 在名称字段中，输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。
5. 添加与您的应用相关的已获授权 URI：
   • 客户端应用 (JavaScript) - 在已获授权的 JavaScript 来源下，点击添加 URI。然后，输入要用于浏览器请求的 URI。这用于标识您的应用可以从哪些网域向 OAuth 2.0 服务器发送 API 请求。
   • 服务器端应用（Java、Python 等） - 在已获授权的重定向 URI 下，点击添加 URI。然后，输入 OAuth 2.0 服务器可以向其发送响应的端点 URI。
6. 点击创建。系统随即会显示“OAuth 客户端已创建”屏幕，其中显示您的新客户端 ID 和客户端密钥。

   记下客户端 ID。客户端密钥不适用于 Web 应用。

7. 点击确定。新创建的凭据会显示在 OAuth 2.0 客户端 ID 下。

Android

1. 在 Google Cloud 控制台中，依次选择“菜单”图标 > API 和服务 > 凭据。

   进入“凭据”页面

2. 依次点击创建凭据 > OAuth 客户端 ID。
3. 依次点击应用类型 > Android。
4. 在“名称”字段中，输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。
5. 在“软件包名称”字段中，输入 AndroidManifest.xml 文件中的软件包名称。
6. 在“SHA-1 证书指纹”字段中，输入您生成的 SHA-1 证书指纹。
7. 点击创建。系统随即会显示“OAuth 客户端已创建”屏幕，其中显示您的新客户端 ID。
8. 点击确定。新创建的凭据会显示在“OAuth 2.0 客户端 ID”下。

iOS

1. 在 Google Cloud 控制台中，依次选择“菜单”图标 > API 和服务 > 凭据。

   进入“凭据”页面

2. 依次点击创建凭据 > OAuth 客户端 ID。
3. 依次点击应用类型 > iOS。
4. 在“名称”字段中，输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。
5. 在“Bundle ID”字段中，输入应用的 Info.plist 文件中列出的软件包标识符。
6. 可选：如果您的应用在 Apple App Store 中展示，请输入 App Store ID。
7. 可选：在“团队 ID”字段中，输入由 Apple 生成并分配给您的团队的唯一字符串（包含 10 个字符）。
8. 点击创建。系统随即会显示“OAuth 客户端已创建”屏幕，其中显示您的新客户端 ID 和客户端密钥。
9. 点击确定。新创建的凭据会显示在“OAuth 2.0 客户端 ID”下。

Chrome 应用

1. 在 Google Cloud 控制台中，依次选择“菜单”图标 > API 和服务 > 凭据。

   进入“凭据”页面

2. 依次点击创建凭据 > OAuth 客户端 ID。
3. 依次点击应用类型 > Chrome 应用。
4. 在“名称”字段中，输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。
5. 在“应用 ID”字段中，输入应用的 32 个字符的唯一 ID 字符串。您可以在应用的 Chrome 应用商店网址和 Chrome 应用商店开发者信息中心中找到此 ID 值。
6. 点击创建。系统随即会显示“OAuth 客户端已创建”屏幕，其中会显示您的新客户端 ID 和客户端密钥。
7. 点击确定。新创建的凭据会显示在“OAuth 2.0 客户端 ID”下。

桌面应用

1. 在 Google Cloud 控制台中，依次选择“菜单”图标 > API 和服务 > 凭据。

   进入“凭据”页面

2. 依次点击创建凭据 > OAuth 客户端 ID。
3. 依次点击应用类型 > 桌面应用。
4. 在名称字段中，输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。
5. 点击创建。系统随即会显示“OAuth 客户端已创建”屏幕，其中会显示您的新客户端 ID 和客户端密钥。
6. 点击确定。新创建的凭据会显示在 OAuth 2.0 客户端 ID 下。

电视和受限输入设备

1. 在 Google Cloud 控制台中，依次选择“菜单”图标 > API 和服务 > 凭据。

   进入“凭据”页面

2. 依次点击创建凭据 > OAuth 客户端 ID。
3. 依次点击应用类型 > 电视和输入受限设备。
4. 在“名称”字段中，输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。
5. 点击创建。系统随即会显示“OAuth 客户端已创建”屏幕，其中会显示您的新客户端 ID 和客户端密钥。
6. 点击确定。新创建的凭据会显示在“OAuth 2.0 客户端 ID”下。

通用 Windows 平台 (UWP)

1. 在 Google Cloud 控制台中，依次选择“菜单”图标 > API 和服务 > 凭据。

   进入“凭据”页面

2. 依次点击创建凭据 > OAuth 客户端 ID。
3. 依次点击应用类型 > 通用 Windows 平台 (UWP)。
4. 在“名称”字段中，输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。
5. 在“商店 ID”字段中，输入应用的唯一 12 位字符 Microsoft 商店 ID 值。您可以在应用的 Microsoft Store 网址和 Partner Center 中找到此 ID。
6. 点击创建。系统随即会显示“OAuth 客户端已创建”屏幕，其中显示您的新客户端 ID 和客户端密钥。
7. 点击确定。新创建的凭据会显示在“OAuth 2.0 客户端 ID”下。

下载客户端密钥 JSON 文件

注意 ：如果您使用的是 Apps Script，则可以跳过此步骤。

客户端密钥文件是 OAuth 客户端 ID 凭据的 JSON 表示法，您的应用在提供凭据时可以引用该凭据。

1. 在 Google Cloud 控制台中，依次选择“菜单”图标 > API 和服务 > 凭据。

   转到“凭据”页面

2. 在 OAuth 2.0 客户端 ID 下，点击您创建的客户端 ID。

3. 点击下载 JSON。

4. 将该文件另存为 client_secrets.json。

创建和订阅 Pub/Sub 主题

在本部分中，您将创建一个 Pub/Sub 主题并订阅该主题。您的 Pub/Sub 主题充当通知端点，您的 Google Workspace 订阅会在此接收事件。

如需详细了解如何创建和管理 Pub/Sub 主题，请参阅 Pub/Sub 文档。

如需创建 Pub/Sub 主题并订阅该主题，请执行以下操作：

Google Cloud 控制台

1. 在 Google Cloud 控制台中，前往 Pub/Sub 页面：

   前往 Google Cloud Pub/Sub

   确保已选择应用的 Cloud 项目。

2. 点击 创建主题，然后执行以下操作：

   1. 输入主题的名称，例如 workspace-events-topic。
   2. 让添加默认订阅保持选中状态。Pub/Sub 会为此默认订阅命名，名称与主题的名称类似，例如 workspace-events-topic-sub。
   3. 可选：更新或配置主题的其他属性。

3. 点击创建。完整主题名称的格式为 projects/PROJECT_ID/topics/TOPIC_ID。您将在后面的步骤中使用此全名。

4. 授予向您的主题发布 Pub/Sub 消息的权限：

   1. 在主题页面上，前往侧边栏并打开权限标签页。
   2. 点击添加主账号。
   3. 在添加主账号字段中，添加向您的订阅提交事件的 Google Workspace 应用的服务账号：
      1. 对于 Chat 事件，请使用 [e-mail]。
      2. 对于 Meet 活动，请参阅[e-mail]。
   4. 在分配角色菜单中，选择 Pub/Sub Publisher。
   5. 点击保存。更新主题的权限可能需要几分钟时间。

gcloud

1. 在 Cloud 项目中，运行以下命令创建一个主题：

   gcloud pubsub topics create TOPIC_ID

   将 TOPIC_ID 替换为主题的唯一 ID，例如 workspace-events-topic。

   输出会显示格式为 projects/PROJECT_ID/topics/TOPIC_ID 的完整主题名称。记下该名称，并确保 PROJECT_ID 的值为应用的 Cloud 项目 ID。您将在下一步中使用该主题名称，并在稍后创建 Google Workspace 订阅时使用该名称。

2. 授予向您的主题发布消息的权限：

   gcloud pubsub topics add-iam-policy-binding TOPIC_NAME --member='serviceAccount:GOOGLE_WORKSPACE_APPLICATION' --role='roles/pubsub.publisher'

   替换以下内容：

   • TOPIC_NAME：完整主题名称，即上一步的输出。格式为 projects/PROJECT_ID/topics/TOPIC_ID。

   • GOOGLE_WORKSPACE_APPLICATION：必须向您的订阅提交事件的 Google Workspace 应用：

     • 如需接收来自 Chat 的事件，请使用 [e-mail]。
     • 如需接收来自 Meet 的事件，请使用 [e-mail]。

   更新主题的权限可能需要几分钟时间。

3. 为该主题创建 Pub/Sub 订阅：

    gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME

   替换以下内容：

   • SUBSCRIPTION_NAME：订阅的名称，例如 workspace-events-subscription。
   • TOPIC_NAME：您在上一步中创建的主题的名称。

订阅 Google Workspace 资源

在本部分中，您将订阅要监控事件的 Google Workspace 资源。

选择并标识目标资源

在 Google Workspace 订阅中，目标资源是您要监控事件的 Google Workspace 资源。目标资源在订阅的 targetResource 字段中表示，格式为完整资源名称。例如，对于监控 Google Chat 聊天室 (spaces/AAAABBBBBBB) 的订阅，targetResource 的值为 //chat.googleapis.com/spaces/AAAABBBBBBB。

在创建订阅之前，请参阅以下部分，了解如何识别和设置目标资源的格式。

为 Chat 确定目标资源

目标资源	格式	限制
空格	//chat.googleapis.com/spaces/SPACE 其中，SPACE 是 Chat API space 资源的 资源名称中的 ID。 您可以从聊天室的网址中获取此 ID，也可以使用 spaces.list() 方法获取此 ID。	授权订阅的 Chat 用户必须通过其 Google Workspace 或 Google 账号成为聊天室的成员。
用户的所有聊天室	//chat.googleapis.com/spaces/-	订阅仅会接收用户通过 Google Workspace 账号或 Google 账号成为成员的聊天室的活动。
用户	//cloudidentity.googleapis.com/users/USER 其中，USER 是 Chat API user 资源的 资源名称中的 ID。 如需了解详情，请参阅识别和指定 Google Chat 用户。	该订阅仅会接收与授权订阅的用户相关的事件。用户无法代表其他用户授权订阅。

为 Meet 指定目标资源

目标资源	格式	限制（如果适用）
会议空间	//meet.googleapis.com/spaces/SPACE 其中，SPACE 是 Meet REST API space 资源的 资源名称中的 ID。 如需了解详情，请参阅Meet 如何识别会议空间。
用户	//cloudidentity.googleapis.com/users/USER 其中 USER 是 Meet REST API participant 资源的 signedinUser.user 字段中的 ID。 如需了解详情，请参阅与参与者互动。	该订阅会接收与用户具有以下任一身份的会议室相关的事件： 会议室的所有者。 与会议室关联的 Google 日历活动的组织者。

创建 Google Workspace 订阅

如需创建订阅，您可以使用 Google Workspace Events API 的 subscriptions.create() 方法创建 Subscription 资源。您需要指定以下字段：

• targetResource：您在上一部分中指定的 Google Workspace，格式为完整资源名称。
• eventTypes：您希望收到的与资源相关的一个或多个事件类型的数组。例如，如果您的应用只需要了解发布到 Chat 聊天室的新消息，则只需订阅有关创建的消息的事件即可。
• notificationEndpoint：Google Workspace 订阅提交事件的通知端点。您将使用在上一部分中创建的 Pub/Sub 主题。
• payloadOptions：用于指定要在事件载荷中包含多少资源数据的选项。此配置会影响订阅的到期时间。如需了解详情，请参阅事件数据。

如需创建 Google Workspace 订阅，请按以下步骤操作：

Apps 脚本

1. 在 Apps 脚本项目中，创建一个名为 createSubscription 的新脚本文件，并添加以下代码：

   function createSubscription() {
     // The Google Workspace resource to monitor for events.
     const targetResource = 'TARGET_RESOURCE';
   
     // The types of events to receive.
     const eventTypes = [EVENT_TYPES];
   
     // The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
     const pubsubTopic = 'TOPIC_NAME';
   
     // Whether to include resource data or not.
     const resourceData = RESOURCE_DATA;
   
     // Call the Workspace Events API using the advanced service.
     const response = WorkspaceEvents.Subscriptions.create({
       targetResource: targetResource,
       eventTypes: eventTypes,
       notificationEndpoint: {
         pubsubTopic: pubsubTopic,
       },
       payloadOptions: {
         includeResource: resourceData
       }
     });
     console.log(response);
   }
   

   替换以下内容：

   • TARGET_RESOURCE：您要订阅的 Google Workspace 资源，格式为其完整资源名称。例如，如需订阅聊天室 ID 为 AAAABBBB 的 Google Chat 聊天室，请使用 //chat.googleapis.com/spaces/AAAABBBB。
   • EVENT_TYPES：您要在目标资源中订阅的一个或多个事件类型。格式为字符串数组，例如 'google.workspace.chat.message.v1.created'。
   • TOPIC_NAME：您在 Cloud 项目中创建的 Pub/Sub 主题的完整名称。格式为 projects/PROJECT_ID/topics/TOPIC_ID。

   • RESOURCE_DATA：一个布尔值，用于指定订阅是否在载荷中包含资源数据：

     • True：包含所有资源数据。如需限制要包含的字段，请添加 fieldMask 字段，并为更改后的资源指定至少一个字段。只有对 Chat 资源的订阅支持包含资源数据。
     • False：不包括资源数据。

2. 如需创建 Google Workspace 订阅，请在 Apps 脚本项目中运行函数 createSubscription。

Python

1. 在工作目录中，创建一个名为 create_subscription.py 的文件，并添加以下代码：

   """Create subscription."""
   
   from google_auth_oauthlib.flow import InstalledAppFlow
   from googleapiclient.discovery import build
   
   # Specify required scopes.
   SCOPES = [SCOPES]
   
   # Authenticate with Google Workspace and get user authentication.
   flow = InstalledAppFlow.from_client_secrets_file('client_secrets.json', SCOPES)
   CREDENTIALS = flow.run_local_server()
   
   # The Google Workspace resource to monitor for events.
   TARGET_RESOURCE = 'TARGET_RESOURCE'
   
   # The types of events to receive.
   EVENT_TYPES = [EVENT_TYPES]
   
   # The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
   TOPIC = 'TOPIC_NAME'
   
   # Call the Workspace Events API using the service endpoint.
   service = build(
       'workspaceevents',
       'v1',
       credentials=CREDENTIALS,
   )
   
   BODY = {
       'target_resource': TARGET_RESOURCE,
       'event_types': EVENT_TYPES,
       'notification_endpoint': {'pubsub_topic': TOPIC},
       'payload_options': {'include_resource': RESOURCE_DATA},
   }
   response = service.subscriptions().create(body=BODY).execute()
   print(response)
   

   替换以下内容：

   • SCOPES：一个或多个OAuth 范围，用于支持订阅的每种事件类型。格式为字符串数组。如需列出多个镜重，请用英文逗号分隔。例如 'https://www.googleapis.com/auth/chat.spaces.readonly', 'https://www.googleapis.com/auth/chat.memberships.readonly'。
   • TARGET_RESOURCE：您要订阅的 Google Workspace 资源，格式为其完整资源名称。例如，如需订阅聊天室 ID 为 AAAABBBB 的 Google Chat 聊天室，请使用 //chat.googleapis.com/spaces/AAAABBBB。
   • EVENT_TYPES：您要在目标资源中订阅的一个或多个事件类型。格式为字符串数组，例如 'google.workspace.chat.message.v1.created'。
   • TOPIC_NAME：您在 Cloud 项目中创建的 Pub/Sub 主题的完整名称。格式为 projects/PROJECT_ID/topics/TOPIC_ID。

   • RESOURCE_DATA：一个布尔值，用于指定订阅是否在载荷中包含资源数据：

     • True：包含所有资源数据。如需限制要包含的字段，请添加 fieldMask 字段，并为更改后的资源指定至少一个字段。只有对 Chat 资源的订阅支持包含资源数据。
     • False：不包括资源数据。

2. 如需创建 Google Workspace 订阅，请在终端中运行以下命令：

   python3 create_subscription.py

Google Workspace Events API 会返回一个已完成的长时间运行的操作，其中包含您创建的 Subscription 资源的实例。

测试您的 Google Workspace 订阅

如需测试您是否正在接收 Google Workspace 事件，您可以触发事件并将消息拉取到 Pub/Sub 订阅。

如需测试您的 Google Workspace 订阅，请按以下步骤操作：

Google Cloud 控制台

1. 在 Google Workspace 订阅的目标资源中触发一种或多种类型的事件。例如，如果您已订阅 Chat 聊天室中的新消息，请向该聊天室发消息。

2. 在 Google Cloud 控制台中，前往 Pub/Sub 页面：

   转到“Pub/Sub”

   确保已选择应用的 Cloud 项目。

3. 在 Pub/Sub 菜单中，点击订阅。

4. 在表格中，找到您的主题的 Pub/Sub 订阅，然后点击订阅名称。

5. 点击消息标签页。

6. 点击拉取。事件生成 Pub/Sub 消息最长可能需要几分钟。

gcloud

1. 在 Google Workspace 订阅的目标资源中触发一种或多种类型的事件。例如，如果您已订阅 Chat 聊天室中的新消息，请在聊天室中发消息。

2. 运行以下命令：

   gcloud pubsub subscriptions pull PUBSUB_SUBSCRIPTION_NAME --format=json --limit=MESSAGE_COUNT --auto-ack

   替换以下内容：

   • PUBSUB_SUBSCRIPTION_NAME：您的 Pub/Sub 订阅的完整名称，格式为 projects/SUBSCRIPTION_ID/subscriptions/SUBSCRIPTION_ID。
   • MESSAGE_COUNT：您要拉取的 Pub/Sub 消息的数量上限。

   事件最多可能需要几分钟才能生成 Pub/Sub 消息。

对于您触发的每项 Google Workspace 事件，系统都会向包含该事件的 Pub/Sub 订阅提交一条消息。如需了解详情，请参阅以 Google Cloud Pub/Sub 消息的形式接收事件。

配置应用接收事件的方式

您创建的 Pub/Sub 订阅是基于拉取的。测试 Pub/Sub 订阅后，您可以更新传送类型，以更改应用接收事件的方式。例如，您可以将 Pub/Sub 订阅配置为推送传送类型，以便您的应用可以直接在应用端点接收事件。

如需了解如何配置 Pub/Sub 订阅，请参阅 Pub/Sub 文档。

注意 ：您无法在 Pub/Sub 中将 Apps 脚本项目设置为推送提交端点。如需将 Pub/Sub 消息推送到 Apps 脚本项目，您必须将脚本发布为Web 应用。

相关主题

• 教程：使用 Python 和 Google Meet REST API 监控会议事件
• 获取订阅
• 列出订阅
• 更新或续订
• 解决错误并重新激活订阅
• 删除订阅