此页面由 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 想要了解更多详细信息，因此 Charlie 点击了展开，让 Vertex AI 向故事说明中添加要求。Charlie 将故事分配给自己，将状态设置为“已开始”，选择相应的优先级和大小，然后点击保存。
图 5. Charlie 可以随时使用 /manageUserStories 斜杠命令查看和管理团队的所有用户故事。

前提条件

拥有对 Google Chat 访问权限的商务版或企业版 Google Workspace 账号。
访问 Google Cloud 服务，以执行以下操作：
- 创建 Google Cloud 项目。
- 将 Google Cloud 结算账号与 Cloud 项目相关联。如需了解您是否具有访问权限，请参阅启用结算功能所需的权限。
- 使用未经身份验证的 Google Cloud 函数调用。您可以通过确定您的 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：一种用于开发 Google Chat 应用的 API，可接收和响应 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 会将其作为消息或对话框显示给用户。

准备环境

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

创建 Google Cloud 项目

Google Cloud 控制台

在 Google Cloud 控制台中，依次点击“菜单”图标 > IAM 和管理 > 创建项目。
前往“创建项目”页面
在 Project Name 字段中，为项目输入一个描述性名称。
可选：要修改项目 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: 用于处理卡片点击 Chat 互动事件的应用逻辑。
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: 调用 Vertex AI API 以进行生成式 AI 文本预测。
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 的 HTTP 请求，其中包含 Chat 互动事件。运行时，Cloud Functions 代码会处理事件，并向 Chat 返回响应，Chat 会将响应呈现为消息、对话框或其他类型的用户互动。Cloud Functions 还会从 Firestore 数据库读取或向其中写入数据（如果适用）。

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

Google Cloud 控制台

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

下载 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.
点击启用互动功能开关，将其切换到“开启”位置。
在功能下方，依次选择接收 1 对 1 消息和加入聊天室和群组对话。
在连接设置下，选择 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
点击 发起新对话。
在添加 1 人或更多人字段中，输入 Chat 应用的名称。
从结果中选择您的 Chat 应用。系统随即会打开一条私信。

注意：如果您在结果列表中没有看到您的 Chat 应用，请确保您已在 Google Cloud 控制台的 Chat API 配置页面的公开范围设置中添加了您的 Google Workspace 账号。
在与应用的新私信对话中，输入 Hello 并按 enter。项目管理 Chat 应用会返回一个帮助菜单，其中详细说明了它可以执行的操作。
如需创建故事，请在消息栏中输入 /createUserStory Test story 并发送。项目管理聊天应用会回复一条卡片消息，详细说明它使用 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 和管理 > 管理资源。
前往资源管理器
在项目列表中，选择要删除的项目，然后点击删除。
在对话框中输入项目 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`