本教學課程說明如何建立 Google Chat 擴充應用程式,供團隊即時管理專案。Chat 應用程式會使用 Vertex AI 協助團隊撰寫使用者故事 (從使用者角度呈現軟體系統的功能,供團隊開發),並將故事儲存在 Firestore 資料庫中。
-
圖 1. Charlie 在 Chat 聊天室中與團隊討論功能開發事宜。只要提及專案管理 Chat 應用程式,Chat 應用程式就會提供協助。 -
圖 2. 使用 /createUserStory
斜線指令,Charlie 創作了一則故事。 -
圖 3. 專案管理 Chat 應用程式會使用 Vertex AI 撰寫故事說明,然後在空間中分享故事。 -
圖 4. Charlie 按一下「編輯」,完成故事詳細資料。AI 說明內容準確,但 Charlie 希望有更多詳細資料,因此點選「展開」,讓 Vertex AI 在故事說明中加入需求。Charlie 將故事指派給自己、將狀態設為「已開始」、選取適當的優先順序和大小,然後按一下「儲存」。 -
圖 5. Charlie 隨時可以使用 /manageUserStories
斜線指令,查看及管理團隊的所有使用者故事。
必要條件
- 具有 Google Chat 存取權的 Business 或 Enterprise 版 Google Workspace 帳戶。
存取 Google Cloud 服務,以便執行下列操作:
- 建立 Google Cloud 專案。
- 將 Google Cloud 帳單帳戶連結至 Cloud 專案。如要瞭解您是否具備存取權,請參閱「啟用帳單功能所需的權限」。
使用未經驗證的 Google Cloud Functions 呼叫,您可以判斷 Google Cloud 機構是否使用網域限定共用,藉此驗證。
如有需要,請向 Google Cloud 管理員要求存取權或權限。
如果使用 Google Cloud CLI,則須設定 Node.js 開發環境,以便與 gcloud CLI 搭配使用。請參閱設定 Node.js 開發環境。
目標
- 建構可管理敏捷軟體專案的 Chat 應用程式。
- 透過 Vertex AI 支援的生成式 AI 輔助故事撰寫工具,協助使用者撰寫使用者故事:
- 生成及重新生成故事說明。
- 根據附註擴充故事說明,以符合完整需求。
- 修正文法錯誤,避免錯字。
- 在 Firestore 資料庫中寫入及讀取資料,確保工作內容與時俱進。
- 在 Chat 聊天室中,使用者可以直接從對話建立、編輯、指派及開始處理故事,促進協作。
使用的產品
專案管理應用程式會使用下列 Google Workspace 和 Google Cloud 產品:
- Chat API: 這個 API 可用來開發 Google Chat 應用程式,接收及回應訊息等 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 應用程式的運作方式如下:
使用者在 Chat 中傳送訊息,並透過直接傳送訊息、在聊天室中提及或輸入斜線指令,叫用專案管理 Google Chat 應用程式。
Chat 會向 Cloud Functions 的 HTTP 端點傳送同步 HTTP 要求。
專案管理 Google Chat 應用程式會處理 HTTP 要求:
Vertex AI 可協助撰寫或更新使用者故事。
Firestore 資料庫會儲存、擷取、更新或刪除使用者故事資料。
Cloud Functions 會將 HTTP 回應傳回給 Chat,並以訊息或對話方塊的形式顯示給使用者。
準備環境
本節說明如何為 Chat 應用程式建立及設定 Google Cloud 專案。
建立 Google Cloud 專案
Google Cloud 控制台
- 前往 Google Cloud 控制台,依序點選「選單」圖示 >「IAM 與管理」 >「建立專案」。
-
在「Project Name」(專案名稱) 欄位中,輸入專案的描述性名稱。
選用:如要編輯「專案 ID」,請按一下「編輯」。專案建立後就無法變更專案 ID,因此請選用符合專案執行期間需求的 ID。
- 在「Location」(位置) 欄位中,按一下「Browse」(瀏覽),顯示專案的可能位置。然後按一下「選取」。
- 按一下「建立」,Google Cloud 控制台會前往「資訊主頁」頁面,並在幾分鐘內建立專案。
gcloud CLI
在下列任一開發環境中,存取 Google Cloud CLI (gcloud
):
-
Cloud Shell:如要使用已設定 gcloud CLI 的線上終端機,請啟用 Cloud Shell。
啟用 Cloud Shell -
本機殼層:如要使用本機開發環境,請安裝並初始化 gcloud CLI。
如要建立 Cloud 專案,請使用gcloud projects create
指令: 將 PROJECT_ID 替換為要建立的專案 ID。gcloud projects create PROJECT_ID
啟用 Cloud 專案的計費功能
Google Cloud 控制台
- 前往 Google Cloud 控制台的「帳單」頁面。依序點選「選單」 「帳單」「我的專案」。
- 在「選取機構」中,選擇與 Google Cloud 專案相關聯的機構。
- 在專案列中開啟「動作」選單 ( ),然後按一下「變更帳單」,並選擇 Cloud 帳單帳戶。
- 按一下 [設定帳戶]。
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。
確認您要在正確的 Cloud 專案中啟用 API,然後按一下「下一步」。
確認要啟用的 API 正確無誤,然後按一下「啟用」。
gcloud CLI
如有必要,請使用
gcloud config set project
指令,將目前的 Cloud 專案設為您建立的專案: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 Function。
建立及部署 Google Chat 應用程式
Google Cloud 專案建立及設定完成後,即可建構及部署 Google Chat 應用程式。在本節中,您將完成下列步驟:
- 建立 Firestore 資料庫,用於保存及擷取使用者故事。
- (選用) 查看程式碼範例。
- 建立 Cloud 函式,以便在收到 Chat 傳送的 HTTP 要求時,代管及執行 Chat 應用程式的程式碼。
- 在 Google Chat API 設定頁面建立及部署 Google Chat 應用程式。
建立 Firestore 資料庫
在本節中,您將建立 Firestore 資料庫來保存及擷取使用者故事,但不會定義資料模型。資料模型會在範例程式碼中,由 model/user-story.js
和 model/user.js
檔案隱含設定。
專案管理 Chat 應用程式資料庫採用 NoSQL 資料模型,以整理成Firestore 資料模型。
文件的 集合為基礎。詳情請參閱下圖概述專案管理 Google Chat 應用程式的資料模型:
根層級集合是 spaces
,其中的每個文件都代表 Chat 應用程式建立故事的空間。每個使用者故事都以 userStories
子集合中的文件表示,每個使用者則以 users
子集合中的文件表示。
查看集合、文件和欄位定義
spaces
Chat 應用程式在這些聊天室中建立動態消息。
欄位 | |
---|---|
Document ID | String 建立動態消息的特定空間專屬 ID。對應於 Chat API 中的聊天室資源名稱。 |
userStories | Subcollection of Documents ( 由 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 中的 assignee ,以及 Chat API 中的使用者資源名稱。userStories |
avatarUrl | String 使用者 Google Chat 顯示圖片的網址。 |
displayName | String 使用者的 Chat 顯示名稱。 |
以下說明如何建立 Firestore 資料庫:
Google Cloud 控制台
前往 Google Cloud 控制台中的 Firestore。依序點選「選單」圖示
>「Firestore」。按一下 [Create database] (建立資料庫)。
在「選取 Firestore 模式」中,按一下「原生模式」。
按一下「繼續」。
設定資料庫:
在「為資料庫命名」中,將「資料庫 ID」保留為
(default)
。在「位置類型」中,為資料庫指定區域,例如
us-central1
。為獲得最佳效能,請選取與 Chat 應用程式的 Cloud 函式相同或鄰近的位置。
按一下 [Create database] (建立資料庫)。
gcloud CLI
使用
gcloud firestore databases create
指令,以原生模式建立 Firestore 資料庫:gcloud firestore databases create \ --location=LOCATION \ --type=firestore-native
將 LOCATION 替換為 Firestore 區域的名稱,例如
us-central1
。
查看程式碼範例
(選用) 建立 Cloud Function 前,請先花點時間查看並熟悉 GitHub 上託管的範例程式碼。
以下簡要說明各個檔案:
env.js
- 環境設定變數,可將 Chat 應用程式部署至指定的 Google Cloud 專案和區域。您必須更新這個檔案中的設定變數。
package.json
和package-lock.json
- Node.js 專案設定和依附元件。
index.js
- Chat 應用程式 Cloud Function 的進入點。它會從 HTTP 要求讀取 Chat 事件、呼叫應用程式處理常式,並將 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
- 這個目錄中的每個檔案都會例項化 card 物件,然後 Chat 應用程式會將該物件做為訊息卡或對話方塊動作回應傳回給 Chat。
views/widgets/*.js
- 每個檔案都會例項化應用程式用來在
views/
目錄中建構資訊卡的 widget 物件類型。 test/**/*.test.js
- 這個目錄及其子目錄中的每個檔案,都包含對應函式、控制器、服務、檢視區塊或小工具的單元測試。如要執行所有單元測試,請在專案的根目錄中執行
npm run test
。
建立及部署 Cloud 函式
在本節中,您將建立並部署 Cloud 函式,其中包含專案管理 Chat 應用程式的應用程式邏輯。
Cloud 函式會因應 Chat 的 HTTP 要求而執行,該要求包含 Chat 互動事件。執行時,Cloud Functions 程式碼會處理事件,並將回應傳回 Chat,而 Chat 會將回應顯示為訊息、對話方塊或其他類型的使用者互動。如果適用,Cloud Function 也會從 Firestore 資料庫讀取或寫入資料。
建立 Cloud Function 的方式如下:
Google Cloud 控制台
從 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」頁面:
請確認已選取 Chat 應用程式的 Google Cloud 專案。
按一下
「建立函式」。在「建立函式」頁面中設定函式:
- 在「環境」中,選取「Cloud Run 函式」。
- 在「Function name」(函式名稱) 中輸入
project-management-tutorial
。 - 在「區域」中選取區域。
- 在「Authentication」(驗證) 下方,選取「Allow unauthenticated invocations」(允許未經驗證的叫用)。
- 點選 [下一步]。
在「執行階段」中,選取「Node.js 20」。
在「Entry point」中,刪除預設文字並輸入
projectManagementChatApp
。在「原始碼」中,選取「上傳 ZIP 檔案」。
在「Destination bucket」(目的地值區) 中,建立或選取值區:
- 點選「瀏覽」。
- 選擇 bucket。
- 按一下「選取」。
Google Cloud 會將 ZIP 檔案上傳至這個 bucket,並解壓縮其中的元件檔案。接著,Cloud Functions 會將元件檔案複製到 Cloud Function 中。
在「Zip file」(ZIP 檔案) 欄位中,上傳您從 GitHub 下載、解壓縮並重新壓縮的 ZIP 檔案:
- 點選「瀏覽」。
- 找出並選取 ZIP 檔案。
- 按一下「開啟」。
按一下 [Deploy] (部署)。
「Cloud Functions 詳細資料」頁面隨即開啟,函式會顯示兩個進度指標:一個用於建構,另一個用於服務。當兩個進度指標都消失並顯示勾號時,表示函式已部署完成,可以開始使用。
編輯範例程式碼,設定常數:
- 在「Cloud Function detail」(Cloud 函式詳細資料) 頁面中,按一下「Edit」(編輯)。
- 點選 [下一步]。
- 在「原始碼」中選取「內嵌編輯器」。
- 在內嵌編輯器中開啟
env.js
檔案。 - 使用您的 Cloud 專案 ID 取代 project-id。
- 選用:使用 Cloud Functions 的支援位置更新 us-central1。
按一下 [Deploy] (部署)。
函式部署完成後,請複製觸發網址:
- 在「Function details」(函式詳細資料) 頁面中,按一下「Trigger」(觸發條件)。
- 複製網址。下一節設定 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
檔案,設定環境變數:- 將 project-id 替換為您的 Google Cloud 專案 ID。
- 將 us-central1 替換為您的 Google Cloud 專案位置。
將 Cloud 函式部署至 Google Cloud:
gcloud functions deploy project-management-tutorial \ --gen2 \ --region=REGION \ --runtime=nodejs20 \ --source=. \ --entry-point=projectManagementChatApp \ --trigger-http \ --allow-unauthenticated
請將 REGION 改成基礎架構的託管位置,例如
us-central1
。如需詳細資訊,請參閱 Cloud Functions 位置。
- 函式部署完成後,請從回應中複製
url
屬性。您會在下一節使用這個觸發條件網址,設定 Google Chat 應用程式。
在 Google Cloud 控制台中設定 Google Chat 應用程式
本節說明如何在 Google Cloud 控制台中設定 Chat API,並提供 Chat 擴充應用程式的相關資訊,包括 Chat 擴充應用程式的名稱、支援的斜線指令,以及 Chat 擴充應用程式 Cloud Function 的觸發網址 (Chat 互動事件會傳送至該網址)。
在 Google Cloud 控制台中,依序點選「選單」 >「更多產品」 >「Google Workspace」 >「產品程式庫」 >「Google Chat API」 >「管理」 >「設定」。
在「應用程式名稱」中輸入
Project Manager
。在「Avatar URL」中輸入
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 Function,這就是url
屬性。註冊 Chat 應用程式的斜線指令。如要註冊斜線指令,請按照下列步驟操作:
- 在「指令」下方,按一下「新增指令」。
針對下表詳列的每個斜線指令,輸入「名稱」、「指令 ID」和「說明」,然後選取斜線指令是否「開啟對話方塊」,最後按一下「完成」:
名稱 指令 ID 說明 指令類型 斜線指令名稱 開啟對話方塊 建立使用者故事 1 建立具有指定標題的故事。 斜線指令 /createUserStory
已取消選取 我的使用者故事 2 列出指派給使用者的所有故事。 斜線指令 /myUserStories
已取消選取 使用者故事 3 顯示指定故事的目前狀態。 斜線指令 /userStory
已取消選取 管理使用者故事 4 開啟對話方塊,編輯動態消息。 斜線指令 /manageUserStories
已選取 清理使用者故事 5 刪除聊天室中的所有動態消息。 斜線指令 /cleanupUserStories
已取消選取
在「顯示設定」下方,選取「將這個 Chat 擴充應用程式提供給 Workspace 網域中的特定使用者和群組」,然後輸入電子郵件地址。
(選用) 在「記錄」下方,選取「將錯誤記錄到 Logging」。
按一下 [儲存]。系統會顯示「已儲存設定」訊息,表示 Chat 應用程式已可供測試。
測試 Chat 應用程式
傳送訊息給專案管理 Chat 應用程式,並使用斜線指令建立、編輯及刪除使用者故事,測試該應用程式。
使用您在新增自己為信任測試人員時提供的 Google Workspace 帳戶,開啟 Google Chat。
- 按一下 「發起新即時通訊」。
- 在「新增 1 位以上使用者」欄位中,輸入 Chat 應用程式的名稱。
從結果中選取 Chat 應用程式。系統會開啟即時訊息。
- 在與應用程式互傳的新即時訊息中輸入
Hello
,然後按下enter
。專案管理 Chat 應用程式會回覆說明選單,詳細列出可執行的動作。 - 如要建立故事,請在訊息列中輸入
/createUserStory Test story
並傳送。專案管理聊天應用程式會回覆一張資訊卡訊息,詳細說明使用 Vertex AI 生成式 AI 為您建立的使用者故事。 在控制台中,檢查 Firestore 資料庫,查看系統為您新增 Chat 應用程式的聊天室建立的記錄、與該聊天室互動的使用者,以及您建立的使用者故事。
返回 Google Chat。
- 如要編輯故事,請按一下「編輯」。確認故事內容正確無誤後,按一下「儲存」。
- 測試應用程式支援的每個斜線指令。如要查看這些指令,請輸入
/
或提及 Google Chat 應用程式。 - 發出
/cleanupUserStories
斜線指令,刪除測試使用者故事。或者,移除或解除安裝應用程式。移除後,應用程式會刪除該空間中建立的所有使用者故事。
疑難排解
如果 Google Chat 應用程式或資訊卡傳回錯誤,Chat 介面會顯示「發生錯誤」訊息。或「無法處理您的要求」。有時 Chat UI 不會顯示任何錯誤訊息,但 Chat 應用程式或資訊卡會產生非預期結果,例如資訊卡訊息可能不會顯示。
即使 Chat 使用者介面未顯示錯誤訊息,只要開啟 Chat 應用程式的錯誤記錄功能,系統就會提供說明性錯誤訊息和記錄資料,協助您修正錯誤。如需查看、偵錯及修正錯誤的相關協助,請參閱「排解及修正 Google Chat 錯誤」。
清除所用資源
如要避免系統向您的 Google Cloud 帳戶收取本教學課程中所用資源的相關費用,建議您刪除 Cloud 專案。
- 在 Google Cloud 控制台中,前往「管理資源」頁面。依序點選「選單」 「IAM 與管理」「管理資源」。
- 在專案清單中選取要刪除的專案,然後按一下「Delete」(刪除) 圖示 。
- 在對話方塊中輸入專案 ID,然後按一下「Shut down」(關閉) 即可刪除專案。