使用 Google Chat、Vertex AI 和 Firestore 管理项目

本教程介绍了如何构建可供团队使用的 Google Chat 应用 用于实时管理项目。Chat 应用会使用 Vertex AI 可帮助团队撰写用户故事（用户案例代表 软件系统供团队开发）以及 会将故事保留在 Firestore 数据库中。

  • <ph type="x-smartling-placeholder">
    </ph> 提及项目管理应用会提示该应用提供帮助。
    图 1.Charlie 与团队讨论 Chat 聊天室的功能开发。提及项目管理 Chat 应用会提示 Chat 应用提供帮助。
  • 使用 /createUserStory 斜杠命令创建故事。
    图 2.Charlie 使用 /createUserStory 斜杠命令创建了一个故事。
  • 项目管理 Chat 应用使用 Vertex AI 撰写故事说明。
    图 3.项目管理 Chat 应用使用 Vertex AI 撰写故事说明，然后在聊天室中分享故事。
  • Charlie 敲定故事细节。
    图 4.Charlie 点击修改，敲定故事细节。AI 说明准确无误，但 Charlie 想要了解更多详细信息，因此 Charlie 点击了展开，让 Vertex AI 向故事说明中添加要求。Charlie 将故事分配给自己，将状态设置为“已开始”，选择合适的优先级和大小，然后点击保存。
  • 管理团队的所有用户案例。
    图 5.Charlie 可以随时使用 /manageUserStories 斜杠命令查看和管理团队的所有用户案例。

前提条件

目标

  • 构建一款用于管理敏捷软件的 Chat 应用 项目。
  • 利用生成式 AI 帮助用户撰写用户故事 由 Vertex AI 提供支持的 AI 辅助故事撰写工具： <ph type="x-smartling-placeholder">
      </ph>
    • 生成并重新生成故事说明。
    • 从备注中展开故事说明以完成要求。
    • 更正语法以修正拼写错误。
  • 通过向 Firestore 数据库写入和从中读取数据，使工作保持最新状态。
  • 允许用户在 Chat 聊天室中开展协作 直接在对话中创建、修改、分配和发起故事。

使用的产品

项目管理应用使用以下 Google Workspace 和 Google Cloud 产品：

  • Chat API： 此 API 用于开发 Google Chat 应用，这些应用会接收和响应 聊天互动事件，例如消息。项目管理 Google Chat 应用使用 Chat API 来接收和回复消息 Chat 发送的互动事件，以及配置 确定它在 Chat 中的显示方式，例如名称和头像图片。
  • Vertex AI API： 生成式 AI 平台。项目管理 Google Chat 应用使用 Vertex AI API 撰写用户故事 标题和说明。
  • Firestore： 无服务器文档数据库。项目管理 Google Chat 应用使用 Firebase 存储用户故事的相关数据。

  • Cloud Functions： 一项轻量级无服务器计算服务，让您可以 单一用途的独立函数，可用于响应 Chat 而无需管理服务器或运行时环境。通过 项目管理 Google Chat 应用使用 Cloud Functions 托管 Chat 将互动事件发送到的 HTTP 端点，并作为 计算平台来运行处理和响应这些事件的逻辑。

    Cloud Functions 使用以下 Google Cloud 产品进行构建 处理互动事件和托管计算资源：

    • Cloud Build： 全代管式持续集成、交付和部署平台 运行自动构建的系统
    • Pub/Sub： 一种异步且可扩缩的消息传递服务，用于分离服务 。
    • Cloud Run Admin API： 用于运行容器化应用的全代管式环境。

架构

Google Chat 应用架构的项目管理接收和 在 HTTP 端点处理聊天互动事件，使用 Vertex AI 来帮助 写入用户故事，并将用户故事详细信息存储在 Firestore 数据库中。通过 下图显示了 Google Workspace 的架构和 已使用的 Google Cloud 资源。

项目管理 Google Chat 应用的架构图

项目管理 Google Chat 应用的运作方式如下：

  1. 用户在 Chat 中发送消息，并调用 通过向 Google Chat 应用发送消息 直接使用，在空格中提及，或输入正斜线命令。

  2. Chat 会将同步 HTTP 请求发送到 Cloud Functions 函数的 HTTP 端点。

  3. 项目管理 Google Chat 应用会处理 HTTP 请求：

    1. Vertex AI 可帮助您撰写或更新用户故事。

    2. Firestore 数据库可存储、检索、更新或删除用户故事 数据。

  4. Cloud Functions 会向 Chat 返回 HTTP 响应，该响应 以消息或对话框的形式向用户显示。

准备环境

本部分介绍如何为 Chat 应用。

创建 Google Cloud 项目

Google Cloud 控制台

  1. 在 Google Cloud 控制台中，点击“菜单”图标 &gt; IAM 和管理 &gt; 创建项目。

    转到“创建项目”

  2. 在项目名称字段中，为您的项目输入描述性名称。

    可选：要修改项目 ID，请点击修改。项目 ID 无法更改 创建项目后，请选择一个满足您需求的 ID 项目。

  3. 在地理位置字段中，点击浏览以显示适合您的潜在地理位置 项目。然后，点击选择。 <ph type="x-smartling-placeholder">
  4. 点击创建。Google Cloud 控制台会转到“信息中心”页面，并且您的项目已创建完毕 就会出现这种问题

gcloud CLI

在以下某个开发环境中，访问 Google Cloud CLI (`gcloud`)：

  • Cloud Shell：通过 gcloud CLI 使用在线终端 请激活 Cloud Shell。
    激活 Cloud Shell
  • Local Shell：如需使用本地开发环境， 安装和 初始化 gcloud CLI
    如需创建 Cloud 项目，请使用“gcloud projects create”命令： 
    gcloud projects create PROJECT_ID
     通过设置要创建的项目的 ID 来替换 PROJECT_ID。

为 Cloud 项目启用结算功能

<ph type="x-smartling-placeholder">

Google Cloud 控制台

  1. 在 Google Cloud 控制台中，前往结算。点击 菜单 &gt; 结算 &gt; 我的项目。

    转到“我的项目的结算”

  2. 在选择组织中，选择与 Google Cloud 项目。
  3. 在项目行中，打开操作菜单 (), 点击更改结算信息，然后选择 Cloud Billing 账号。
  4. 点击设置账号。

gcloud CLI

  1. 如需列出可用的结算账号，请运行以下命令： 
    gcloud billing accounts list
  2. 将结算账号与 Google Cloud 项目相关联： 
    gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

    替换以下内容：

    • PROJECT_ID 是 您要为其启用结算功能的 Cloud 项目。
    • BILLING_ACCOUNT_ID 是要关联的结算账号 ID Google Cloud 项目。

启用 API

Google Cloud 控制台

  1. 在 Google Cloud 控制台中，启用 Google Chat API、Vertex AI API、 Cloud Functions API、Firestore API、Cloud Build API Pub/Sub API 和 Cloud Run Admin API。

    启用 API

  2. 确认您是在正确的 Cloud 项目，然后点击下一步。

  3. 确认您启用的 API 正确无误，然后点击启用。

gcloud CLI

  1. 如有必要，请将当前 Cloud 项目设置为您 使用 gcloud config set project 命令创建：

    gcloud config set project PROJECT_ID

    将 PROJECT_ID 替换为项目 ID 您创建的 Cloud 项目。

  2. 启用 Google Chat API、Vertex AI API、Cloud Functions API、 Firestore API、Cloud Build API、Pub/Sub API 以及 通过 gcloud services enable 命令访问 Cloud Run Admin API：

    gcloud services enable chat.googleapis.com \
aiplatform.googleapis.com \
cloudfunctions.googleapis.com \
firestore.googleapis.com \
cloudbuild.googleapis.com \
pubsub.googleapis.com \
run.googleapis.com

    Cloud Build、Pub/Sub 和 Cloud Run Admin API 是 Cloud Functions

身份验证和授权

遵循此指南无需身份验证和授权配置 教程。

为了调用 Firestore 和 Vertex AI API，本教程使用 应用默认凭据 默认服务账号关联到 Cloud Functions 函数 无需设置在生产环境中 通常 创建 和 附加 服务账号。

创建和部署 Google Chat 应用

现在，您的 Google Cloud 项目已创建并配置完毕，您可以开始构建 并部署 Google Chat 应用。在本部分中，您需要 以下：

  1. 创建 Firestore 数据库，在其中保留和检索用户故事。
  2. （可选）查看示例代码。
  3. 创建一个 Cloud Functions 函数来托管并运行 Chat 应用响应事件的代码 从 Chat 接收的 HTTP 请求。
  4. 使用 Google Chat API 创建和部署 Google Chat 应用 配置页面。

创建 Firestore 数据库

在本部分中，您将创建一个 Firestore 数据库，用于保存和检索 用户故事，但您无需定义数据模型。数据模型设置 由 model/user-story.js 和 model/user.js 在示例代码中隐式隐含 文件。

项目管理 Chat 应用数据库使用 NoSQL 数据模型， 文档 组织为 集合。如需了解详情，请参阅 Firestore 数据模型。

下图是项目管理概览 Google Chat 应用的数据模型：

Firestore 数据库的数据模型。

根集合是 spaces，其中每个文档表示 Chat 应用在其中创建了故事。每个用户故事 由 userStories 子集合中的一个文档表示， 由 users 子集合中的文档表示。

查看集合、文档和字段定义

spaces

Chat 应用在其中创建故事的聊天室。

字段
Document IDString
创建故事的特定空间的唯一 ID。与 Chat API 中的聊天室资源名称对应。
userStoriesSubcollection of Documents (userStories)
由 Chat 应用及其用户创建的故事。对应于 Firebase 中 userStories 的 Document ID。
usersSubcollection of Documents (user)
创建故事或获得故事的用户。
displayNameString
Chat API 中聊天室的显示名称。不设置与用户的私信对话。

userStories

由 Chat 应用及其用户创建的故事。

字段
Document IDString
由 Chat 应用及其用户创建的特定用户故事的唯一 ID。
assigneeDocument (user)
分配给完成故事的用户的资源名称。与 users 文档的 Document ID 以及 Chat API 中的用户资源名称对应。
descriptionString
从用户角度对软件功能的说明。
priorityEnum
完成工作的紧迫性。可能的值包括 Low、Medium 或 High。
sizeEnum
工作量。可能的值包括 Small、Medium 或 Large。
statusEnum
工作阶段。可能的值包括 OPEN、STARTED 或 COMPLETED。
titleString
故事的标题；简单总结一下。

users

已创建故事或被分配了故事的用户。

字段
Document IDString
特定用户的唯一 ID。对应于 Firebase 中 userStories 的 assignee，以及 Chat API 中用户的资源名称。
avatarUrlString
托管用户 Chat 头像图片的网址。
displayNameString
用户的 Chat 显示名称。

创建 Firestore 数据库的方法如下：

Google Cloud 控制台

  1. 在 Google Cloud 控制台中，前往 Firestore。点击 菜单 &gt; Firestore。

    转到 Firestore

  2. 点击创建数据库。

  3. 从选择您的 Firestore 模式中，点击原生模式。

  4. 点击继续。

  5. 配置数据库：

    1. 在为数据库命名中，将数据库 ID 保留为 (default)。

    2. 在位置类型中，为数据库指定一个区域，例如 us-central1。为获得最佳效果，请选择同一地点或附近地点 Chat 应用的 Cloud Functions 函数。

  6. 点击创建数据库。

gcloud CLI

  • 使用 gcloud firestore databases create 命令：

    gcloud firestore databases create \
--location=LOCATION \
--type=firestore-native

    将 LOCATION 替换为 Firestore 的名称 区域，例如 名称：us-central1。

查看示例代码

（可选）在创建 Cloud Functions 函数之前，请花点时间查看 熟悉 GitHub 上托管的示例代码。

在 GitHub 上查看

以下是对每个文件的概述：

env.js
用于部署 将 Chat 扩展应用添加到指定的 Google Cloud 项目，以及 区域。您必须更新此文件中的配置变量。
package.json和package-lock.json
Node.js 项目设置和依赖项。
index.js
Chat 应用的 Cloud Functions 函数的入口点。它 读 聊天事件来自 HTTP 请求，调用应用程序处理程序，并将 HTTP 响应作为 JSON 对象。
controllers/app.js
主要应用逻辑。会处理 互动事件，具体方法是处理 Chat 应用会提及和斜杠命令。 为了响应卡片点击，它会调用 app-action-handler.js。
controllers/app-action-handler.js
用于处理卡片点击的应用逻辑 聊天互动事件。
services/space-service.js、services/user-service.js和services/user-story-service.js
这些文件包含 特定于处理 Chat 聊天室的应用逻辑， 以及用户案例这些文件中的函数由 app.js 调用 或 app-action-handler.js。为了执行数据库操作， 这些文件会调用 firestore-service.js 中的函数。
services/firestore-service.js
处理数据库操作。 此文件中的函数由 services/space-service.js、services/user-service.js和 services/user-story-service.js。
services/aip-service.js
调用生成式 AI 文本的 Vertex AI API 预测。
model/*.js
这些文件包含应用需要定义的类和枚举的定义 用于在函数之间存储和传递数据的服务。他们设置了 Firestore 数据库的数据模型。
views/*.js
此目录中的每个文件都会实例化 一个卡片对象 然后，Chat 应用会以如下身份发回 Chat： 卡片消息或 对话框操作响应。
views/widgets/*.js
每个文件都会实例化 一种 widget 类型 对象用于在 views/ 目录中构建卡片。
test/**/*.test.js
此目录及其子目录中的每个文件都包含单元测试 。 您可以在以下位置运行 npm run test 来执行所有单元测试： 项目的根目录

创建和部署 Cloud Functions 函数

在本部分中，您将创建并部署一个 Cloud Functions 函数，其中包含 项目管理 Chat 应用的应用逻辑。

Cloud Functions 函数在运行 来自包含 Chat 的 Chat 的 HTTP 请求 互动事件运行时，Cloud Functions 函数代码会处理事件，并 返回对 Chat 的响应，Chat 会将该响应显示为 消息、对话框或其他类型的用户互动。如果适用， 函数还会对 Firestore 数据库执行读写操作。

创建 Cloud Functions 函数的方法如下：

Google Cloud 控制台

  1. 从 GitHub 下载 ZIP 文件形式的代码。

    下载 zip 文件

  2. 解压缩下载的 ZIP 文件。

    解压缩的文件夹包含整个 Google Workspace 示例 存储库

  3. 在解压缩的文件夹中，导航到 google-chat-samples-main/node/project-management-app/，然后压缩 将 project-management-app 文件夹压缩成一个 ZIP 文件。

    zip 文件的根目录必须包含以下内容 文件和文件夹：

    • env.js
    • README.md
    • gcloudignore.text
    • package-lock.json
    • package.json
    • index.js
    • model/
    • controllers/
    • views/
    • services/

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

    转到 Cloud Functions

    确保您的 Google Cloud 项目 已选择 Chat 应用。

  5. 点击 创建函数。

  6. 在创建函数页面上，设置您的函数：

    1. 在环境中，选择第 2 代。
    2. 在函数名称中，输入 project-management-tutorial。
    3. 在区域中，选择一个区域。
    4. 在身份验证下，选择 允许未通过身份验证的调用。
    5. 点击下一步。

  7. 在运行时中，选择 Node.js 20。

  8. 在入口点中，删除默认文本并输入 projectManagementChatApp。

  9. 在源代码中，选择 Zip upload。

  10. 在目标存储分区中， 创建 或选择一个存储分区：

    1. 点击浏览。
    2. 选择存储分区。
    3. 点击选择。

    Google Cloud 将 zip 文件上传到并解压缩组件文件 此存储分区中的实例。Cloud Functions 随后会将组件文件复制到 Cloud Functions 函数。

  11. 在 Zip 文件中，上传您从 GitHub 下载的 ZIP 文件。 提取后重新压缩后的结果：

    1. 点击浏览。
    2. 找到并选择该 ZIP 文件。
    3. 点击打开。

  12. 点击部署。

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

  13. 修改示例代码以设置常量：

    1. 在 Cloud Functions 函数详情页面上，点击修改。
    2. 点击下一步。
    3. 在源代码中，选择内嵌编辑器。
    4. 在内嵌编辑器中，打开 env.js 文件。
    5. 将 project-id 替换为您的 Cloud 项目 ID。
    6. 可选：使用us-central1 支持的位置 Cloud Functions 函数。

  14. 点击部署。

  15. 当函数部署完成后，复制触发器网址：

    1. 在函数详情页面上，点击触发器。
    2. 复制网址。您需要使用它来配置 Chat 扩展应用。

gcloud CLI

  1. 从 GitHub 克隆代码：

    git clone https://github.com/googleworkspace/google-chat-samples.git

  2. 切换到包含此项目代码的目录 管理 Chat 应用：

    cd google-chat-samples/node/project-management-app

  3. 修改 env.js 文件以设置环境变量：

    1. 将 project-id 替换为您的 Google Cloud 项目 ID。
    2. 将 us-central1 替换为您的 Google Cloud 项目位置。

  4. 将 Cloud Functions 函数部署到 Google Cloud：

    gcloud functions deploy project-management-tutorial \
--gen2 \
--region=REGION \
--runtime=nodejs20 \
--source=. \
--entry-point=projectManagementChatApp \
--trigger-http \
--allow-unauthenticated

    将 REGION 替换为 Cloud Functions 函数位置 其基础架构的托管位置，例如 us-central1。

  1. 当函数部署完成时，将 url 属性从 响应。这是您在下一部分中用于 配置 Google Chat 应用。

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

本部分介绍如何在 显示您的 Chat 应用相关信息的 Google Cloud 控制台， 包括 Chat 应用的名称、支持的斜杠 以及 Chat 应用云的触发器网址 将 Chat 互动事件发送到的函数。

  1. 在 Google Cloud 控制台中，点击菜单 &gt; 更多产品 &gt; Google Workspace &gt; 产品库 &gt; Google Chat API &gt; 管理 &gt; 配置。

    前往 Chat API 配置

  2. 在应用名称中，输入 Project Manager。

  3. 在头像网址中输入 https://developers.google.com/chat/images/quickstart-app-avatar.png。

  4. 在说明中，输入 Manages projects with user stories.。

  5. 点击启用互动功能开关，将其切换到“开启”位置。

  6. 在功能下方，依次选择接收 1 对 1 消息和加入聊天室和群组对话。

  7. 在连接设置下，选择应用网址。

  8. 在应用网址中，粘贴您从 Cloud 控制台中复制的触发器网址 函数部署，格式为 https://REGION-PROJECT_ID.cloudfunctions.net/project-management-tutorial。 如果您使用 gcloud CLI 部署了 Cloud Functions 函数，则此参数为 url 属性。

  9. 注册 Chat 应用的 斜杠命令。如需注册斜杠命令，请执行以下操作：

    1. 在斜杠命令下，点击添加斜杠命令。

    2. 对于下表中详述的每条斜杠命令， 输入名称、命令 ID、说明，并选择是 斜杠命令打开对话框，然后点击完成：

      名称 命令 ID 说明 打开对话框
      /createUserStory 1 使用指定标题创建故事。 已取消选择
      /myUserStories 2 列出分配给用户的所有故事。 已取消选择
      /userStory 3 显示指定故事的当前状态。 已取消选择
      /manageUserStories 4 选中该选项可打开一个对话框，供您修改故事。 已选择
      /cleanupUserStories 5 删除聊天室中的所有故事。 已取消选择

  10. 在公开范围下，选择 将此聊天应用设为允许特定人员和群组使用 Workspace 域名，然后输入您的电子邮件地址。

  11. （可选）在日志下，选择将错误记录到 Logging。

  12. 点击保存。系统会显示一条配置已保存的消息，表示 Chat 扩展应用现为 测试。

测试 Chat 应用

通过发送消息测试项目管理 Chat 应用 以及使用斜杠命令创建、修改和删除用户故事。

  1. 使用您用于登录的 Google Workspace 账号打开 Google Chat 在您添加为可信测试员时提供的凭据。

    前往 Google Chat

  2. 点击 发起新对话。
  3. 在添加一人或多人字段中，输入 Chat 应用。

  4. 从结果中选择您的 Chat 应用。直接客户 消息会打开。

  5. 在与应用的新私信对话中，输入“Hello”并 按 enter。项目管理 聊天应用会在响应中提供详细说明的帮助菜单 有哪些用途
  6. 如需创建故事，请在以下位置输入 /createUserStory Test story： 然后发送消息。项目管理 聊天应用会返回一个卡片消息，详细说明 它使用 Vertex AI 中的生成式 AI 为您创作的用户故事。

  7. 在控制台中，检查 Firestore 数据库以查看 关于您添加了 Chat 应用发送给、与其互动过的用户 以及您创建的用户故事

    转到 Firestore

  8. 返回 Google Chat。

    前往 Google Chat

  9. （可选）如需修改故事，请点击修改。如果您对 点击保存。
  10. 测试应用支持的每个斜杠命令。要查看这些建议，请输入 /或提及 Chat 应用。
  11. 通过发出 /cleanupUserStories 删除测试用户故事 斜杠命令。或者 移除或卸载应用。 移除后，该应用会删除在相应聊天室中创建的所有用户故事。

问题排查

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

虽然 Chat 界面中可能不会显示错误消息， 提供描述性错误消息和日志数据，以帮助您修正错误 启用 Chat 应用的错误日志记录时。如需观看方面的帮助， 请参阅 排查并修正 Google Chat 错误。

清理

为避免系统因 我们建议您删除 Cloud 项目中。

  1. 在 Google Cloud 控制台中，前往管理资源页面。点击 菜单 &gt; IAM 和管理员 &gt; 管理资源。

    <ph type="x-smartling-placeholder"></ph> 前往 Resource Manager

  2. 在项目列表中，选择要删除的项目，然后点击 删除 。
  3. 在对话框中输入项目 ID，然后点击关停以删除项目 项目。