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

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

  • 提及專案管理應用程式時,該應用程式會提供協助。
    圖 1. Charlie 在 Chat 聊天室中與團隊討論功能開發事宜。提及專案管理 Chat 應用程式,Chat 應用程式就會提供協助。
  • 使用 /createUserStory 斜線指令建立故事。
    圖 2. /createUserStory
  • 專案管理聊天應用程式會使用 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 Function 的 HTTP 端點傳送同步 HTTP 要求。

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

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

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

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

準備環境

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

建立 Google Cloud 專案

Google API Console

  1. 在 Google API 控制台中,依序前往「Menu」(選單) >「IAM & Admin」(IAM 與管理) >「Create a Project」(建立專案)。

    前往「建立專案」

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

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

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

gcloud CLI

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

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

啟用 Cloud 專案的帳單功能

Google API Console

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

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

  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 是要啟用計費功能的雲端專案的專案 ID。
    • BILLING_ACCOUNT_ID 是要連結至 Google Cloud 雲端專案的帳單帳戶 ID。

啟用 API

Google API 控制台

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

    啟用 API

  2. 確認您要在正確的雲端專案中啟用 API,然後按一下 下一步。

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

gcloud CLI

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

    gcloud config set project PROJECT_ID

    將 PROJECT_ID 替換為您建立的雲端專案的專案 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 Function,以代管及執行 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)
指派完成故事的使用者資源名稱。對應 Document ID users 文件,以及 Chat API 中的使用者資源名稱。
descriptionString
從使用者角度描述軟體功能。
priorityEnum
完成工作的緊急程度。可能的值為 Low、Medium 或 High。
sizeEnum
工作量。可能的值為 Small、Medium 或 Large。
statusEnum
工作階段。可能的值為 OPEN、STARTED 或 COMPLETED。
titleString
故事標題;簡短摘要。

users

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

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

請按照下列步驟建立 Firestore 資料庫:

Google API 控制台

  1. 在 Google API 控制台中,前往 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.json和package-lock.json
Node.js 專案設定和依附元件。
index.js
Chat 應用程式 Cloud 函式的進入點。它會從 HTTP 要求讀取 Chat 事件、呼叫應用程式處理常式,並將 HTTP 回應發布為 JSON 物件。
controllers/app.js
主要應用程式邏輯。處理互動事件,包括處理 Google 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/ 目錄中建構資訊卡的小工具物件類型。
test/**/*.test.js
這個目錄及其子目錄中的每個檔案,都包含對應函式、控制器、服務、檢視區塊或小工具的單元測試。如要執行所有單元測試,請在專案的根目錄中執行 npm run test。

建立及部署 Cloud 函式

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

Cloud 函式會因應 Chat 傳送的 HTTP 要求執行,其中包含 Chat 互動事件。執行時,Cloud Functions 程式碼會處理事件,並將回應傳回 Chat,而 Chat 會將回應顯示為訊息、對話方塊或其他類型的使用者互動。如果適用,Cloud Function 也會從 Firestore 資料庫讀取或寫入資料。

建立 Cloud 函式的方法如下:

Google API 控制台

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

    下載 ZIP 檔案

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

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

  3. 在解壓縮的資料夾中,前往 add-ons-samples-main/node/chat/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 API 控制台的 Cloud Functions 頁面:

    前往 Cloud Functions 頁面

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

  5. 按一下 「Create Function」(建立函式)。

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

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

  8. 在「Entry point」(進入點) 中,刪除預設文字並輸入 projectManagementChatApp。

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

  10. 在「目的地 bucket」中,建立或選取 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. 在「Source code」(原始碼) 中選取「Inline editor」(直接修改)。
    4. 在內嵌編輯器中開啟 env.js 檔案。
    5. 使用您的 Cloud 專案 ID 取代 project-id。
    6. 選用:將 us-central1 更新為 Cloud Functions 的支援位置。
  14. 按一下 [Deploy] (部署)。

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

    1. 在「Function details」(函式詳細資料) 頁面中,按一下「Trigger」(觸發條件)。
    2. 複製網址。您需要這項資訊,才能在下一節中設定 Chat 應用程式。

gcloud CLI

  1. 從 GitHub 複製程式碼:

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

    cd add-ons-samples/node/chat/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 API 控制台中設定 Google Chat 應用程式

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

  1. 在 Google API 控制台中,依序點選「選單」「API 和服務」「已啟用的 API 和服務」「Google Chat API」「設定」。

    前往 Chat API 設定

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

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

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

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

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

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

  8. 複製「服務帳戶電子郵件地址」。授權 Google Chat 應用程式叫用函式時,您需要這個電子郵件地址。

  9. 在「觸發條件」下方,選取「為所有觸發條件使用通用的 HTTP 端點網址」。

  10. 在「HTTP endpoint URL」(HTTP 端點網址) 中,貼上 Cloud 函式的觸發網址,格式為 https://REGION-PROJECT_ID.cloudfunctions.net/project-management-tutorial。如果您使用 gcloud CLI 部署 Cloud 函式,這就是 url 屬性。

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

    1. 在「指令」下方,按一下「新增指令」。
    2. 針對下表詳列的每個指令,輸入「指令 ID」,輸入「說明」,在「指令類型」下方選取「斜線指令」,輸入「斜線指令名稱」,選取「對話方塊」,然後按一下「完成」:

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

  13. 選用:在「記錄」下方,選取「將錯誤記錄到 Logging」。

  14. 按一下 [儲存]。畫面會顯示「已儲存設定」訊息。

Chat 應用程式已準備好接收及回覆 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. 在 API 控制台中檢查 Firestore 資料庫,查看系統為您新增 Chat 應用程式的聊天室、與應用程式互動的使用者,以及您建立的使用者故事所建立的記錄。

    前往 Firestore

  8. 返回 Google Chat。

    前往 Google Chat

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

疑難排解

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

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

清除所用資源

為避免系統向您的 Google Cloud 帳戶收取本教學課程所用資源的費用,建議您刪除雲端專案。

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

    前往 Resource Manager

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