將應用程式連線至 Cloud Firestore 模擬器

將應用程式連線至 Cloud Firestore 模擬器之前,請務必瞭解整體 Firebase 本機模擬器套件工作流程,且您已安裝並設定本機模擬器套件,並查看其 CLI 指令

選擇 Firebase 專案

Firebase 本機模擬器套件可模擬單一 Firebase 專案的產品。

如要選取要使用的專案,請在啟動模擬器前,先在 CLI 中於工作目錄中執行 firebase use。或者,您也可以將 --project 標記傳遞給每個模擬器指令。

本機模擬器套件支援模擬「實際」的 Firebase 專案和示範專案。

專案類型 功能 與模擬器搭配使用
真的

實際的 Firebase 專案是指您建立及設定的專案,很有可能是透過 Firebase 控制台使用。

實際專案會包含即時資源,例如資料庫執行個體、儲存空間值區、函式,或是您為該 Firebase 專案設定的任何其他資源。

使用實際的 Firebase 專案時,您可以為任何或所有支援的產品執行模擬器。

針對尚未模擬的任何產品,您的應用程式和程式碼會與「即時」資源互動,例如資料庫執行個體、儲存空間值區和函式等。

操作示範

示範 Firebase 專案沒有實際的 Firebase 設定和即時資源。這些專案通常透過程式碼研究室或其他教學課程存取。

示範專案的專案 ID 含有 demo- 前置字串。

使用示範 Firebase 專案時,您的應用程式和程式碼「只」與模擬器互動。如果應用程式嘗試與未執行模擬器的資源互動,該程式碼就會失敗。

建議您盡可能使用示範專案。福利包括:

  • 設定更輕鬆,因為您不必建立 Firebase 專案就能執行模擬器
  • 更安全可靠,因為如果程式碼意外叫用非模擬 (實際工作環境) 資源,資料、用量和計費方式就不會產生變化。
  • 更優異的離線支援功能,因為不需存取網際網路即可下載 SDK 設定。

檢測應用程式,以便與模擬器交談

啟動時,Cloud Firestore 模擬器會為 firebase.json 檔案中的每個 firestore 設定建立預設資料庫和具名資料庫。

此外,系統也會自動建立已命名資料庫,以回應模擬器參照特定資料庫的任何 SDK 或 REST API 呼叫。這類隱含建立的資料庫採用「開放規則」運作。

如要在 Emulator 套件 UI 中以互動方式使用預設和已命名的資料庫,請在瀏覽器網址列中更新網址,選取預設或已命名的資料庫。

  • 舉例來說,如要瀏覽預設執行個體中的資料,請將網址更新為 localhost:4000/firestore/default/data
  • 如要瀏覽名為 ecommerce 的執行個體,請更新至 localhost:4000/firestore/ecommerce/data

Android、Apple 平台和 Web SDK

按照以下方式調整應用程式內設定或測試類別,與 Cloud Firestore 互動。請注意,在下列範例中,應用程式程式碼會連線至預設專案資料庫。如需預設資料庫以外的其他 Cloud Firestore 資料庫的相關範例,請參閱多個資料庫的指南

Kotlin+KTX
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val firestore = Firebase.firestore
firestore.useEmulator("10.0.2.2", 8080)

firestore.firestoreSettings = firestoreSettings {
    isPersistenceEnabled = false
}
Java
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFirestore firestore = FirebaseFirestore.getInstance();
firestore.useEmulator("10.0.2.2", 8080);

FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setPersistenceEnabled(false)
        .build();
firestore.setFirestoreSettings(settings);
Swift
let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings

網路模組 API

import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";

// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, '127.0.0.1', 8080);

網路命名空間 API

// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
  db.useEmulator("127.0.0.1", 8080);
}

不需要額外設定,即可使用模擬器測試透過 Firestore 事件觸發的 Cloud Functions。Firestore 和 Cloud Functions 模擬器同時執行時,兩者會自動搭配運作。

Admin SDK

設定 FIRESTORE_EMULATOR_HOST 環境變數時,Firebase Admin SDK 會自動連線至 Cloud Firestore 模擬器:

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

如果您的程式碼是在 Cloud Functions 模擬器中執行,系統會在呼叫 initializeApp 時自動設定專案 ID 和其他設定。

如要讓 Admin SDK 程式碼連結至在其他環境中執行的共用模擬器,您必須指定使用 Firebase CLI 設定的同一個專案 ID。您可以將專案 ID 直接傳遞至 initializeApp,或設定 GCLOUD_PROJECT 環境變數。

Node.js Admin SDK
admin.initializeApp({ projectId: "your-project-id" });
環境變數
export GCLOUD_PROJECT="your-project-id"

在測試之間清除資料庫

實際工作環境 Firestore 不提供清除資料庫的平台 SDK 方法,但 Firestore 模擬器提供專為此目的而提供的 REST 端點,您可以在測試開始之前透過測試架構設定/拆解步驟、測試類別或殼層 (例如:curl) 呼叫。這個方法只能做為關閉模擬器程序的替代方法。

在適當的方法中執行 HTTP DELETE 作業,將您的 Firebase 專案 ID (例如 firestore-emulator-example) 提供給以下端點:

"http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

一般而言,您的程式碼會等待 REST 確認清除已完成或失敗。

您可以在殼層中執行這項作業:

// Shell alternative…
$ curl -v -X DELETE "http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

實作這類步驟後,您可以安排測試的順序,並放心觸發函式,因為系統會在執行期間清除舊資料,並使用新的基準測試設定。

匯入及匯出資料

資料庫和 Cloud Storage for Firebase 模擬器可讓您從執行中的模擬器執行個體匯出資料。定義要在單元測試或持續整合工作流程中使用的基準資料集,然後匯出並匯出至團隊中。

firebase emulators:export ./dir

在測試中,於模擬器啟動時匯入基準資料。

firebase emulators:start --import=./dir

您可以指示模擬器在關機時匯出資料,只要指定匯出路徑,或直接使用傳遞至 --import 標記的路徑即可。

firebase emulators:start --import=./dir --export-on-exit

這些資料匯入和匯出選項也能搭配 firebase emulators:exec 指令使用。詳情請參閱模擬器指令參考資料

以圖表呈現安全性規則活動

處理原型和測試迴圈時,您可以使用本機模擬器套件提供的視覺化工具和報表。

使用要求監控器

Cloud Firestore 模擬器可讓您在模擬器套件 UI 中以視覺化方式呈現用戶端要求,包括 Firebase 安全性規則的評估追蹤。

開啟「Firestore > 要求」分頁,查看每項要求的詳細評估順序。

Firestore 模擬器要求監控畫面,顯示安全性規則評估作業

視覺化呈現規則評估報表

在原型中加入安全性規則時,您可以使用本機模擬器套件偵錯工具對規則進行偵錯。

執行一組測試後,您就可以存取測試涵蓋範圍報表,瞭解各項安全性規則的評估方式。

如要取得報告,請在模擬器執行期間查詢已公開的端點。如需瀏覽器可用的版本,請使用下列網址:

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage.html

這樣會將規則拆成運算式與子運算式,您可以重複使用以獲得更多資訊,包括傳回的評估和值。針對這項資料的原始 JSON 版本,請在查詢中加入下列網址:

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage

以下為 HTML 版本的報表,會醒目顯示出現未定義和空值錯誤的評估:

Cloud Firestore 模擬器與實際工作環境的差異

Cloud Firestore 模擬器會嘗試以可靠的方式複製實際工作環境服務的行為,但有一些重要的限制。

Cloud Firestore 支援多資料庫

模擬器套件 UI 目前支援預設資料庫的互動式建立、編輯、刪除、要求監控和安全性視覺化功能,但不支援其他已命名資料庫。

不過,模擬器本身會根據 firebase.json 檔案中的設定建立已命名的資料庫,並以隱含方式回應 SDK 或 REST API 呼叫。

交易

模擬器目前不會實作實際工作環境中的所有交易行為。測試需要同時寫入一份文件的功能時,模擬器完成寫入要求的速度可能較慢。在某些情況下,鎖定最多可能需要 30 秒才能釋放。請考慮視需要調整測試逾時。

索引

模擬器不會追蹤複合索引,會改為執行任何有效查詢。請務必針對真實的 Cloud Firestore 執行個體測試應用程式,以判斷需要的索引。

限制

模擬器不會強制執行正式版中強制執行的所有限制。例如,模擬器可能會允許因實際執行服務導致遭拒交易過大的交易。請務必熟悉記錄的限制,並且在設計應用程式時主動避免這些限制。

接下來要我為你做什麼呢?