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

前提条件

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 Chat 聊天室是指经过身份验证的用户所属的 Chat 聊天室，以便订阅。用户必须通过其 Google Workspace 或 Google 帐号成为聊天室成员（不支持通过 Google 群组成为聊天室成员的用户）。

  • 通过身份验证的用户是所有者的会议空间，可以订阅 Google Meet 会议空间。如需创建聊天室，请参阅 Google Meet 文档中的使用会议聊天室。

  • 如需订阅 Google Meet 用户，需要 Cloud Identity API 的 user ID。

• 已启用结算功能的 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 凭据

请选择您的应用类型，了解有关如何创建 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. 点击 OK。新创建的凭据会显示在 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. 点击 OK。新创建的凭据会显示在“OAuth 2.0 客户端 ID”下方。

iOS

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

   进入“凭据”页面

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

桌面应用

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

   进入“凭据”页面

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

电视和受限输入设备

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

   进入“凭据”页面

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

通用 Windows 平台 (UWP)

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

   进入“凭据”页面

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

下载客户端密钥 JSON 文件

客户端密钥文件是您的应用在提供凭据时可以引用的 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 Events API 的 subscriptions.create() 方法来创建 Subscription 资源。您指定了以下字段：

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

如需创建 Google Workspace 订阅，请执行以下操作：

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 文档。

相关主题

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