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

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

  • 提及專案管理應用程式時，應用程式會提供協助。
    圖 1. Charlie 與團隊成員在 Chat 聊天室中討論功能開發事宜。提及專案管理 Chat 應用程式，Chat 應用程式就會提供協助。
  • 使用 /createUserStory 斜線指令建立故事。
    圖 2. 然後使用 /createUserStory 斜線指令建立故事。
  • Chat 專案管理應用程式使用 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 即時通訊應用程式會使用 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 Function 的 HTTP 端點。

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

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

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

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

準備環境

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

建立 Google Cloud 專案

Google Cloud 控制台

  1. 在 Google Cloud 控制台中，依序點選「選單」圖示 >「IAM 與管理」>>「建立專案」。

    前往「建立專案」

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

    選用步驟：如要編輯「Project ID」，請按一下「Edit」。專案建立後即無法變更 ID，因此請依據專案的生命週期需求，選擇合適的 ID。

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

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 控制台

  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，然後按一下「下一步」。

  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 附加的預設服務帳戶，您不需要自行設定。在實際工作環境中，您通常會將服務帳戶create並連結至 Cloud 函式。

建立及部署 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. 在「為資料庫命名」中，將「資料庫 ID」保留為 (default)。

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

  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 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
這個目錄中的每個檔案都會將 資訊卡物件例項化，然後 Chat 應用程式會將其傳回 Chat，做為 資訊卡訊息或對話方塊動作回應。
views/widgets/*.js
每個檔案都會將某種類型的 Widget 物件例項化，應用程式會使用這些物件在 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 函式

  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. 在「功能」下方，選取「接收一對一訊息」和「加入聊天室和群組對話」。

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

  8. 在「HTTP 端點網址」中，貼上從 Cloud 函式部署作業複製的觸發條件網址，格式為 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. 在「Visibility」(顯示設定) 下方，選取「Make this Chat app available for your Workspace domain」(將這個 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 控制台中，前往「管理資源」頁面。依序按一下「選單」圖示 >「IAM 與管理」 >「管理資源」。

    前往 Resource Manager

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