此页面由 Cloud Translation API 翻译。

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

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

图 1. Charlie 在 Chat 聊天室中与团队讨论功能开发事宜。提及项目管理 Chat 应用会促使 Chat 应用提供帮助。
图 2. Charlie 使用 /createUserStory 斜杠命令创作了一个故事。
图 3. 项目管理聊天应用使用 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 Function 调用，您可以通过确定您的 Google Cloud 组织是否使用网域限定共享来验证这一点。
如有必要，请向您的 Google Cloud 管理员申请访问权限或使用权限。
如果使用 Google Cloud CLI，则需要配置为可与 gcloud CLI 搭配使用的 Node.js 开发环境。请参阅设置 Node.js 开发环境。

目标

构建一个用于管理敏捷软件项目的聊天应用。
借助由 Vertex AI 提供支持的生成式 AI 辅助故事撰写工具，帮助用户撰写用户故事：
- 生成和重新生成故事描述。
- 将故事描述从注释扩展为完整的要求。
- 更正语法以修正拼写错误。
通过写入 Firestore 数据库和从 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 作为计算平台来运行处理这些事件并做出响应的逻辑。

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 Function 的默认服务账号，您无需进行设置。在生产环境的上下文中，您通常会创建服务账号并将其关联到 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 文件隐式设置。

项目管理聊天应用数据库使用基于文档（整理到集合中）的 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` 托管用户聊天头像图片的网址。
`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: 这些文件包含与处理聊天室、用户和用户故事相关的特定应用逻辑部分。这些文件中的函数由 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: 此目录中的每个文件都会实例化一个 card 对象，然后 Chat 应用会将该对象作为卡片消息或对话框操作响应发送回 Chat。
views/widgets/*.js: 每个文件都会实例化一种微件对象，应用使用该对象在 views/ 目录中构建卡片。
test/**/*.test.js: 此目录及其子目录中的每个文件都包含相应函数、控制器、服务、视图或 widget 的单元测试。您可以在项目的根目录下运行 npm run test 来执行所有单元测试。

创建和部署 Cloud Functions 函数

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

Cloud Functions 函数会运行以响应来自 Chat 的 HTTP 请求，该请求包含 Chat 互动事件。运行时，Cloud Functions 代码会处理该事件，并向 Chat 返回一个响应，Chat 会将该响应呈现为消息、对话框或其他类型的用户互动。如果适用，Cloud Function 还会从 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 Function。
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. 可选：将 us-central1 更新为 Cloud Functions 函数的受支持位置。
点击部署。
函数部署完成后，复制触发网址：
1. 在函数详情页面上，点击触发。
2. 复制网址。您需要此信息才能在下一部分中配置 Chat 应用。

gcloud CLI

从 GitHub 克隆代码：

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

切换到包含此项目管理聊天应用代码的目录：
```
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 Function 基础架构的 Cloud Function 位置，例如 us-central1。

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

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

本部分介绍了如何在 Google Cloud 控制台中配置 Chat API，其中包含有关 Chat 应用的信息，包括 Chat 应用的名称、支持的斜杠命令以及 Chat 应用的 Cloud Function 的触发网址（Chat 应用会将 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.
点击启用互动功能切换开关，以切换到开启位置。
在功能下，选择加入聊天室和群组对话。
在连接设置下，选择 HTTP 端点网址。
在 HTTP 端点网址中，粘贴您从 Cloud Functions 部署中复制的触发器网址，格式为 https://REGION-PROJECT_ID.cloudfunctions.net/project-management-tutorial。如果您使用 gcloud CLI 部署了 Cloud Functions 函数，则此属性为 url。

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

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

名称	命令 ID	说明	命令类型	斜杠命令的名称	打开对话框
创建用户故事	1	创建具有指定标题的故事。	斜杠命令	`/createUserStory`	已取消选择
我的用户故事	2	列出分配给用户的所有故事。	斜杠命令	`/myUserStories`	已取消选择
用户案例	3	显示指定故事的当前状态。	斜杠命令	`/userStory`	已取消选择
管理用户故事	4	打开一个对话框，您可以在其中修改故事。	斜杠命令	`/manageUserStories`	已选择
清理用户故事	5	删除聊天室中的所有报道。	斜杠命令	`/cleanupUserStories`	已取消选择

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

测试 Chat 应用

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

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

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

注意：如果您在结果列表中没有看到自己的 Chat 应用，请确保您已在 Google Cloud 控制台的 Chat API 配置页面中将自己的 Google Workspace 账号纳入公开范围设置。
在与应用来往的新私信中，输入 Hello 并按 enter。项目管理聊天应用会做出响应，显示一个详细说明其功能的帮助菜单。
如需创建故事，请在消息栏中输入 /createUserStory Test story，然后发送。项目管理聊天应用会回复一条卡片消息，其中详细介绍了它使用 Vertex AI 的生成式 AI 为您创建的用户故事。
在控制台中，检查 Firestore 数据库，查看其中创建的记录，这些记录涉及您向其添加了 Chat 应用的聊天室、与该应用互动过的用户以及您创建的用户故事。

转到 Firestore
返回 Google Chat。

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

问题排查

当 Google 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 应用

问题排查

清理

相关主题

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

`spaces`

`userStories`

`users`