使用 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 撰寫故事說明,然後在聊天室中分享故事。
  • 小查完成故事細節。
    圖 4.小莉按一下「編輯」完成故事詳細資料。AI 的說明內容正確,但小查需要更詳細的資訊,因此 Charlie 必須點選「展開」,在故事說明中加入 Vertex AI 條件。小莉將故事指派給自己、設定狀態、選取適當的優先順序和大小,然後按一下「儲存」
  • 管理團隊所有的使用者故事。
    圖 5.無論何時,Charlie 隨時可以透過 /manageUserStories 斜線指令查看及管理所有團隊的使用者故事。

必要條件

目標

  • 建構可管理靈活軟體專案的即時通訊應用程式。
  • 運用採用 Vertex AI 的生成式 AI 輔助故事書寫工具,協助使用者撰寫使用者故事:
    • 產生及重新產生故事說明。
    • 在附註中展開故事說明,完成所有規定。
    • 請修正文法以修正錯字。
  • 寫入及讀取 Firestore 資料庫,藉此掌握最新工作資訊。
  • 讓使用者直接透過對話建立、編輯、指派及開始撰寫故事,進而在 Chat 聊天室中促進協作。

使用的產品

專案管理應用程式使用下列 Google Workspace 和 Google Cloud 產品:

  • Chat API:用於開發 Google Chat 應用程式的 API,可接收及回應 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 函式的 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 與管理」>「建立專案」

    前往「Create a Project」(建立專案)

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

    選用:如要編輯專案 ID,請按一下「Edit」。專案建立後即無法變更專案 ID,因此請在專案生命週期內選擇符合您需求的 ID。

  3. 在「位置」欄位中,按一下「瀏覽」,查看專案的潛在位置。然後按一下「選取」
  4. 點選「建立」。Google Cloud 控制台會前往「資訊主頁」頁面,並在幾分鐘內建立專案。

gcloud CLI

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

  • Cloud Shell:如要在已設定 gcloud CLI 中使用線上終端機,請啟用 Cloud Shell。
    啟用 Cloud Shell
  • 本機殼層:如要使用本機開發環境,請安裝initialize 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 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 函式的預設服務帳戶,但您不需要設定。在實際工作環境的環境中,您通常會改為建立服務帳戶並連結至 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.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 中 userStoriesassignee,以及 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.jsonpackage-lock.json
Node.js 專案設定和依附元件。
index.js
Chat 應用程式 Cloud 函式的進入點。它會從 HTTP 要求讀取 Chat 事件、呼叫應用程式處理常式,並以 JSON 物件形式發布 HTTP 回應。
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
這個目錄中的每個檔案都會將卡片物件例項化,接著 Chat 應用程式會以資訊卡訊息對話方塊動作回應的形式傳回 Chat。
views/widgets/*.js
每個檔案都會將一種小工具物件例項化,該物件用於在 views/ 目錄中建立資訊卡。
test/**/*.test.js
這個目錄及其子目錄中的每個檔案都包含對應函式、控制器、服務、檢視畫面或小工具的單元測試。您可以在專案的根目錄中執行 npm run test,藉此執行所有單元測試。

建立及部署 Cloud 函式

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

Cloud 函式為了回應來自 Chat 的 HTTP 要求,其中包含 Chat 互動事件。執行時,Cloud 函式程式碼會處理事件並傳回 Chat 回應,Chat 會以訊息、對話方塊或其他類型的使用者互動方式轉譯。在適用情況下,Cloud 函式也會從 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. 按一下 「建立函式」

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

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

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

  9. 在「原始碼」中,選取「壓縮上傳」

  10. 目的地值區中,建立或選取值區:

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

    Google Cloud 會將 ZIP 檔案上傳到這個值區中,並擷取元件檔案。接著,Cloud Functions 會將元件檔案複製到 Cloud 函式中。

  11. 在「ZIP 檔案」中,上傳您從 GitHub 下載、擷取和重新壓縮的 ZIP 檔案:

    1. 點選「瀏覽」
    2. 找出並選取所需 ZIP 檔案。
    3. 按一下「開啟」
  12. 按一下「部署」

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

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

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

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

    1. 在「Function details」(函式詳細資料) 頁面中,按一下「Trigger」(觸發條件)
    2. 複製網址。在下一節中,您將需要用到 Chat 應用程式設定 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 API,包括 Chat 應用程式的名稱、支援的斜線指令,以及 Chat 應用程式 Cloud 函式的觸發網址,應用程式會傳送 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. 在「功能」下方,依序選取「接收 1:1 訊息」和「加入聊天室和群組對話」

  7. 在「連線設定」下方,選取「應用程式網址」

  8. 在「App URL」(應用程式網址) 中,貼上從 Cloud 函式部署中複製的觸發事件網址,格式為 https://REGION-PROJECT_ID.cloudfunctions.net/project-management-tutorial。如果您是透過 gcloud CLI 部署 Cloud 函式,這就是 url 屬性。

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

    1. 在「斜線指令」下方,點選「新增斜線指令」
    2. 針對下表詳述的各個斜線指令,輸入「Name」、「Command ID」、「Description」,然後選擇是否要使用斜線指令「開啟對話方塊」,然後點選「完成」

      名稱 指令 ID 說明 開啟對話方塊
      /createUserStory 1 以指定標題建立故事。 已取消選取
      /myUserStories 2 列出指派給使用者的所有精選故事。 已取消選取
      /userStory 3 顯示指定故事的目前狀態。 已取消選取
      /manageUserStories 4 開啟可供編輯故事的對話方塊。 已選取
      /cleanupUserStories 5 刪除聊天室中的所有報導。 已取消選取
  10. 在「Visibility」(顯示設定) 下方,選取「Make this Chat app as the specific people and groups」,然後輸入您的電子郵件地址。

  11. 或者,在「記錄檔」下方,選取「將錯誤記錄到 Logging」

  12. 按一下「儲存」。畫面上會顯示設定儲存的訊息,代表 Chat 應用程式已準備就緒,可以進行測試。

測試 Chat 應用程式

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

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

    前往 Google Chat

  2. 按一下「發起即時通訊」圖示
  3. 在「Add 1 or more people」欄位中,輸入 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 UI 可能不會顯示錯誤訊息,但我們提供描述性的錯誤訊息和記錄資料,協助您修正啟用 Chat 應用程式錯誤記錄功能時發生的錯誤。如要瞭解如何查看、偵錯及修正錯誤,請參閱「疑難排解及修正 Google Chat 錯誤」。

清除所用資源

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

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

    前往 Resource Manager

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