此页面由 Cloud Translation API 翻译。

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

本教程介绍了如何构建 Google Chat 应用，供团队实时管理项目。Chat 应用使用 Vertex AI 帮助团队编写用户故事（从用户的角度描述软件系统的功能，供团队开发），并将这些故事保留在 Firestore 数据库中。

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

前提条件

拥有对 Google Chat 访问权限的商务版或企业版 Google Workspace 账号。
能够访问 Google Cloud 服务以执行以下操作：
- 创建 Google Cloud 项目。
- 将 Google Cloud 结算账号与 Cloud 项目相关联。如需了解您是否具有访问权限，请参阅启用结算功能所需的权限。
- 使用未经身份验证的 Google Cloud Functions 函数调用（您可以通过确定您的 Google Cloud 组织是否使用网域限定共享来验证这一点）。
如有必要，请向您的 Google Cloud 管理员申请访问权限。
如果使用 Google Cloud CLI，则需要一个配置为与 gcloud CLI 搭配使用的 Node.js 开发环境。请参阅设置 Node.js 开发环境。

目标

构建一个用于管理敏捷软件项目的 Chat 应用。
借助由 Vertex AI 提供支持的生成式 AI 辅助故事创作工具，帮助用户撰写用户故事：
- 生成和重新生成故事说明。
- 从备注中展开故事说明，以满足要求。
- 更正语法以修正拼写错误。
通过向 Firestore 数据库写入和从中读取数据，及时更新工作。
让用户能够直接在对话中创建、修改、分配和启动故事，从而促进在 Chat 聊天室中协作。

使用的产品

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

Chat API：此 API 用于开发接收和响应 Chat 互动事件（如消息）的 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 端点接收和处理 Chat 互动事件，使用 Vertex AI 帮助撰写用户故事，并将用户故事详细信息存储在 Firestore 数据库中。下图显示了所用 Google Workspace 和 Google Cloud 资源的架构。

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

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

用户在 Chat 中发送消息，然后通过直接向其发送消息、在聊天室中提及该应用或输入正斜线命令来调用项目管理 Google Chat 应用。
Chat 会向 Cloud Functions 函数的 HTTP 端点发送同步 HTTP 请求。
项目管理 Google Chat 应用会处理 HTTP 请求：
1. Vertex AI 可帮助编写或更新用户故事。
2. Firestore 数据库用于存储、检索、更新或删除用户故事数据。
Cloud Functions 向 Chat 返回 HTTP 响应，以消息或对话框的形式向用户显示响应。

准备环境

本部分介绍如何为 Chat 应用创建和配置 Google Cloud 项目。

创建 Google Cloud 项目

Google Cloud 控制台

在 Google Cloud 控制台中，依次点击“菜单”图标 > IAM 和管理 > 创建项目。
前往“创建项目”页面
在项目名称字段中，为项目输入描述性名称。
可选：如需修改项目 ID，请点击修改。项目创建后便无法更改项目 ID，因此请选择满足项目生命周期需求的 ID。
在位置字段中，点击浏览以显示项目的可能位置。然后，点击选择。
注意：找不到您的 Google Workspace 组织？
这意味着您未登录 Google Workspace 账号。Google Workspace 开发者文档中描述的某些功能仅适用于与组织关联的项目。
点击创建。Google Cloud 控制台会转到“信息中心”页面，您的项目会在几分钟内创建完毕。

gcloud CLI

在以下任一开发环境中，访问 Google Cloud CLI (gcloud)：

Cloud Shell：如需使用已设置 gcloud CLI 的在线终端，请激活 Cloud Shell。
激活 Cloud Shell
本地 Shell：如需使用本地开发环境，请安装并初始化 gcloud CLI。
如需创建 Cloud 项目，请使用 gcloud projects create 命令：
```
gcloud projects create PROJECT_ID
```
为要创建的项目设置 ID，从而替换 PROJECT_ID。

为 Cloud 项目启用结算功能

Google Cloud 控制台

在 Google Cloud 控制台中，前往结算。依次点击菜单 > 结算> 我的项目。
转到“我的项目的结算”
在选择组织中，选择与您的 Google Cloud 项目关联的组织。
在项目行中，打开操作菜单 ()，点击更改结算信息，然后选择 Cloud Billing 账号。
点击设置账号。

gcloud CLI

如需列出可用的结算账号，请运行以下命令：
```
gcloud billing accounts list
```
将结算账号与 Google Cloud 项目相关联：
```
gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID
```
替换以下内容：
- PROJECT_ID 是您要启用结算功能的 Cloud 项目的项目 ID。
- BILLING_ACCOUNT_ID 是与 Google Cloud 项目关联的结算账号 ID。

启用 API

Google Cloud 控制台

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

启用 API
确认您是在正确的 Cloud 项目中启用 API，然后点击下一步。
确认您要启用的 API 正确无误，然后点击启用。

gcloud CLI

如有必要，请将当前 Cloud 项目设置为您使用 gcloud config set project 命令创建的项目：
```
gcloud config set project PROJECT_ID
```
将 PROJECT_ID 替换为您创建的 Cloud 项目的项目 ID。
使用 gcloud services enable 命令启用 Google Chat API、Vertex AI API、Cloud Functions API、Firestore API、Cloud Build API、Pub/Sub API 和 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 的默认服务账号搭配使用，您无需进行设置。在生产环境中，您通常会改为创建并关联服务账号到 Cloud Functions 函数。

创建和部署 Google Chat 应用

现在，您的 Google Cloud 项目已创建并配置完毕，您可以开始构建和部署 Google Chat 应用了。在本部分中，您将执行以下操作：

创建一个 Firestore 数据库，用于持久存储和检索用户故事。
（可选）查看示例代码。
创建一个 Cloud Functions 函数，以托管并运行 Chat 应用的代码，以响应以 HTTP 请求形式从 Chat 收到的事件。
在 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 ID`	`String` 创建故事的特定空间的唯一 ID。与 Chat API 中的聊天室资源名称对应。
`userStories`	`Subcollection of Documents (userStories)` Chat 应用及其用户创建的短片故事。对应于 Firebase 中 `userStories` 的 `Document ID`。
`users`	`Subcollection of Documents (user)` 创建故事或获得故事的用户。
`displayName`	`String` Chat API 中聊天室的显示名称。未针对与用户的私信设置。

`userStories`

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

字段
`Document ID`	`String` 由 Chat 应用及其用户创建的特定用户故事的唯一 ID。
`assignee`	`Document (user)` 分配完成故事的用户的资源名称。与 `users` 文档的 `Document ID` 和 Chat API 中的用户资源名称相对应。
`description`	`String` 从用户角度描述软件功能。
`priority`	`Enum` 完成工作的紧迫性。可能的值包括 `Low`、`Medium` 或 `High`。
`size`	`Enum` 工作量。可能的值为 `Small`、`Medium` 或 `Large`。
`status`	`Enum` 工作阶段。可能的值为 `OPEN`、`STARTED` 或 `COMPLETED`。
`title`	`String` 故事的标题；简短摘要。

`users`

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

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

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

Google Cloud 控制台

在 Google Cloud 控制台中，前往 Firestore。依次点击菜单 > Firestore。

转到 Firestore
点击创建数据库。
从选择您的 Firestore 模式中，点击原生模式。
点击继续。
配置数据库：
1. 在为数据库命名中，将数据库 ID 保留为 (default)。
2. 在位置类型中，为数据库指定一个区域，例如 us-central1。为获得最佳性能，请选择与 Chat 应用的 Cloud Functions 函数相同或附近的位置。
点击创建数据库。

gcloud CLI

使用 gcloud firestore databases create 命令创建原生模式下的 Firestore 数据库：
```
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: 此目录及其子目录中的每个文件都包含相应函数、控制器、服务、视图或 widget 的单元测试。您可以在项目的根目录中运行 npm run test 来执行所有单元测试。

创建和部署 Cloud Functions 函数

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

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

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

Google Cloud 控制台

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

下载 zip 文件
解压缩下载的 ZIP 文件。

解压缩的文件夹包含整个 Google Workspace 示例代码库。
在解压缩的文件夹中，前往 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/
在 Google Cloud 控制台中，转到 Cloud Functions 页面：

转到 Cloud Functions

确保为您的 Chat 应用选择了 Google Cloud 项目。
点击 创建函数。
在创建函数页面上，设置您的函数：
1. 在环境中，选择 Cloud Run Functions。
2. 在函数名称中，输入 project-management-tutorial。
3. 在区域中，选择一个区域。
4. 在身份验证下，选择允许未通过身份验证的调用。
5. 点击下一步。
在运行时中，选择 Node.js 20。
在入口点中，删除默认文本并输入 projectManagementChatApp。
在源代码中，选择 Zip 文件上传。
在目标存储桶中，创建或选择一个存储桶：
1. 点击浏览。
2. 选择存储桶。
3. 点击选择。
Google Cloud 会将该 zip 文件上传到此存储桶，并在其中提取组件文件。然后，Cloud Functions 会将组件文件复制到 Cloud Functions 函数中。
在 Zip 文件中，上传您从 GitHub 下载、解压并重新压缩的 ZIP 文件：
1. 点击浏览。
2. 找到并选择该 ZIP 文件。
3. 点击打开。
点击部署。

Cloud Functions 详情页面随即打开，您的函数会显示两个进度指示器：一个用于构建，另一个用于服务。当两个进度指示器消失并被对勾标记取代时，表示您的函数已部署且可以使用。
修改示例代码以设置常量：
1. 在 Cloud Functions 函数详情页面上，点击修改。
2. 点击下一步。
3. 在源代码中，选择内嵌编辑器。
4. 在内嵌编辑器中，打开 env.js 文件。
5. 将 project-id 替换为您的 Cloud 项目 ID。
6. 可选：使用 Cloud Functions 函数的受支持的位置更新 us-central1。
点击部署。
函数部署完成后，复制触发器网址：
1. 在函数详情页面上，点击触发器。
2. 复制网址。您需要使用它来配置下一部分中的 Chat 应用。

gcloud CLI

从 GitHub 克隆代码：

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

切换到存放此项目管理 Chat 应用代码的目录：
```
cd google-chat-samples/node/project-management-app
```
修改 env.js 文件以设置环境变量：
1. 将 project-id 替换为您的 Google Cloud 项目 ID。
2. 将 us-central1 替换为您的 Google Cloud 项目位置。

将 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。

当函数部署完毕后，请从响应中复制 url 属性。这是您在下一部分中用于配置 Google Chat 应用的触发器网址。

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

本部分介绍了如何在 Google Cloud 控制台中使用 Chat 应用的相关信息（包括 Chat 应用的名称、支持的斜杠命令，以及 Chat 应用发送 Chat 互动事件的 Cloud Functions 函数的触发器网址）配置 Chat API。

在 Google Cloud 控制台中，依次点击菜单 > 更多产品 > Google Workspace > 产品库 > Google Chat API > 管理 > 配置。

前往 Chat API 配置
在应用名称中，输入 Project Manager。
在头像网址中输入 https://developers.google.com/chat/images/quickstart-app-avatar.png。
在说明中，输入 Manages projects with user stories.
点击启用互动功能开关，将其切换到“开启”位置。
在功能下，选择接收一对一消息、加入聊天室和群组对话。
在连接设置下，选择 HTTP 端点网址。
在 HTTP 端点网址中，粘贴您从 Cloud Functions 部署中复制的触发器网址，格式为 https://REGION-PROJECT_ID.cloudfunctions.net/project-management-tutorial。如果您使用 gcloud CLI 部署了 Cloud Functions 函数，那么此属性为 url 属性。

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

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

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

在公开范围下，选择面向 Workspace 网域中的特定人员和群组提供此 Chat 应用，然后输入您的电子邮件地址。
（可选）在日志下，选择将错误记录到 Logging。
点击保存。系统会显示一条已保存的配置消息，表示 Chat 应用已准备好进行测试。

测试 Chat 应用

测试项目管理 Chat 应用，方法是向其发送消息，并使用其斜杠命令创建、修改和删除用户故事。

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

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

注意：如果结果列表中未显示您的 Chat 应用，请确保您已在 Google Cloud 控制台 Chat API 配置页面的公开范围设置中添加了您的 Google Workspace 账号。
在与该应用的新私信对话中，输入 Hello 并按 enter。项目管理 Chat 应用会返回一个帮助菜单，其中详细说明了它可以执行的操作。
如需创建故事，请在消息栏中输入 /createUserStory Test story 并发送。项目管理 Chat 应用会返回一张卡片消息，详细说明它使用 Vertex AI 中的生成式 AI 为您创建的用户故事。
在控制台中，检查 Firestore 数据库，查看它创建的关于您添加了 Chat 应用的聊天室、与其互动的用户以及您创建的用户故事的记录。

转到 Firestore
返回 Google Chat。

前往 Google Chat
（可选）如需修改故事，请点击修改。对故事满意后，点击保存。
测试应用支持的每个斜杠命令。如需查看这些命令，请输入 / 或提及 Chat 应用。
发出 /cleanupUserStories 斜杠命令以删除测试用户故事。或者，移除或卸载该应用。移除后，该应用会删除在相应空间中创建的所有用户故事。

问题排查

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

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

清理

为避免因本教程中使用的资源导致您的 Google Cloud 账号产生费用，我们建议您删除 Cloud 项目。

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

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

前提条件

目标

使用的产品

架构

准备环境

创建 Google Cloud 项目

Google Cloud 控制台

gcloud CLI

为 Cloud 项目启用结算功能

Google Cloud 控制台

gcloud CLI

启用 API

Google Cloud 控制台

gcloud CLI

身份验证和授权

创建和部署 Google Chat 应用

创建 Firestore 数据库

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

spaces

userStories

users

Google Cloud 控制台

gcloud CLI

查看示例代码

创建和部署 Cloud Functions 函数

Google Cloud 控制台

gcloud CLI

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

测试 Chat 应用

问题排查

清理

相关主题

`spaces`

`userStories`

`users`