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

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

  • 提及專案管理應用程式,即可讓應用程式提供協助。
    圖 1. Charlie 在 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 會將同步 HTTP 要求傳送至 Cloud Functions 的 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 控制台中,依序前往「選單」 >「IAM 與管理」 >「建立專案」

    前往「建立專案」

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

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

  3. 在「位置」欄位中,按一下「瀏覽」,顯示專案的可能位置。然後按一下「選取」
  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. 如有必要,請將目前的 Cloud 專案設為您使用 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 函式。

建立及部署 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)
獲派完成故事的使用者資源名稱。這與 Document IDusers 文件,以及 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 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 函式前,請先花點時間查看並熟悉 GitHub 上託管的程式碼範例。

前往 GitHub 查看

以下簡要說明各個檔案:

env.js
環境設定變數,可將 Chat 應用程式部署至指定的 Google Cloud 雲端專案和區域。您必須更新這個檔案中的設定變數。
package.jsonpackage-lock.json
Node.js 專案設定和依附元件。
index.js
Chat 應用程式 Cloud Function 的進入點。讀取 HTTP 要求中的即時通訊事件、呼叫應用程式處理常式,並將 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/ 目錄中建構資訊卡的 小工具 物件類型。
test/**/*.test.js
這個目錄及其子目錄中的每個檔案,都包含對應函式、控制器、服務、檢視區塊或小工具的單元測試。在專案的根目錄中執行 npm run test,即可執行所有單元測試。

建立及部署 Cloud 函式

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

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

建立 Cloud Function 的方式如下:

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. 按一下 「建立函式」

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

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

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

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

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

    1. 點選「瀏覽」
    2. 選擇值區。
    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. 在「App name」(應用程式名稱) 中輸入 Project Manager

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

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

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

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

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

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

  9. 在「Triggers」(觸發條件) 下方,選取「Use a common HTTP endpoint URL for all triggers」(為所有觸發條件使用通用的 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. 在專案清單中選取要刪除的專案,然後按一下「刪除」圖示
  3. 在對話方塊中輸入專案 ID,然後按一下「Shut down」(關機) 即可刪除專案。