创建 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. 您可以选择配置如何将事件推送到应用的端点，以便应用可以处理事件并在必要时采取行动。

注意： Google Drive API 的事件功能是 Google Workspace 开发者预览计划的一部分，该计划可让您提前体验某些功能。此处列出的代码示例不适用于这些事件。

前提条件

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 脚本自动创建的默认项目。
  • 对于您为配置 OAuth 同意屏幕而添加的任何范围，您还必须将这些范围添加到 Apps 脚本项目中的 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 脚本，则可以跳过此步骤。

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

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

Web 应用

1. 在 Google Cloud 控制台中，依次前往“菜单”图标 > > 客户端。

   前往“客户端”页面

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

   新创建的凭据会显示在 OAuth 2.0 客户端 ID 下。

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

Android

1. 在 Google Cloud 控制台中，依次前往“菜单”图标 > > 客户端。

   前往“客户端”页面

2. 点击创建客户端。
3. 依次点击应用类型 > Android。
4. 在“名称”字段中，输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。
5. 在“软件包名称”字段中，输入 AndroidManifest.xml 文件中的软件包名称。
6. 在“SHA-1 证书指纹”字段中，输入您生成的 SHA-1 证书指纹。
7. 点击创建。

   新创建的凭据会显示在“OAuth 2.0 客户端 ID”下。

iOS

1. 在 Google Cloud 控制台中，依次前往“菜单”图标 > > 客户端。

   前往“客户端”页面

2. 点击创建客户端。
3. 依次点击应用类型 > iOS。
4. 在“名称”字段中，输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。
5. 在“软件包 ID”字段中，输入应用的 Info.plist 文件中列出的软件包标识符。
6. 可选：如果您的应用在 Apple App Store 中上架，请输入 App Store ID。
7. 可选：在“团队 ID”字段中，输入由 Apple 生成并分配给您的团队的唯一字符串，该字符串包含 10 个字符。
8. 点击创建。

   新创建的凭据会显示在“OAuth 2.0 客户端 ID”下。

Chrome 应用

1. 在 Google Cloud 控制台中，依次前往“菜单”图标 > > 客户端。

   前往“客户端”页面

2. 点击创建客户端。
3. 依次点击应用类型 > Chrome 扩展程序。
4. 在“名称”字段中，输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。
5. 在“商品 ID”字段中，输入应用的唯一 32 字符 ID 字符串。您可以在应用的 Chrome 应用商店网址和 Chrome 应用商店开发者信息中心中找到此 ID 值。
6. 点击创建。

   新创建的凭据会显示在“OAuth 2.0 客户端 ID”下。

桌面应用

1. 在 Google Cloud 控制台中，依次前往“菜单”图标 > > 客户端。

   前往“客户端”页面

2. 点击创建客户端。
3. 依次点击应用类型 > 桌面应用。
4. 在名称字段中，输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。
5. 点击创建。

   新创建的凭据会显示在“OAuth 2.0 客户端 ID”下。

电视和受限输入设备

1. 在 Google Cloud 控制台中，依次前往“菜单”图标 > > 客户端。

   前往“客户端”页面

2. 点击创建客户端。
3. 依次点击应用类型 > 电视和有限输入设备。
4. 在“名称”字段中，输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。
5. 点击创建。

   新创建的凭据会显示在“OAuth 2.0 客户端 ID”下。

通用 Windows 平台 (UWP)

1. 在 Google Cloud 控制台中，依次前往“菜单”图标 > > 客户端。

   前往“客户端”页面

2. 点击创建客户端。
3. 依次点击应用类型 > 通用 Windows 平台 (UWP)。
4. 在“名称”字段中，输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。
5. 在“商店 ID”字段中，输入应用的唯一 12 字符 Microsoft Store ID 值。您可以在应用的 Microsoft Store 网址和合作伙伴中心中找到此 ID。
6. 点击创建。

   新创建的凭据会显示在“OAuth 2.0 客户端 ID”下。

下载客户端密钥 JSON 文件

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

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

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

   转到“凭据”页面

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

3. 点击下载 JSON。

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

创建并订阅 Pub/Sub 主题

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

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

注意： Google Workspace Events API 使用排序键，以便您的应用按消息发布顺序接收消息。我们建议避免使用消息存储政策。发布到具有此类政策的主题的事件很可能会失败，因为政策中的区域可能与事件来源不匹配。

如需创建和订阅 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. 对于聊天活动，请参阅[e-mail]。
      2. 开发者预览版：对于云端硬盘事件，[e-mail]。
      3. 对于 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]。
     • 开发者预览版：如需接收来自云端硬盘的事件，请使用 [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 用户。	订阅仅接收有关授权订阅的用户的事件。用户无法代表其他用户授权订阅。

确定云端硬盘的目标资源

开发者预览版：作为 Google Workspace 开发者预览版计划的一部分提供，可抢先体验某些功能。

目标资源	格式	限制（如适用）
文件	//googleapis.com/drive/v3/files/FILE 其中，FILE 是 Drive API files 资源的 资源名称中的 ID。您可以从文件的网址中获取该 ID，也可以使用 files.list 方法获取该 ID。	授权订阅的用户必须拥有订阅中相对于订阅事件的文件权限。
共享云端硬盘	//googleapis.com/drive/v3/drives/DRIVE 其中，DRIVE 是 Drive API drives 资源的 资源名称中的 ID。您可以从云端硬盘的网址中获取该 ID，也可以使用 drives.list 方法获取该 ID。	相应订阅仅接收用户通过其 Google Workspace 账号或 Google 账号成为成员的共享云端硬盘中内容的事件。

确定 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：一个数组，包含您希望接收的有关资源的一个或多个事件类型。例如，如果您的应用只需要了解发布到 Google 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('credentials.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/PROJECT_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 观察会议事件
• 订阅
• 列出订阅
• 更新或续订订阅
• 解决错误并重新激活订阅
• 删除订阅