此页面由 Cloud Translation API 翻译。

构建 HTTP Google Chat 应用

本页介绍了如何创建 HTTP Chat 应用。您可以通过多种方式实现此架构。在 Google Cloud 上，您可以使用 Cloud Functions、Cloud Run 和 App Engine。在本快速入门中，您将编写并部署一个 Cloud Functions 函数，供 Chat 应用使用来回复用户的消息。

采用这种架构时，您可以配置 Chat 以使用 HTTP 与 Google Cloud 或本地服务器集成，如下图所示：

使用本地服务器中的 Web 服务的 Chat 应用架构。

在上图中，与 HTTP Chat 应用互动的用户具有以下信息流：

用户在 Chat 中通过私信或 Chat 聊天室向 Chat 应用发送消息。
系统会向 Web 服务器发送 HTTP 请求，该服务器是包含 Chat 应用逻辑的云端或本地系统。
（可选）Chat 应用逻辑可以与 Google Workspace 服务（如日历和表格）、其他 Google 服务（如地图、YouTube 和 Vertex AI）或其他网络服务（如项目管理系统或票务工具）集成。
Web 服务器将 HTTP 响应发回给 Chat 中的 Chat 应用服务。
系统会将响应传递给用户。
聊天应用可以选择调用 Chat API 以异步发布消息或执行其他操作。

由于这些 Chat 应用可以使用不同的编程语言进行设计，因此这种架构可让您灵活使用系统中现有的库和组件。

目标

设置环境。
创建和部署 Cloud Functions 函数。
将应用发布到 Chat。
测试应用。

前提条件

拥有对 Google Chat 访问权限的商务版或企业版 Google Workspace 账号。
启用了结算功能的 Google Cloud 项目。如需检查现有项目是否已启用结算功能，请参阅验证项目的结算状态。如需创建项目并设置结算信息，请参阅创建 Google Cloud 项目。

设置环境

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

在 Google Cloud 控制台中，启用 Google Chat API、Cloud Build API、Cloud Functions API、Cloud Pub/Sub API、Cloud Logging API、Artifact Registry API 和 Cloud Run API。

启用 API

创建和部署 Cloud Functions 函数

创建和部署一个 Cloud Functions 函数，该函数将生成包含发送者的显示名称和头像图片的聊天卡片。当 Chat 应用收到消息时，它会运行该函数并使用卡片进行响应。

如需为 Chat 应用创建和部署函数，请完成以下步骤：

Node.js

在 Google Cloud 控制台中，转到 Cloud Functions 页面：

转到 Cloud Functions

确保为您的 Chat 应用选择项目。
点击 创建函数。
在“创建函数”页面上，设置您的函数：
1. 在环境中，选择 Cloud Run Functions。
2. 在函数名称中，输入 QuickStartChatApp。
3. 在区域中，选择一个区域。
4. 在“身份验证”下，选择需要进行身份验证。
5. 点击下一步。
在运行时中，选择最新版本的 Node.js。
在源代码中，选择內嵌编辑器。
在入口点中，删除默认文本，然后输入 avatarApp。

将 index.js 的内容替换为以下代码：

node/avatar-app/index.js

在 GitHub 上查看

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You need to
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = "";

/**
 * Google Cloud Function that responds to messages sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.avatarApp = function avatarApp(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    return res.send('Hello! This function is meant to be used ' +
      'in a Google Chat Space.');
  }

  // Stores the Google Chat event as a variable.
  const event = req.body;

  // Checks for the presence of a slash command in the message.
  if (event.message.slashCommand) {
    // Executes the slash command logic based on its ID.
    // Slash command IDs are set in the Google Chat API configuration.
    switch (event.message.slashCommand.commandId) {
      case ABOUT_COMMAND_ID:
        return res.send({
          privateMessageViewer: event.user,
          text: 'The Avatar app replies to Google Chat messages.'
        });
    }
  }

  const sender = req.body.message.sender.displayName;
  const image = req.body.message.sender.avatarUrl;
  const data = createMessage(sender, image);
  res.send(data);
};

/**
 * Creates a card with two widgets.
 * 
 * @param {string} displayName the sender's display name
 * @param {string} avatarUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, avatarUrl) {
  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: {
          title: `Hello ${displayName}!`,
        },
        sections: [{ widgets: [{
          textParagraph: { text: 'Your avatar picture: ' }
        }, {
          image: { imageUrl: avatarUrl }
        }]}]
      }
    }]
  };
}

点击部署。

Python

在 Google Cloud 控制台中，转到 Cloud Functions 页面：

转到 Cloud Functions

确保选择了 Chat 应用的项目。
点击 创建函数。
在“创建函数”页面上，设置您的函数：
1. 在环境中，选择 Cloud Run Functions。
2. 在函数名称中，输入 QuickStartChatApp。
3. 在区域中，选择一个区域。
4. 在“身份验证”下，选择需要进行身份验证。
5. 点击下一步。
在运行时中，选择最新版本的 Python。
在源代码中，选择内嵌编辑器。
在入口点中，删除默认文本，然后输入 avatar_app。

将 main.py 的内容替换为以下代码：

python/avatar-app/main.py

在 GitHub 上查看

from typing import Any, Mapping

import flask
import functions_framework

# The ID of the slash command "/about".
# It's not enabled by default, set to the actual ID to enable it. You need to
# use the same ID as set in the Google Chat API configuration.
ABOUT_COMMAND_ID = ""

@functions_framework.http
def avatar_app(req: flask.Request) -> Mapping[str, Any]:
  """Google Cloud Function that handles requests from Google Chat

  Args:
      flask.Request: the request

  Returns:
      Mapping[str, Any]: the response
  """
  if req.method == "GET":
    return "Hello! This function must be called from Google Chat."

  request_json = req.get_json(silent=True)

  # Checks for the presence of a slash command in the message.
  if "slashCommand" in request_json["message"]:
    # Executes the slash command logic based on its ID.
    # Slash command IDs are set in the Google Chat API configuration.
    if request_json["message"]["slashCommand"]["commandId"] == ABOUT_COMMAND_ID:
      return {
        "privateMessageViewer": request_json["user"],
        "text": 'The Avatar app replies to Google Chat messages.'
      }

  display_name = request_json["message"]["sender"]["displayName"]
  avatar = request_json["message"]["sender"]["avatarUrl"]
  response = create_message(name=display_name, image_url=avatar)
  return response


def create_message(name: str, image_url: str) -> Mapping[str, Any]:
  """Google Cloud Function that handles requests from Google Chat

  Args:
      str name: the sender's display name.
      str image_url: the URL for the sender's avatar.

  Returns:
      Mapping[str, Any]: a card with the user's avatar.
  """
  return {
    "text": "Here's your avatar",
    "cardsV2": [{
      "cardId": "avatarCard",
      "card": {
          "name": "Avatar Card",
          "header": { "title": f"Hello {name}!" },
          "sections": [{
            "widgets": [{
              "textParagraph": { "text": "Your avatar picture:" }
            }, {
              "image": { "imageUrl": image_url }
            }]
          }]
      }
    }]
  }

点击部署。

Java

在 Google Cloud 控制台中，转到 Cloud Functions 页面：

转到 Cloud Functions

确保选择了 Chat 应用的项目。
点击 创建函数。
在“创建函数”页面上，设置您的函数：
1. 在环境中，选择 Cloud Run Functions。
2. 在函数名称中，输入 QuickStartChatApp。
3. 在区域中，选择一个区域。
4. 在“身份验证”下，选择需要进行身份验证。
5. 点击下一步。
在运行时中，选择最新版本的 Java。
在源代码中，选择內嵌编辑器。
在入口点中，删除默认文本并输入 App。
将 src/main/java/com/example/Example.java 改名为 src/main/java/App.java。

将 App.java 的内容替换为以下代码：

java/avatar-app/src/main/java/App.java

在 GitHub 上查看

import java.util.List;

import com.google.api.services.chat.v1.model.CardWithId;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1Card;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1CardHeader;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1Image;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1Section;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1TextParagraph;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1Widget;
import com.google.api.services.chat.v1.model.Message;
import com.google.api.services.chat.v1.model.User;
import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.JsonObject;

public class App implements HttpFunction {
  private static final Gson gson = new Gson();

  // The ID of the slash command "/about".
  // It's not enabled by default, set to the actual ID to enable it. You need to
  // use the same ID as set in the Google Chat API configuration.
  private static final String ABOUT_COMMAND_ID = "";

  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonObject body = gson.fromJson(request.getReader(), JsonObject.class);

    if (request.getMethod().equals("GET") || !body.has("message")) {
      response.getWriter().write("Hello! This function must be called from Google Chat.");
      return;
    }

    // Checks for the presence of a slash command in the message.
    if (body.getAsJsonObject("message").has("slashCommand")) {
      // Executes the slash command logic based on its ID.
      // Slash command IDs are set in the Google Chat API configuration.
      JsonObject slashCommand = body.getAsJsonObject("message").getAsJsonObject("slashCommand");
      switch (slashCommand.get("commandId").getAsString()) {
        case ABOUT_COMMAND_ID:
          Message aboutMessage = new Message();
          aboutMessage.setText("The Avatar app replies to Google Chat messages.");
          aboutMessage.setPrivateMessageViewer(new User()
            .setName(body.getAsJsonObject("user").get("name").getAsString()));
          response.getWriter().write(gson.toJson(aboutMessage));
          return;
      }
    }

    JsonObject sender = body.getAsJsonObject("message").getAsJsonObject("sender");
    String displayName = sender.has("displayName") ? sender.get("displayName").getAsString() : "";
    String avatarUrl = sender.has("avatarUrl") ? sender.get("avatarUrl").getAsString() : "";
    Message message = createMessage(displayName, avatarUrl);
    response.getWriter().write(gson.toJson(message));
  }

  Message createMessage(String displayName, String avatarUrl) {
    return new Message()
      .setText("Here's your avatar")
      .setCardsV2(List.of(new CardWithId()
        .setCardId("previewLink")
        .setCard(new GoogleAppsCardV1Card()
          .setName("Avatar Card")
          .setHeader(new GoogleAppsCardV1CardHeader()
            .setTitle(String.format("Hello %s!", displayName)))
          .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(
            new GoogleAppsCardV1Widget()
              .setTextParagraph(new GoogleAppsCardV1TextParagraph()
                .setText("Your avatar picture: ")),
            new GoogleAppsCardV1Widget()
              .setImage(new GoogleAppsCardV1Image().setImageUrl(avatarUrl)))))))));
  }
}

将 pom.xml 的内容替换为以下代码：

java/avatar-app/pom.xml

在 GitHub 上查看

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.google.chat</groupId>
  <artifactId>avatar-app</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.target>17</maven.compiler.target>
    <maven.compiler.source>17</maven.compiler.source>
  </properties>

  <dependencies>
    <dependency>
      <groupId>com.google.cloud.functions</groupId>
      <artifactId>functions-framework-api</artifactId>
      <version>1.0.1</version>
    </dependency>

    <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
    <dependency>
        <groupId>com.google.code.gson</groupId>
        <artifactId>gson</artifactId>
        <version>2.9.1</version>
    </dependency>

    <!-- https://mvnrepository.com/artifact/com.google.apis/google-api-services-chat -->
    <dependency>
      <groupId>com.google.apis</groupId>
      <artifactId>google-api-services-chat</artifactId>
      <version>v1-rev20241008-2.0.0</version>
    </dependency>
  </dependencies>

  <!-- Required for Java 11 functions in the inline editor -->
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.8.1</version>
        <configuration>
          <excludes>
            <exclude>.google/</exclude>
          </excludes>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

点击部署。

Cloud Functions 详情页面随即打开，您的函数会显示两个进度指示器：一个指示构建进度，另一个指示服务进度。当两个进度指示器都消失并替换为对勾标记时，您的函数已部署并准备就绪。

授权 Google Chat 调用您的函数

如需授权 Google Chat 调用您的函数，请添加具有 Cloud Run Invoker 角色的 Google Chat 服务账号。

在 Google Cloud 控制台中，转到 Cloud Run 页面。

转到 Cloud Run
在 Cloud Run 服务列表中，选中接收函数旁边的复选框。（请勿点击函数本身。）
点击权限。权限面板随即会打开。
点击添加主账号。
在新主账号中，输入 chat@system.gserviceaccount.com。
在选择角色中，依次选择 Cloud Run > Cloud Run Invoker。
点击保存。

将应用发布到 Google Chat

部署 Cloud Functions 函数后，请按照以下步骤将其转换为 Google Chat 应用：

在 Google Cloud 控制台中，依次点击“菜单”图标 > Cloud Functions。

转到 Cloud Functions

请务必选择启用了 Cloud Functions 的项目。
在函数列表中，点击 QuickStartChatApp。
点击触发器标签页。
在 HTTPS 下，复制网址。
搜索“Google Chat API”并点击 Google Chat API，然后点击管理。

前往 Chat API
点击配置并设置 Google Chat 应用：
1. 在应用名称中，输入 Quickstart App。
2. 在头像网址中，输入 https://developers.google.com/chat/images/quickstart-app-avatar.png。
3. 在说明中，输入 Quickstart app。
4. 在功能下，选择接收一对一消息和加入聊天室和群组对话。
5. 在连接设置下，选择 HTTP 端点网址，然后将 Cloud Functions 函数触发器的网址粘贴到该框中。
6. 在 Authentication Audience（身份验证受众群体）中，选择 HTTP 端点网址。
7. 在公开范围下，选择将此 Google Chat 应用设为可供网域中的特定人员和群组使用，然后输入您的电子邮件地址。
8. 在日志下，选择将错误记录到 Logging。
点击保存。

Chat 应用已准备好接收和回复 Chat 中的消息。

测试您的 Chat 应用

如需测试 Chat 应用，请使用 Chat 应用打开私信聊天室并发送消息：

使用您在将自己添加为受信任的测试人员时提供的 Google Workspace 账号打开 Google Chat。

前往 Google Chat
点击 发起新对话。
在添加一人或多人字段中，输入您的 Chat 应用的名称。
从结果中选择您的 Chat 应用。系统随即会打开一条私信。

注意：如果您在结果列表中没有看到您的 Chat 应用，请确保您已在 Google Cloud 控制台的 Chat API 配置页面的公开范围设置中添加了您的 Google Workspace 账号。
在与应用来往的新私信中，输入 Hello 并按 enter。

Chat 应用的响应包含一个卡片消息，其中显示了发件人的姓名和头像图片，如以下图片所示：

Chat 应用使用包含发件人显示名称和头像图片的卡片进行响应

如需添加可信测试人员并详细了解如何测试 Interactive 功能，请参阅测试 Google Chat 应用的 Interactive 功能。

问题排查

当 Google Chat 应用或卡片返回错误时，Chat 界面会显示“出了点问题”消息。或“无法处理您的请求”。有时，Chat 界面不会显示任何错误消息，但 Chat 应用或卡片会产生意外结果；例如，卡片消息可能不会显示。

虽然 Chat 界面中可能不会显示错误消息，但当 Chat 应用的错误日志记录功能处于开启状态时，描述性错误消息和日志数据可帮助您修正错误。如需有关查看、调试和修复错误的帮助，请参阅排查和修复 Google Chat 错误。

清理

为避免系统因本教程中使用的资源向您的 Google Cloud 账号收取费用，我们建议您删除该 Cloud 项目。

在 Google Cloud 控制台中，前往管理资源页面。依次点击菜单 > IAM 和管理 > 管理资源。
前往资源管理器
在项目列表中，选择要删除的项目，然后点击删除。
在对话框中输入项目 ID，然后点击关闭以删除项目。

构建 HTTP Google Chat 应用

目标

前提条件

设置环境

创建和部署 Cloud Functions 函数

Node.js

Python

Java

授权 Google Chat 调用您的函数

将应用发布到 Google Chat

测试您的 Chat 应用

问题排查

清理

相关主题