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

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

  • 提到專案管理應用程式，可提示應用程式提供協助。
    圖 1.Charlie 與團隊成員討論 Chat 聊天室的功能開發事宜。提及專案管理 Chat 應用程式，提示 Chat 應用程式提供協助。
  • 使用 /createUserStory 斜線指令建立情節。
    圖 2. Charlie 使用 /createUserStory 斜線指令建立故事。
  • Chat 專案管理應用程式使用 Vertex AI 撰寫故事說明。
    圖 3.專案管理 Chat 應用程式會使用 Vertex AI 編寫故事說明，然後在工作區中分享故事。
  • Charlie 將故事細節定案。
    圖 4.小查按一下「編輯」完成故事細節。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 傳送的互動事件，以及設定屬性 (例如名稱和顯示圖片)。
  • 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 應用程式的運作方式如下：

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

  2. Chat 會將同步 HTTP 要求傳送至 Cloud 函式的 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. 點選「Create」(建立)，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
     設定要建立專案的 ID 來取代 PROJECT_ID。

為 Cloud 專案啟用計費功能

Google Cloud 控制台

  1. 前往 Google Cloud 控制台中的「Billing」，依序點選「選單」圖示 >「帳單」>「我的專案」。

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

  2. 在「選取組織」中，選擇與 Google Cloud 專案相關聯的組織。
  3. 在專案資料列中，開啟「動作」選單 ()，按一下「變更帳單」，然後選擇 Cloud Billing 帳戶。
  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，然後點選「Next」(下一步)。

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

gcloud CLI

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

    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 應用程式的程式碼，回應 Chat 以 HTTP 要求接收的事件。
  4. 在 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 IDString
建立故事的特定聊天室專屬 ID，對應於 Chat API 中的聊天室資源名稱。
userStoriesSubcollection of Documents (userStories)
由 Chat 應用程式和使用者建立的故事。對應至 Firebase 中 userStories 的 Document ID。
usersSubcollection of Documents (user)
建立故事或指派故事的使用者。
displayNameString
Chat API 中的聊天室顯示名稱。未設定與使用者的即時訊息。

userStories

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

欄位
Document IDString
由 Chat 應用程式及其使用者建立的特定使用者故事專屬 ID。
assigneeDocument (user)
完成故事作業的使用者資源名稱。對應至 users 文件的 Document ID，以及 Chat API 中的使用者資源名稱。
descriptionString
從使用者觀點說明軟體功能。
priorityEnum
完成工作的緊急程度。可能的值為 Low、Medium 或 High。
sizeEnum
工作量。可能的值為 Small、Medium 或 Large。
statusEnum
工作的階段。可能的值包括 OPEN、STARTED 或 COMPLETED。
titleString
故事標題；簡短摘要。

users

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

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

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

Google Cloud 控制台

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

    前往 Firestore

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

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

  4. 按一下「繼續」。

  5. 設定資料庫：

    1. 在「Name your database」(為資料庫命名) 中，將「Database ID」(資料庫 ID) 保留為 (default)。

    2. 在「Location type」(位置類型) 中，指定資料庫的區域，例如 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 函式之前，先花點時間查看並熟悉 GitHub 上託管的範例程式碼。

前往 GitHub 查看

以下是每個檔案的總覽：

env.js
環境變數，將 Chat 應用程式部署至指定的 Google Cloud 專案和地區。您必須更新這個檔案中的設定變數。
package.json和package-lock.json
Node.js 專案設定和依附元件。
index.js
Chat 應用程式的 Cloud 函式進入點。這個物件會從 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
這個目錄中的每個檔案都會將 資訊卡物件例項化，然後 Chat 應用程式會將其傳回 Chat，做為 資訊卡訊息或對話方塊動作回應。
views/widgets/*.js
每個檔案都會將一種小工具物件例項化，讓應用程式用來建構 views/ 目錄中的資訊卡。
test/**/*.test.js
此目錄及其子目錄中的每個檔案都包含對應函式、控制器、服務、檢視畫面或小工具的單元測試。只要在專案的根目錄中執行 npm run test，即可執行所有單元測試。

建立及部署 Cloud 函式

在本節中，您將建立及部署 Cloud 函式，其中包含專案管理 Chat 應用程式的應用程式邏輯。

Cloud 函式會在 Chat 的 HTTP 要求中執行，該要求包含 Chat 互動事件。執行時，Cloud Functions 程式碼會處理事件，並將回應傳回至 Chat，Chat 會將回應轉譯為訊息、對話方塊或其他類型的使用者互動。在適用情況下，Cloud 函式也會從 Firestore 資料庫讀取或寫入至 Firestore 資料庫。

建立 Cloud 函式的方式如下：

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. 按一下 「Create Function」。

  6. 在「Create function」(建立函式) 頁面中設定函式：

    1. 在「環境」中，選取「Cloud Run 函式」。
    2. 在「Function name」(函式名稱) 中輸入 project-management-tutorial。
    3. 在「區域」中選取所需區域。
    4. 在「Authentication」下方，選取「Allow unauthenticated invocations」。
    5. 點選「下一步」。

  7. 在「Runtime」中，選取「Node.js 20」。

  8. 在「進入點」中，刪除預設文字並輸入 projectManagementChatApp。

  9. 在「Source code」中，選取「Zip upload」。

  10. 在「目的地值區」中，create或選取值區：

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

    Google Cloud 會將 ZIP 檔案上傳至這個值區，並擷取其中的元件檔案。接著，Cloud Functions 會將元件檔案複製到 Cloud Function。

  11. 在 ZIP 檔案中，上傳您從 GitHub 下載、擷取並重新壓縮的 ZIP 檔案：

    1. 點選「瀏覽」。
    2. 瀏覽並選取 ZIP 檔案。
    3. 按一下「開啟」。

  12. 按一下「部署」。

    「Cloud Functions 詳細資料」頁面會隨即開啟，並顯示您的函式和兩個進度指標：一個用於建構，另一個用於服務。當兩個進度指標消失且以勾號取代時，表示函式已部署完成且準備就緒。

  13. 編輯範例程式碼來設定常數：

    1. 在「Cloud Function details」(Cloud 函式詳細資料) 頁面點選「Edit」(編輯)。
    2. 點選「下一步」。
    3. 在「Source code」中，選取「Inline editor」。
    4. 在內嵌編輯器中開啟 env.js 檔案。
    5. 使用您的 Cloud 專案 ID 取代 project-id。
    6. 選用：使用 Cloud 函式的支援位置更新 us-central1。

  14. 按一下「部署」。

  15. 當函式完成部署後，請複製觸發條件網址：

    1. 在「函式詳細資料」頁面中點選「觸發條件」。
    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 替換為託管其基礎架構的 Cloud 函式位置，例如 us-central1。

  1. 函式部署完畢後，請從回應複製 url 屬性。這是您在下一節設定 Google Chat 應用程式時使用的觸發條件網址。

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

本節說明如何在 Google Cloud 控制台中使用 Chat 應用程式的相關資訊，包括 Chat 應用程式名稱、支援的斜線指令，以及其將 Chat 互動事件傳送至 Chat 應用程式的 Cloud 函式觸發網址。

  1. 在 Google Cloud 控制台中，依序點選「選單」圖示 >「更多產品」>「Google Workspace」 >「產品資料庫」 > 「Google Chat API」 >「管理」 >「設定」。

    前往 Chat API 設定

  2. 在「App name」中輸入 Project Manager。

  3. 在「顯示圖片網址」中輸入 https://developers.google.com/chat/images/quickstart-app-avatar.png。

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

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

  6. 在「功能」下方，選取「接收 1:1 訊息」、「加入聊天室和群組對話」。

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

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

  9. 註冊 Chat 應用程式的斜線指令。如要註冊斜線指令：

    1. 在「斜線指令」下方，按一下「新增斜線指令」。

    2. 針對下表中詳述的每個斜線指令，輸入「名稱」、「指令 ID」和「說明」，然後選取斜線指令是否「開啟對話方塊」，然後點選「完成」：

      名稱 指令 ID 說明 開啟對話方塊
      /createUserStory 1 建立標題為指定名稱的故事。 已取消選取
      /myUserStories 2 列出指派給使用者的所有故事。 已取消選取
      /userStory 3 顯示指定故事目前的狀態。 已取消選取
      /manageUserStories 4 可開啟可編輯故事的對話方塊。 已選取
      /cleanupUserStories 5 刪除聊天室中的所有故事。 已取消選取

  10. 在「瀏覽權限」下方，選取「將這個 Chat 擴充應用程式提供給 Workspace 網域中的特定使用者和群組」，然後輸入您的電子郵件地址。

  11. 您可以選擇在「Logs」下方選取「Log errors to 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 並傳送。專案管理 Chat 應用程式會回覆一張資訊卡訊息，詳細說明使用者故事，並說明該應用程式如何使用 Vertex AI 的生成式 AI 為您建立這類故事。

  7. 在控制台中查看 Firestore 資料庫，檢閱系統建立的記錄，瞭解您新增 Chat 應用程式的聊天室、與該聊天室互動的使用者，以及您建立的使用者故事。

    前往 Firestore

  8. 返回 Google Chat。

    前往 Google Chat

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

疑難排解

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

雖然 Chat UI 可能不會顯示錯誤訊息，但只要開啟 Chat 應用程式的錯誤記錄功能，您就能取得描述性錯誤訊息和記錄資料，協助修正錯誤。如需查看、偵錯及修正錯誤的相關說明，請參閱「排解及修正 Google Chat 錯誤」一文。

清除所用資源

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

  1. 在 Google Cloud 控制台中前往「管理資源」頁面。依序點選「Menu」圖示 >「IAM & Admin」(IAM 與管理) >「Manage Resources」(管理資源)。

    前往 Resource Manager

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