使用適用於 CI/CD 的 Data Connect 模擬器

Firebase Data Connect 提供本機模擬器，可用於端對端原型設計，以及持續整合和持續部署 (CI/CD) 流程：

  • Data Connect 模擬器會與本機整合的 PGLite 資料庫執行個體互動，讓您在完全本機環境中建立查詢和變異型原型，並測試用戶端程式碼。
  • Data Connect 模擬器也可用於非互動式工作。可讓您執行自動化測試，並適合搭配 CI/CD 工作流程使用。當結構定義穩定且您想製作原型並測試用戶端程式碼時，這項功能就非常實用。

本指南將詳細介紹模擬器的安裝和使用方式，而非快速入門導覽課程。

安裝 Data Connect 模擬器

在安裝 Local Emulator Suite 以使用 Data Connect 模擬器前，您需要：

  • Node.js 18.0 以上版本。

安裝 Firebase CLI 並設定專案目錄

  1. 請按照安裝指南安裝 Firebase CLI。請務必定期更新，因為 Data Connect 模擬器仍處於開發階段，並修正了錯誤並推出新功能。

  2. 如果您尚未將目前的工作目錄初始化為 Firebase 專案，請按照提示指定要使用的產品：

    firebase init

設定或修改 Local Emulator Suite 設定

如果您是透過 Firebase VS Code 擴充功能啟動 Data Connect 模擬器，系統會視需要為您安裝模擬器。

您可以使用 Firebase CLI 手動安裝模擬器，以及 Local Emulator Suite 的其他所選元件。這個指令會啟動設定精靈，讓您選取所需的模擬器、下載對應的模擬器二進位檔案，以及在預設值不合適時設定模擬器連接埠。

  firebase init emulators

安裝模擬器後，系統不會執行更新檢查，也不會自動下載其他內容，除非您更新 Firebase CLI 版本。

選擇 Firebase 專案

在設定流程中，Firebase CLI 會提示您選擇或建立 Firebase 專案。如果您選擇在 Firebase 控制台中使用 Data Connect 設定的現有專案，則系統會建議您選擇的設定。

設定模擬器

設定模擬器

執行 firebase init 流程時，系統會引導您設定模擬器。與 Local Emulator Suite 中的其他模擬器一樣，設定參數會儲存在本機專案檔案中。

  • firebase.json 檔案含有模擬器通訊埠指派項目。
    • emulators:ui 鍵不適用於 Data Connect 模擬器。

使用本機和實際工作環境的 Data Connect 資源

如要確保不會影響實際資源，請設定 demo- projectID，或是確保您的用戶端程式碼已檢測並連線至模擬器，如後續章節所述。

啟動模擬器

如果您要以非交互方式執行模擬器 (例如 CI/CD 工作流程)，請使用 exec 選項啟動模擬器。

firebase emulators:exec ./path/to/test-script.sh

如果您要在用戶端程式碼中整合預先定義的查詢和變異，並且要使用模擬器專門測試用戶端，則可以使用 start 選項進行互動作業。您也可以透過 VS Code 擴充功能啟動模擬器。

firebase emulators:start

檢測用戶端程式碼，與模擬器通訊

如要設定應用程式內設定或測試類別，以便與 Data Connect 模擬器互動，請按照下列步驟操作：

JavaScript
import { initializeApp } from "firebase/app";
import { connectorConfig } from "@name-of-package";
import { connectDataConnectEmulator, getDataConnect } from 'firebase/data-connect';

// TODO: Replace the following with your app's Firebase project configuration
const firebaseConfig = {
  //...
};

const app = initializeApp(firebaseConfig);

const dataConnect = getDataConnect(app, connectorConfig);
connectDataConnectEmulator(dataConnect, "localhost", 9399);

// Make calls from your app
Kotlin Android
val connector = MoviesConnector.instance

// Connect to the emulator on "10.0.2.2:9399"
connector.dataConnect.useEmulator()

// (Alternatively) if you're running your emulator on non-default port:
connector.dataConnect.useEmulator(port = 9999)

// Make calls from your app
iOS
let connector = DataConnect.dataConnect(DefaultConnectorClient.connectorConfig)

// Connect to the emulator on "127.0.0.1:9399"
connector.useEmulator()

// (alternatively) if you're running your emulator on non-default port:
connector.useEmulator(port: 9999)

// Make calls from your app

使用模擬器進行測試和持續整合

執行容器化 Local Emulator Suite 映像檔

在一般 CI 設定中，使用容器安裝及設定 Local Emulator Suite 相當簡單。

請注意以下幾點：

  • 模擬器二進位檔會在 ~/.cache/firebase/emulators/ 安裝及快取。建議您將這個路徑新增至 CI 快取設定，以免重複下載。
  • 如果儲存庫中沒有 firebase.json 檔案，您必須在 emulators:start 或 emulators:exec 指令中新增指令列引數，指定要啟動的模擬器。例如：--only dataconnect。

清除測試之間的資料庫

如要在兩次執行作業之間重設測試環境，Firebase 建議：

  • 編寫專屬變異來處理下列項目：
    • 在設定期間，請使用起始資料填入本機資料庫例項。
    • 在拆解作業中，刪除測試後資料庫執行個體中的修改資料。

Data Connect 模擬器與實際環境的差異

Data Connect 模擬器可模擬伺服器端產品的許多功能。不過，請注意以下例外狀況：

  • PGLite 的版本和詳細設定可能與您正式版 Cloud SQL 執行個體的版本不同。
  • 如果您使用模擬器開發 Data Connect 的 pgvector 和 Vertex API 整合，系統會直接呼叫 Cloud Vertex API，而非透過 Cloud SQL 的 Vertex 整合。不過，系統仍會呼叫正式版 API，也就是說您必須使用實際的 Firebase 專案 (無法使用 demo- 專案)，並且會產生 Vertex API 費用。