使用 Google Chat、Vertex AI 和 Firestore 管理專案

本教學課程說明如何建立 Google Chat 擴充應用程式,供團隊即時管理專案。Chat 應用程式會使用 Vertex AI 協助團隊撰寫使用者故事 (從使用者角度呈現軟體系統的功能,供團隊開發),並將故事儲存在 Firestore 資料庫中。

  • 只要提及專案管理應用程式,應用程式就會提供協助。
    圖 1. Charlie 在 Chat 聊天室中與團隊討論功能開發事宜。只要提及專案管理 Chat 應用程式,Chat 應用程式就會提供協助。
  • 使用 /createUserStory 斜線指令建立故事。
    圖 2. 使用 /createUserStory 斜線指令,Charlie 創作了一則故事。
  • 專案管理聊天應用程式會使用 Vertex AI 撰寫故事說明。
    圖 3. 專案管理 Chat 應用程式會使用 Vertex AI 撰寫故事說明,然後在空間中分享故事。
  • Charlie 統整故事詳細資料。
    圖 4. Charlie 按一下「編輯」,完成故事詳細資料。AI 說明內容準確,但 Charlie 希望有更多詳細資料,因此點選「展開」,讓 Vertex AI 在故事說明中加入需求。Charlie 將故事指派給自己、將狀態設為「已開始」、選取適當的優先順序和大小,然後按一下「儲存」
  • 管理團隊的所有使用者故事。
    圖 5. Charlie 隨時可以使用 /manageUserStories 斜線指令,查看及管理團隊的所有使用者故事。

必要條件

目標

  • 建構可管理敏捷軟體專案的 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 應用程式的架構圖

專案管理 Google Chat 應用程式的運作方式如下:

  1. 使用者在 Chat 中傳送訊息,並透過直接傳送訊息、在聊天室中提及或輸入斜線指令,叫用專案管理 Google Chat 應用程式。

  2. Chat 會向 Cloud Functions 的 HTTP 端點傳送同步 HTTP 要求。

  3. 專案管理 Google Chat 應用程式會處理 HTTP 要求:

    1. Vertex AI 可協助撰寫或更新使用者故事。

    2. Firestore 資料庫會儲存、擷取、更新或刪除使用者故事資料。

  4. Cloud Functions 會將 HTTP 回應傳回給 Chat,並以訊息或對話方塊的形式顯示給使用者。

準備環境

本節說明如何為 Chat 應用程式建立及設定 Google Cloud 專案。

建立 Google Cloud 專案

Google Cloud 控制台

  1. 前往 Google Cloud 控制台,依序點選「選單」圖示 >「IAM 與管理」 >「建立專案」

    前往「建立專案」

  2. 在「Project Name」(專案名稱) 欄位中,輸入專案的描述性名稱。

    選用:如要編輯「專案 ID」,請按一下「編輯」。專案建立後就無法變更專案 ID,因此請選用符合專案執行期間需求的 ID。

  3. 在「Location」(位置) 欄位中,按一下「Browse」(瀏覽),顯示專案的可能位置。然後按一下「選取」
  4. 按一下「建立」,Google Cloud 控制台會前往「資訊主頁」頁面,並在幾分鐘內建立專案。

gcloud CLI

在下列任一開發環境中,存取 Google Cloud CLI (gcloud):

  • Cloud Shell:如要使用已設定 gcloud CLI 的線上終端機,請啟用 Cloud Shell。
    啟用 Cloud Shell
  • 本機殼層:如要使用本機開發環境,請安裝初始化 gcloud CLI。
    如要建立 Cloud 專案,請使用 gcloud projects create 指令:
    gcloud projects create PROJECT_ID
    PROJECT_ID 替換為要建立的專案 ID。

啟用 Cloud 專案的計費功能

Google Cloud 控制台

  1. 前往 Google Cloud 控制台的「帳單」頁面。依序點選「選單」「帳單」「我的專案」

    前往「我的專案」的帳單頁面

  2. 在「選取機構」中,選擇與 Google Cloud 專案相關聯的機構。
  3. 在專案列中開啟「動作」選單 (),然後按一下「變更帳單」,並選擇 Cloud 帳單帳戶。
  4. 按一下 [設定帳戶]

gcloud CLI

  1. 如要列出可用的帳單帳戶,請執行下列指令:
    gcloud billing accounts list
  2. 將帳單帳戶連結至 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 控制台

  1. 在 Google Cloud 控制台中,啟用 Google Chat API、Vertex AI API、Cloud Functions API、Firestore API、Cloud Build API、Pub/Sub API 和 Cloud Run Admin API。

    啟用 API

  2. 確認您要在正確的 Cloud 專案中啟用 API,然後按一下「下一步」

  3. 確認要啟用的 API 正確無誤,然後按一下「啟用」

gcloud CLI

  1. 如有必要,請使用 gcloud config set project 指令,將目前的 Cloud 專案設為您建立的專案:

    gcloud config set project PROJECT_ID

    PROJECT_ID 替換為您建立的 Cloud 專案的專案 ID

  2. 使用 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 應用程式。在本節中,您將完成下列步驟:

  1. 建立 Firestore 資料庫,用於保存及擷取使用者故事。
  2. (選用) 查看程式碼範例。
  3. 建立 Cloud 函式,以便在收到 Chat 傳送的 HTTP 要求時,代管及執行 Chat 應用程式的程式碼。
  4. 在 Google Chat API 設定頁面建立及部署 Google Chat 應用程式。

建立 Firestore 資料庫

在本節中,您將建立 Firestore 資料庫來保存及擷取使用者故事,但不會定義資料模型。資料模型會在範例程式碼中,由 model/user-story.jsmodel/user.js 檔案隱含設定。

專案管理 Chat 應用程式資料庫採用 NoSQL 資料模型,以整理成 文件 集合為基礎。詳情請參閱 Firestore 資料模型

下圖概述專案管理 Google Chat 應用程式的資料模型:

Firestore 資料庫的資料模型。

根層級集合是 spaces,其中的每個文件都代表 Chat 應用程式建立故事的空間。每個使用者故事都以 userStories 子集合中的文件表示,每個使用者則以 users 子集合中的文件表示。

查看集合、文件和欄位定義

spaces

Chat 應用程式在這些聊天室中建立動態消息。

欄位
Document IDString
建立動態消息的特定空間專屬 ID。對應於 Chat API 中的聊天室資源名稱。
userStoriesSubcollection of Documents (userStories)
由 Chat 應用程式及其使用者建立的故事。對應 Firebase 中 userStoriesDocument ID
usersSubcollection of Documents (user)
建立或獲派故事的使用者。
displayNameString
Chat API 中聊天室的顯示名稱。不會為使用者之間的即時訊息設定。

userStories

由 Chat 應用程式及其使用者建立的故事。

欄位
Document IDString
Chat 應用程式及其使用者建立的特定使用者故事專屬 ID。
assigneeDocument (user)
:獲派完成故事的使用者資源名稱。對應於 users 文件的 Document ID,以及 Chat API 中的使用者資源名稱。
descriptionString
從使用者角度描述軟體功能。
priorityEnum
完成工作的緊急程度。可能的值為 LowMediumHigh
sizeEnum
工作量。可能的值為 SmallMediumLarge
statusEnum
工作階段。可能的值為 OPENSTARTEDCOMPLETED
titleString
故事標題;簡短摘要。

users

建立或獲派故事的使用者。

欄位
Document IDString
特定使用者的專屬 ID。對應於 Firebase 中的 assignee,以及 Chat API 中的使用者資源名稱。userStories
avatarUrlString
使用者 Google Chat 顯示圖片的網址。
displayNameString
使用者的 Chat 顯示名稱。

以下說明如何建立 Firestore 資料庫:

Google Cloud 控制台

  1. 前往 Google Cloud 控制台中的 Firestore。依序點選「選單」圖示 >「Firestore」

    前往 Firestore

  2. 按一下 [Create database] (建立資料庫)。

  3. 在「選取 Firestore 模式」中,按一下「原生模式」

  4. 按一下「繼續」

  5. 設定資料庫:

    1. 在「為資料庫命名」中,將「資料庫 ID」保留為 (default)

    2. 在「位置類型」中,為資料庫指定區域,例如 us-central1。為獲得最佳效能,請選取與 Chat 應用程式的 Cloud 函式相同或鄰近的位置。

  6. 按一下 [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 上託管的範例程式碼。

前往 GitHub 查看

以下簡要說明各個檔案:

env.js
環境設定變數,可將 Chat 應用程式部署至指定的 Google Cloud 專案和區域。您必須更新這個檔案中的設定變數。
package.jsonpackage-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.jsservices/user-service.jsservices/user-story-service.js
這些檔案包含應用程式邏輯,專門用於處理 Chat 聊天室、使用者和使用者故事。這些檔案中的函式是由 app.jsapp-action-handler.js 呼叫。如要執行資料庫作業,這些檔案中的函式會呼叫 firestore-service.js 中的函式。
services/firestore-service.js
處理資料庫作業。 這個檔案中的函式是由 services/space-service.jsservices/user-service.jsservices/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 控制台

  1. 從 GitHub 下載程式碼 (ZIP 檔案)。

    下載 ZIP 檔案

  2. 將下載的 ZIP 檔案解壓縮。

    解壓縮的資料夾包含整個 Google Workspace 範例存放區。

  3. 在解壓縮的資料夾中,前往 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/
  4. 前往 Google Cloud 控制台的「Cloud Functions」頁面:

    前往 Cloud Functions 頁面

    請確認已選取 Chat 應用程式的 Google Cloud 專案。

  5. 按一下 「建立函式」

  6. 在「建立函式」頁面中設定函式:

    1. 在「環境」中,選取「Cloud Run 函式」
    2. 在「Function name」(函式名稱) 中輸入 project-management-tutorial
    3. 在「區域」中選取區域。
    4. 在「Authentication」(驗證) 下方,選取「Allow unauthenticated invocations」(允許未經驗證的叫用)
    5. 點選 [下一步]。
  7. 在「執行階段」中,選取「Node.js 20」

  8. 在「Entry point」中,刪除預設文字並輸入 projectManagementChatApp

  9. 在「原始碼」中,選取「上傳 ZIP 檔案」

  10. 在「Destination bucket」(目的地值區) 中,建立或選取值區:

    1. 點選「瀏覽」
    2. 選擇 bucket。
    3. 按一下「選取」

    Google Cloud 會將 ZIP 檔案上傳至這個 bucket,並解壓縮其中的元件檔案。接著,Cloud Functions 會將元件檔案複製到 Cloud Function 中。

  11. 在「Zip file」(ZIP 檔案) 欄位中,上傳您從 GitHub 下載、解壓縮並重新壓縮的 ZIP 檔案:

    1. 點選「瀏覽」
    2. 找出並選取 ZIP 檔案。
    3. 按一下「開啟」
  12. 按一下 [Deploy] (部署)

    「Cloud Functions 詳細資料」頁面隨即開啟,函式會顯示兩個進度指標:一個用於建構,另一個用於服務。當兩個進度指標都消失並顯示勾號時,表示函式已部署完成,可以開始使用。

  13. 編輯範例程式碼,設定常數:

    1. 在「Cloud Function detail」(Cloud 函式詳細資料) 頁面中,按一下「Edit」(編輯)
    2. 點選 [下一步]。
    3. 在「原始碼」中選取「內嵌編輯器」
    4. 在內嵌編輯器中開啟 env.js 檔案。
    5. 使用您的 Cloud 專案 ID 取代 project-id
    6. 選用:使用 Cloud Functions 的支援位置更新 us-central1
  14. 按一下 [Deploy] (部署)

  15. 函式部署完成後,請複製觸發網址:

    1. 在「Function details」(函式詳細資料) 頁面中,按一下「Trigger」(觸發條件)
    2. 複製網址。下一節設定 Chat 應用程式時會用到。

gcloud CLI

  1. 從 GitHub 複製程式碼:

    git clone https://github.com/googleworkspace/google-chat-samples.git
  2. 切換至包含這個專案管理 Chat 應用程式程式碼的目錄:

    cd google-chat-samples/node/project-management-app
  3. 編輯 env.js 檔案,設定環境變數:

    1. project-id 替換為您的 Google Cloud 專案 ID。
    2. us-central1 替換為您的 Google Cloud 專案位置。
  4. 將 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 位置

  1. 函式部署完成後,請從回應中複製 url 屬性。您會在下一節使用這個觸發條件網址,設定 Google Chat 應用程式。

在 Google Cloud 控制台中設定 Google Chat 應用程式

本節說明如何在 Google Cloud 控制台中設定 Chat API,並提供 Chat 擴充應用程式的相關資訊,包括 Chat 擴充應用程式的名稱、支援的斜線指令,以及 Chat 擴充應用程式 Cloud Function 的觸發網址 (Chat 互動事件會傳送至該網址)。

  1. 在 Google Cloud 控制台中,依序點選「選單」 >「更多產品」 >「Google Workspace」 >「產品程式庫」 >「Google Chat API」 >「管理」 >「設定」

    前往 Chat API 設定

  2. 在「應用程式名稱」中輸入 Project Manager

  3. 在「Avatar URL」中輸入 https://developers.google.com/chat/images/quickstart-app-avatar.png

  4. 在「說明」中輸入 Manages projects with user stories.

  5. 將「啟用互動功能」切換鈕設為開啟。

  6. 在「功能」下方,選取「加入聊天室和群組對話」

  7. 在「連線設定」下方,選取「HTTP 端點網址」

  8. 在「HTTP 端點網址」中,貼上從 Cloud Functions 部署作業複製的觸發條件網址,格式為 https://REGION-PROJECT_ID.cloudfunctions.net/project-management-tutorial。如果您是使用 gcloud CLI 部署 Cloud Function,這就是 url 屬性。

  9. 註冊 Chat 應用程式的斜線指令。如要註冊斜線指令,請按照下列步驟操作:

    1. 在「指令」下方,按一下「新增指令」
    2. 針對下表詳列的每個斜線指令,輸入「名稱」、「指令 ID」和「說明」,然後選取斜線指令是否「開啟對話方塊」,最後按一下「完成」

      名稱 指令 ID 說明 指令類型 斜線指令名稱 開啟對話方塊
      建立使用者故事 1 建立具有指定標題的故事。 斜線指令 /createUserStory 已取消選取
      我的使用者故事 2 列出指派給使用者的所有故事。 斜線指令 /myUserStories 已取消選取
      使用者故事 3 顯示指定故事的目前狀態。 斜線指令 /userStory 已取消選取
      管理使用者故事 4 開啟對話方塊,編輯動態消息。 斜線指令 /manageUserStories 已選取
      清理使用者故事 5 刪除聊天室中的所有動態消息。 斜線指令 /cleanupUserStories 已取消選取
  10. 在「顯示設定」下方,選取「將這個 Chat 擴充應用程式提供給 Workspace 網域中的特定使用者和群組」,然後輸入電子郵件地址。

  11. (選用) 在「記錄」下方,選取「將錯誤記錄到 Logging」

  12. 按一下 [儲存]。系統會顯示「已儲存設定」訊息,表示 Chat 應用程式已可供測試。

測試 Chat 應用程式

傳送訊息給專案管理 Chat 應用程式,並使用斜線指令建立、編輯及刪除使用者故事,測試該應用程式。

  1. 使用您在新增自己為信任測試人員時提供的 Google Workspace 帳戶,開啟 Google Chat。

    前往 Google Chat

  2. 按一下 「發起新即時通訊」
  3. 在「新增 1 位以上使用者」欄位中,輸入 Chat 應用程式的名稱。
  4. 從結果中選取 Chat 應用程式。系統會開啟即時訊息。

  5. 在與應用程式互傳的新即時訊息中輸入 Hello,然後按下 enter。專案管理 Chat 應用程式會回覆說明選單,詳細列出可執行的動作。
  6. 如要建立故事,請在訊息列中輸入 /createUserStory Test story 並傳送。專案管理聊天應用程式會回覆一張資訊卡訊息,詳細說明使用 Vertex AI 生成式 AI 為您建立的使用者故事。
  7. 在控制台中,檢查 Firestore 資料庫,查看系統為您新增 Chat 應用程式的聊天室建立的記錄、與該聊天室互動的使用者,以及您建立的使用者故事。

    前往 Firestore

  8. 返回 Google Chat。

    前往 Google Chat

  9. 如要編輯故事,請按一下「編輯」。確認故事內容正確無誤後,按一下「儲存」
  10. 測試應用程式支援的每個斜線指令。如要查看這些指令,請輸入 / 或提及 Google Chat 應用程式。
  11. 發出 /cleanupUserStories斜線指令,刪除測試使用者故事。或者,移除或解除安裝應用程式。移除後,應用程式會刪除該空間中建立的所有使用者故事。

疑難排解

如果 Google Chat 應用程式或資訊卡傳回錯誤,Chat 介面會顯示「發生錯誤」訊息。或「無法處理您的要求」。有時 Chat UI 不會顯示任何錯誤訊息,但 Chat 應用程式或資訊卡會產生非預期結果,例如資訊卡訊息可能不會顯示。

即使 Chat 使用者介面未顯示錯誤訊息,只要開啟 Chat 應用程式的錯誤記錄功能,系統就會提供說明性錯誤訊息和記錄資料,協助您修正錯誤。如需查看、偵錯及修正錯誤的相關協助,請參閱「排解及修正 Google Chat 錯誤」。

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取本教學課程中所用資源的相關費用,建議您刪除 Cloud 專案。

  1. 在 Google Cloud 控制台中,前往「管理資源」頁面。依序點選「選單」「IAM 與管理」「管理資源」

    前往 Resource Manager

  2. 在專案清單中選取要刪除的專案,然後按一下「Delete」(刪除) 圖示
  3. 在對話方塊中輸入專案 ID,然後按一下「Shut down」(關閉) 即可刪除專案。