此页面由 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 点击 Edit（修改），最终确定故事详细信息。AI 说明准确无误，但 Charlie 想要更多详细信息，因此 Charlie 点击了展开，让 Vertex AI 向故事说明中添加要求。小强将故事分配给自己，将状态设置为“已开始”，选择合适的优先级和大小，然后点击保存。
图 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，用于开发可接收和响应聊天互动事件（如消息）的 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 托管 HTTP 端点，Chat 会将互动事件发送到此端点，并作为计算平台运行处理和响应这些事件的逻辑。

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：如需使用本地开发环境，请安装并initialize gcloud CLI。
如需创建 Cloud 项目，请使用“gcloud projects create”命令：
```
gcloud projects create PROJECT_ID
```
为要创建的项目设置 ID，以替换 PROJECT_ID。

为 Cloud 项目启用结算功能

Google Cloud 控制台

在 Google Cloud 控制台中，前往结算。点击 Menu 图标 > Billing > My Projects。
前往“我的项目”的“结算”页面
在选择组织中，选择与您的 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 应用的代码，以响应从 Chat 收到的 HTTP 请求事件。
在 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 请求中读取 Chat 事件、调用应用处理程序，并将 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: 调用 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 函数

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

Cloud Functions 函数用于响应来自 Chat 的包含 Chat 互动事件的 HTTP 请求。运行时，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. 在环境中，选择第 2 代。
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 应用

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

在 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 消息、加入聊天室和群组对话。
在连接设置下，选择应用网址。
在应用网址中，粘贴您从 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 网域中的特定用户和群组使用，然后输入您的电子邮件地址。
（可选）在日志下，选择将错误记录到 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 并发送故事。项目管理 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`