配置 Google Chat API

您创建的每个 Google Chat 应用都需要有自己的 Google Cloud 项目，并启用和配置 Chat API。

如需通过用户身份验证执行只读 API 调用（例如获取聊天室和列出消息），您只需启用该 API 并创建 OAuth 客户端即可。

如需执行创建、更新和删除 API 调用，或部署和测试互动式 Chat 应用（作为扩展 Chat 的 Google Workspace 插件构建），您还必须配置 Chat API。在 Chat API 配置设置中，您可以指定有关 Chat 应用的所有详细信息，包括其显示名称、头像、部署端点和互动功能。

前提条件

• 可访问 Google Chat 的 Google Workspace 商务版或企业版账号。
• 创建 Google Cloud 项目。
• 配置 OAuth 权限请求页面。
• 启用 Google Chat API。

为您的 Chat 应用选择显示名称、头像和说明

启用 Chat API 后，您需要配置 Chat 应用的详细信息，这些信息会向 Chat 中的用户显示，包括显示名称、头像和说明。这些详细信息仅会显示在 Chat 中。如需将 Chat 应用发布到 Marketplace，您还必须指定 Chat 应用的 Marketplace 商品详情中显示的详细信息。

在配置 Chat 应用之前，请准备好以下信息：

Chat 应用的名称、头像和说明会显示在 Chat 界面中。对于某些 Chat API 写入请求，Chat 会使用此信息来归因 Chat 应用在 Chat 中执行的操作。

例如，如果您调用 spaces.create() 方法，Chat 会在聊天室创建者的说明中包含 Chat 应用的名称，如下图所示：

为了与 Chat 应用互动，用户还会通过以下方式查看或使用这些信息：

• 使用 @ 提及 Chat 应用，将其添加到聊天室或向其发送消息。
• 查找 Chat 应用并与其发起私信对话。在应用菜单中，私信会显示 Chat 应用的名称和头像。
• 用户可以从撰写栏中浏览 Chat 应用，并查看其名称、头像和说明。

在 Google Cloud 控制台中配置 Chat 应用

获得 Chat 应用详细信息后，打开您的云项目并配置 Chat API：

1. 在 Google Cloud 控制台中，前往 Chat API 页面，然后点击配置页面：

   前往 Chat API 配置页面

2. 在应用信息下，填写应用名称、头像网址和说明字段。

3. 可选：从标记语法菜单中，为 Chat 应用的消息选择默认标记语法（Markdown 或 Chat）。如需详细了解文本格式以及 Chat 如何确定 API 请求的标记语法，请参阅设置消息格式。

4. 在互动功能下，配置您的 Chat 应用是否响应用户互动：

   如需构建互动式 Chat 应用，请开启启用互动功能，然后完成以下操作：

   1. 在功能下：
      • 可选：选择支持应用首页，以便在与 Chat 应用的 1 对 1 私信的首页标签页中显示首页卡片。
      • 选择加入聊天室和群组对话，以便安装和使用您的 Chat 应用。默认情况下，用户可以在用户与 Chat 应用之间的专用聊天室中安装 Chat 应用并与之发送消息。用户还可以在多人聊天室中添加 Chat 应用并与之互动。

   2. 在连接设置下，选择要用于接收 Chat 中的事件对象的架构：

      • 如需使用 HTTP 服务，请选择 HTTP 端点网址并提供网址。
      • 如需使用 Google Apps 脚本项目，请选择 Apps 脚本，并提供项目的部署 ID。
      • 如需使用 Dialogflow 代理，请选择 Dialogflow，选择 Dialogflow CX 或 Dialogflow ES，然后提供代理的资源名称。
      • 如需使用 Pub/Sub，请选择 Cloud Pub/Sub 并输入主题名称。

   3. 可选：如需将事件对象路由到特定端点或函数，请前往连接设置 > 触发器，然后为以下 Chat 触发器提供或更新回调端点或函数：

      • 应用首页（如果启用了支持应用首页）：用户在与 Chat 应用的 1 对 1 私信中打开首页标签页。
      • 已添加到聊天室：用户将 Chat 应用添加到群组对话或聊天室，或安装 Chat 应用以进行 1 对 1 消息。
      • 消息：用户向 Chat 应用发送消息。例如，用户向 Chat 应用发送私信，或在多人聊天室中 @提及 Chat 应用。
      • 从聊天室中移除：用户从聊天室中卸载或移除 Chat 应用。
      • 应用命令：用户从 Chat 应用调用快速命令、斜杠命令或消息操作。

   4. 可选：添加其他互动功能，例如预设提示词、命令（快速命令、斜杠命令和消息操作）或链接预览。

   5. 在公开范围下，指定您的邮箱，以便您在发布到 Google Workspace Marketplace 之前安装和测试 Chat 应用。您最多可以指定 5 个人，也可以指定 Google Workspace 组织中的一个或多个 Google 群组。

5. 可选：在日志下，选中将错误记录到 Logging 复选框，以使用 Google Cloud Logging。如需了解详情，请参阅查询 Chat 应用的错误日志。

6. 点击保存。

保存配置后，您在 Chat API 的公开范围设置中指定的任何人都可以安装、测试或使用 Chat 应用。如需开始测试和调试 Chat 应用，请参阅测试 Google Chat 应用的互动功能。

使用 Google Workspace 插件 API 配置 Chat 应用

您可以使用已加入 Google Workspace 开发者预览版计划的 Google Cloud 项目，通过 Google Workspace add-ons API 中的 chatAppConfig 资源，以编程方式读取和更新作为 Google Workspace 插件构建的 Chat 应用的配置，而无需在 Google Cloud 控制台中手动配置 Chat 应用。

chatAppConfig 是一个单例资源，始终存在于每个云项目中。在您首次保存配置之前，资源包含一个空配置（如果您在首次保存之前读取资源，GetChatAppConfig 也会返回该配置）。由于该资源已存在，因此您无需单独创建它，只需使用 UpdateChatAppConfig 即可保存初始配置并更新现有配置。

前提条件和身份验证

在调用 GetChatAppConfig 或 UpdateChatAppConfig 之前，请先完成以下前提条件：

1. 让您的 Google Cloud 项目加入 Google Workspace 开发者预览版计划。
2. 在云项目中启用 Google Workspace 插件 API (gsuiteaddons.googleapis.com)。（可选）如果您想在 Google Cloud 控制台中查看或更新 Chat 应用配置，或者调用 Chat API，可以启用 Google Chat API (chat.googleapis.com)。
3. 使用包含 https://www.googleapis.com/auth/cloud-platform 范围的 OAuth 2.0 凭据以人类用户身份进行身份验证。chatAppConfig 方法不支持服务账号身份验证。
4. 确保经过身份验证的用户在目标云项目中拥有所需的 Identity and Access Management (IAM) 权限：
   • gsuiteaddons.chatAppConfigs.get 和 chat.bots.get，用于读取配置 (GetChatAppConfig)。
   • gsuiteaddons.chatAppConfigs.update 和 chat.bots.update，以更新配置 (UpdateChatAppConfig)。
5. 如果您使用客户端库，请使用已注册的开发者预览版账号下载开发者预览版客户端库。

更新 Chat 应用配置

如需首次配置 Chat 应用或更新现有配置，请向云项目的单例 chatAppConfig 资源发送 PATCH 请求 (UpdateChatAppConfig)：

• 对于 chatAppConfig 为空的云项目的初始保存，displayName（3 到 25 个字符）和 description（1 到 40 个字符）是必需的。如果您在初始保存时省略了 interactiveFeatureConfig，则 Chat 应用会被配置为非互动应用。
• 对于后续更新，请使用可选的 updateMask 查询参数指定要更新的以逗号分隔的字段（或省略 updateMask 以更新所有提供的字段）。更新重复字段（appCommands、urlPatterns 或 allowlistedTestingPrincipals）会替换整个列表。

PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "name": "projects/PROJECT_NUMBER/chatAppConfig",
  "displayName": "Cymbal Assistant",
  "description": "Helps manage tasks and schedules",
  "avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
  "state": "ACTIVE",
  "errorLoggingEnabled": true,
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "interactiveFeatureConfig": {
    "supportsMultiuserSpaces": false,
    "connectionConfig": {
      "httpEndpointConfig": {
        "commonUrl": "https://example.com/chat"
      }
    },
    "appCommands": [
      {
        "commandType": "SLASH_COMMAND",
        "commandId": 1,
        "command": "/help",
        "description": "Show available commands",
        "dialogEnabled": false
      }
    ],
    "urlPatterns": [
      {
        "hostPattern": "example.com",
        "pathPrefix": "tasks/"
      }
    ],
    "allowlistedTestingPrincipals": [
      "USER_EMAIL"
    ]
  }
}

替换请求网址、标头和正文中的以下内容：

• PROJECT_NUMBER：托管 Chat 应用的 Cloud 项目的数字项目编号。
• ACCESS_TOKEN：使用 https://www.googleapis.com/auth/cloud-platform 范围授权的用户 OAuth 2.0 访问令牌。
• USER_EMAIL：Google Workspace 组织中要列入许可清单以测试 Chat 应用的电子邮件地址或 Google 群组（例如，您自己的电子邮件地址）。
• 将请求正文中的示例配置字段（例如 displayName、description、avatarUri 和 interactiveFeatureConfig，包括端点配置、命令、链接预览网址格式和测试主账号）替换为您的 Chat 应用的值。如需详细了解所有支持的字段和端点选项，请参阅 projects.chatAppConfig REST 参考文档和 projects.chatAppConfig.patch。

获取 Chat 应用配置

如需读取 Cloud 项目的当前 Chat 应用配置，请调用 GetChatAppConfig。您可以传递可选的 view 查询参数 (ChatAppConfigView)：

• BASIC（默认）：返回不含 interactiveFeatureConfig 的基本元数据。
• FULL：返回所有配置字段，包括 interactiveFeatureConfig。

如果尚未为云项目保存 Chat 应用配置，该方法会返回一个空的 ChatAppConfig 对象。

GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN

const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;

const client = new GSuiteAddOnsClient();

async function getChatAppConfig() {
  const [response] = await client.getChatAppConfig({
    name: 'projects/PROJECT_NUMBER/chatAppConfig',
    view: 'FULL',
  });
  console.log(JSON.stringify(response, null, 2));
}

getChatAppConfig();

from google.cloud import gsuiteaddons_v1

client = gsuiteaddons_v1.GSuiteAddOnsClient()

request = gsuiteaddons_v1.GetChatAppConfigRequest(
    name="projects/PROJECT_NUMBER/chatAppConfig",
    view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)

现有 Google Workspace 插件的注意事项

与扩展其他 Google Workspace 应用的 Google Workspace 插件相比，Chat 扩展应用需要不同的配置。如果您的插件扩展了其他 Google Workspace 应用，请考虑以下配置 Chat 应用的要求：

• 个人和 Google Workspace 管理员都必须能够从 Marketplace 安装您的插件。您可以在 Marketplace SDK 中 配置这些安装设置。
• Chat 应用不会使用您在清单的 addons.common 对象中为其他 Google Workspace 应用配置的名称和徽标。
• 对于已发布到 Google Workspace Marketplace 的插件，您无法保存对 Google Chat API 配置设置所做的任何更改的草稿。更新并保存 Chat API 配置设置后，更新后的 Chat 应用会立即提供给所有现有用户。如需更新 Marketplace 商品详情，您可以在提交任何更改之前创建草稿。
• 如果您使用 Apps 脚本构建了插件，请执行以下操作：
  • 您必须使用与插件配置的其余部分相同的 Apps 脚本部署 ID。
  • 您无法使用 Apps 脚本编辑器在 Chat 中安装测试部署。您必须直接从 Chat 界面安装它们。
• 如果您使用 HTTP 服务构建了插件，请在您使用 Google Workspace Add-ons API 创建的 projects.deployments 清单中省略任何 Chat 应用配置详细信息。您在 Google Workspace Marketplace SDK 中指定的 HTTP 部署仅用于其他 Google Workspace 应用。请改为在 Google Cloud 控制台中或使用 Google Workspace Add-ons API 中的 chatAppConfig 资源配置 Chat 应用。

向其他人授予配置 Chat API 的权限

您可以向特定用户授予 Chat 应用所有者或 Chat 应用查看者 Google Cloud Identity Access Management (IAM) 角色，从而向其授予对 Chat 应用配置页面的访问权限。拥有这些角色的用户无法使用 API 和服务信息中心前往 Chat 应用配置页面，但可以前往 Chat 应用的主机云项目 的 Google Cloud 控制台，访问配置页面，具体操作如下：

https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID

其中，PROJECT_ID 是托管 Chat 应用的 Google Cloud 项目的项目 ID。

相关主题

• 选择 Chat 应用架构
• 接收和响应用户互动
• 测试 Google Chat 应用的互动功能