创建 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. 调用 Google Workspace Events API 的 create() 调用 Subscription 资源。
4. 测试您的 Google Workspace 订阅，以确保您的 Pub/Sub 主题接收您订阅的事件。
5. （可选）配置如何将事件推送到应用的端点， 您的应用可以处理相应事件，并根据需要采取措施。

前提条件

Apps 脚本

• 如需使用本指南中的 Google Cloud CLI 命令，请执行以下操作： <ph type="x-smartling-placeholder">
  </ph>
  1. 安装 Google Cloud CLI。
  2. 收件人：<ph type="x-smartling-placeholder"></ph> 初始化 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 命令，请执行以下操作： <ph type="x-smartling-placeholder">
  </ph>
  1. 安装 Google Cloud CLI。
  2. 收件人：<ph type="x-smartling-placeholder"></ph> 初始化 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 项目中启用这些 API。 您可以在单个 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 控制台中，依次点击“菜单”图标 &gt; API 和服务 &gt; 凭据。

   进入“凭据”页面

2. 依次点击创建凭据 &gt; OAuth 客户端 ID。
3. 点击应用类型 &gt; Web 应用。
4. 在名称字段中，输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。
5. 添加与您的应用相关的已获授权的 URI： <ph type="x-smartling-placeholder">
   </ph>
   • 客户端应用 (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 控制台中，依次点击“菜单”图标 &gt; API 和服务 &gt; 凭据。

   进入“凭据”页面

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

iOS

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

   进入“凭据”页面

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

Chrome 应用

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

   进入“凭据”页面

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

桌面应用

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

   进入“凭据”页面

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

电视和受限输入设备

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

   进入“凭据”页面

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

通用 Windows 平台 (UWP)

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

   进入“凭据”页面

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

下载客户端密钥 JSON 文件

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

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

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

   转到“凭据”页面

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 资源。目标 资源以订阅的 targetResource 字段表示，采用 完整资源名称。例如，对于监控 Google Chat 聊天室 (spaces/AAAABBBBBBB)，“targetResource”的值为 //chat.googleapis.com/spaces/AAAABBBBBBB。

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

为 Chat 确定目标资源

目标资源	格式	限制
空格	//chat.googleapis.com/spaces/SPACE 其中 SPACE 是 资源名称。space 您可以从聊天室的网址获取该 ID，也可以使用 <ph type="x-smartling-placeholder"></ph> spaces.list() 方法。	对订阅进行授权的 Chat 用户必须符合以下条件 通过 Google Workspace 或 Google Workspace 成为聊天室成员 账号。
用户的所有聊天室	//chat.googleapis.com/spaces/-	订阅仅接收用户所在聊天室的事件 通过 Google Workspace 或 Google 账号向成员授予相应权限。
用户	//cloudidentity.googleapis.com/users/USER 其中 USER 是 资源名称。user 有关详情，请参阅 标识并指定 Google Chat 用户。	订阅仅接收 对订阅进行了授权。用户无法在以下设备上授权订阅： 代表其他用户。

为 Meet 确定目标资源

目标资源	格式	限制（如适用）
会议空间	//meet.googleapis.com/spaces/SPACE 其中 SPACE 是 资源名称。space 有关详情，请参阅 如何 Meet 可识别会议空间。
用户	//cloudidentity.googleapis.com/users/USER 其中 USER 是 signedinUser.user Meet REST API participant资源的字段。 有关详情，请参阅 与参与者协作。	订阅会收到关于会议空间的事件， user 是以下类型之一： 会议空间的所有者。 组织者 与会议空间关联的 Google 日历活动的名称。

创建 Google Workspace 订阅

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

• targetResource：您在 上一部分，使用其完整资源名称进行格式设置。
• 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 的 Google Chat 聊天室 AAAABBBB，请使用 //chat.googleapis.com/spaces/AAAABBBB。
   • EVENT_TYPES：一个或多个事件类型 在目标资源中订阅。格式为 字符串数组，例如 'google.workspace.chat.message.v1.created'。
   • TOPIC_NAME：Cloud Pub/Sub 主题的全名， 您在 Cloud 项目中创建的应用。格式为 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 的 Google Chat 聊天室 AAAABBBB，请使用 //chat.googleapis.com/spaces/AAAABBBB。
   • EVENT_TYPES：一个或多个事件类型 在目标资源中订阅。格式为 字符串数组，例如 'google.workspace.chat.message.v1.created'。
   • TOPIC_NAME：Cloud Pub/Sub 主题的全名， 您在 Cloud 项目中创建的应用。格式为 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 订阅。例如，如果您订阅了新的 消息，请向聊天室发布消息。

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

注意 ：您无法将 Apps 脚本项目设置为推送传送 Pub/Sub 中的端点。将 Pub/Sub 消息推送到 Apps 脚本 则必须将脚本作为 Web 应用。

相关主题

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