Łączenie aplikacji z emulatorem Cloud Firestore

Zanim połączysz aplikację z emulatorem Cloud Firestore, upewnij się, że rozumiesz ogólny przepływ pracy w Firebase Local Emulator Suite oraz że instalujesz i konfigurujesz Local Emulator Suite i sprawdzasz polecenia interfejsu wiersza poleceń.

Wybierz projekt w Firebase

Firebase Local Emulator Suite emuluje produkty w ramach jednego projektu w Firebase.

Aby wybrać projekt, którego chcesz użyć, przed uruchomieniem emulatorów uruchom w interfejsie wiersza poleceń polecenie firebase use w katalogu roboczym. Możesz też przekazać flagę --project do każdego polecenia emulatora.

Local Emulator Suite obsługuje emulację rzeczywistych projektów w Firebase i projektów demonstracyjnych.

Typ projektu Funkcje Używanie z emulatorami
real

Rzeczywisty projekt w Firebase to projekt utworzony i skonfigurowany przez Ciebie (najprawdopodobniej w konsoli Firebase).

Rzeczywiste projekty zawierają aktywne zasoby, takie jak instancje baz danych, zasobniki, funkcje lub inne zasoby skonfigurowane dla danego projektu Firebase.

Podczas pracy z prawdziwymi projektami w Firebase możesz uruchamiać emulatory dowolnych lub wszystkich obsługiwanych usług.

W przypadku usług, których nie emulujesz, aplikacje i kod będą wchodzić w interakcje z zasobami aktywnymi (instancją bazy danych, zasobnikiem na dane, funkcją itp.).

Prezentacja

Projekt demonstracyjny Firebase nie ma rzeczywistej konfiguracji Firebase ani aktywnych zasobów. Dostęp do tych projektów można zwykle uzyskać za pomocą ćwiczeń w programowaniu lub innych samouczków.

Identyfikatory projektów demonstracyjnych mają prefiks demo-.

Podczas pracy z projektami w Firebase w wersji demonstracyjnej aplikacje i kod wchodzą w interakcje wyłącznie z emulatorami. Jeśli aplikacja spróbuje wejść w interakcję z zasobem, dla którego emulator nie jest uruchomiony, kod nie zadziała.

Zalecamy korzystanie z projektów demonstracyjnych, gdy tylko jest to możliwe. W ten sposób możesz zapewnić im dostęp do tych korzyści:

  • łatwiejsza konfiguracja, ponieważ emulatory można uruchamiać bez tworzenia projektu w Firebase;
  • Większe bezpieczeństwo, ponieważ jeśli kod przypadkowo wywoła nieemulowane zasoby (produkcyjne), nie ma możliwości zmiany danych, użycia ani naliczenia opłat.
  • Lepsza obsługa offline, ponieważ nie trzeba mieć dostępu do internetu, aby pobrać konfigurację pakietu SDK.

Instrumentowanie aplikacji pod kątem komunikacji z emulatorami

Podczas uruchamiania emulator Cloud Firestore tworzy domyślną bazę danych i nazwaną bazę danych dla każdej konfiguracji firestore w pliku firebase.json.

Nazwane bazy danych są też tworzone niejawnie w odpowiedzi na wywołania pakietu SDK lub interfejsu REST API do emulatora, które odwołują się do konkretnej bazy danych. Takie bazy danych utworzone niejawnie działają z otwartymi regułami.

Aby pracować interaktywnie z domyślnymi i nazwanymi bazami danych w Emulator Suite UI, na pasku adresu przeglądarki zaktualizuj adres URL, aby wybrać domyślną lub nazwaną bazę danych.

  • Aby na przykład przeglądać dane w instancji domyślnej, zmień adres URL na localhost:4000/firestore/default/data
  • Aby przeglądać w instancji o nazwie ecommerce, zaktualizuj do localhost:4000/firestore/ecommerce/data.

Uruchamianie emulatora w określonej wersji

Emulator uruchomi się w wersji określonej w sekcji firestore.edition pliku firebase.json. Możesz też określić wersję w sekcji emulators.firestore.edition pliku firebase.json. Prawidłowe wartości wersji to standard i enterprise. Jeśli w obu konfiguracjach określisz edition, pierwszeństwo będzie mieć emulators.firestore.edition.

    {
      ...
      "firestore": {
        "rules": "firestore.rules",
        "indexes": "firestore.indexes.json",
        "edition": "enterprise"
      },
      "emulators": {
        "firestore": {
          "port": 8080,
          "edition": "enterprise" // Takes precedence over `firestore.edition`
        }
      },
      ...
    }

Pakiety SDK na Androida, platformy Apple i sieć

Skonfiguruj konfigurację w aplikacji lub klasy testowe, aby umożliwić interakcję z Cloud Firestore w ten sposób. Zwróć uwagę, że w poniższych przykładach kod aplikacji łączy się z domyślną bazą danych projektu. Przykłady dotyczące dodatkowych baz danych Cloud Firestore poza domyślną bazą danych znajdziesz w przewodniku po wielu bazach danych.

Kotlin
// 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
Unity
FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
// Connects to the Firestore Emulator running on port 8080
db.Settings.Host = "127.0.0.1:8080";
db.Settings.SslEnabled = false;

Web

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

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

Web

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

Nie musisz nic więcej konfigurować, aby przetestować funkcje w Cloud Functions wywoływane przez zdarzenia Firestore za pomocą emulatora. Gdy emulatory Firestore i Cloud Functions są uruchomione, automatycznie współpracują ze sobą.

Admin SDK s

Gdy zmienna środowiskowa FIRESTORE_EMULATOR_HOST jest ustawiona, Firebase Admin SDK automatycznie łączą się z emulatorem Cloud Firestore:

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

Jeśli kod jest uruchamiany w emulatorze Cloud Functions, identyfikator projektu i inne ustawienia konfiguracji są automatycznie ustawiane podczas wywoływania initializeApp.

Jeśli chcesz, aby kod Admin SDK łączył się z emulatorem udostępnionym działającym w innym środowisku, musisz podać ten sam identyfikator projektu, który został ustawiony za pomocą interfejsu wiersza poleceń Firebase. Możesz przekazać identyfikator projektu bezpośrednio do initializeApp lub ustawić zmienną środowiskową GCLOUD_PROJECT.

Node.js Admin SDK
admin.initializeApp({ projectId: "your-project-id" });
Zmienna środowiskowa
export GCLOUD_PROJECT="your-project-id"

Cloud Firestore REST API

Emulator Cloud Firestore udostępnia punkt końcowy REST do interakcji z bazą danych. Wszystkie wywołania interfejsu API REST powinny być kierowane do punktu końcowego http://localhost:8080/v1.

Pełna ścieżka wywołania REST ma następujący wzór:

http://localhost:8080/v1/projects/{project_id}/databases/{database_id}/documents/{document_path}

Jeśli na przykład chcesz wyświetlić listę wszystkich dokumentów w kolekcji users w projekcie my-project-id, możesz użyć curl:

curl -X GET "http://localhost:8080/v1/projects/my-project-id/databases/(default)/documents/users"

Czyszczenie bazy danych między testami

Produkcyjna baza danych Firestore nie udostępnia metody pakietu SDK platformy do czyszczenia bazy danych, ale emulator Firestore udostępnia punkt końcowy REST przeznaczony specjalnie do tego celu.Można go wywołać z kroku setup/tearDown platformy testowej, z klasy testowej lub z powłoki (np. za pomocą curl) przed rozpoczęciem testu. Możesz użyć tego podejścia jako alternatywy dla prostego wyłączenia procesu emulatora.

W odpowiedniej metodzie wykonaj operację HTTP DELETE, podając identyfikator projektu Firebase, na przykład firestore-emulator-example, w tym punkcie końcowym:

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

Oczywiście kod powinien oczekiwać na potwierdzenie REST, że opróżnianie zostało zakończone lub nie powiodło się.

Możesz wykonać tę operację z poziomu powłoki:

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

Po wdrożeniu takiego kroku możesz sekwencjonować testy i wywoływać funkcje, mając pewność, że stare dane zostaną usunięte między uruchomieniami i że używasz nowej podstawowej konfiguracji testowej.

Importowanie i eksportowanie danych

Emulatory bazy danych i Cloud Storage for Firebase umożliwiają eksportowanie danych z działającej instancji emulatora. Zdefiniuj podstawowy zestaw danych do użycia w testach jednostkowych lub przepływach pracy trybu ciągłej integracji, a następnie wyeksportuj go, aby udostępnić go zespołowi.

firebase emulators:export ./dir

W testach podczas uruchamiania emulatora zaimportuj dane podstawowe.

firebase emulators:start --import=./dir

Możesz poinstruować emulator, aby eksportował dane podczas wyłączania, podając ścieżkę eksportu lub po prostu używając ścieżki przekazanej do flagi --import.

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

Te opcje importowania i eksportowania danych działają też z poleceniem firebase emulators:exec. Więcej informacji znajdziesz w dokumentacji poleceń emulatora.

Wizualizacja aktywności związanej z regułami zabezpieczeń

Podczas pracy nad prototypem i testowania pętli możesz korzystać z narzędzi do wizualizacji i raportów udostępnianych przez Local Emulator Suite.

Korzystanie z monitora żądań

Emulator Cloud Firestore umożliwia wizualizację żądań klientów w Emulator Suite UI, w tym śledzenie oceny dla Firebase Security Rules.

Otwórz kartę Firestore > Żądania, aby wyświetlić szczegółową sekwencję oceny każdego żądania.

Monitor żądań emulatora Firestore z ocenami reguł zabezpieczeń

Wizualizacja raportów z ocen reguł

Gdy dodasz reguły zabezpieczeń do prototypu, możesz je debugować za pomocą narzędzi do debugowania Local Emulator Suite.

Po uruchomieniu zestawu testów możesz uzyskać dostęp do raportów o pokryciu testami, które pokazują, jak oceniono każdą z reguł zabezpieczeń.

Aby uzyskać raporty, wyślij zapytanie do udostępnionego punktu końcowego w emulatorze, gdy jest on uruchomiony. Aby uzyskać wersję przyjazną dla przeglądarki, użyj tego adresu URL:

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

Spowoduje to podzielenie reguł na wyrażenia i podwyrażenia, na które możesz najechać kursorem, aby uzyskać więcej informacji, w tym liczbę ocen i zwrócone wartości. Aby uzyskać nieprzetworzoną wersję JSON tych danych, dodaj do zapytania ten adres URL:

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

W tym przypadku wersja HTML raportu wyróżnia oceny, które powodują błędy niezdefiniowanych wartości i wartości null:

Różnice między emulatorem Cloud Firestore a środowiskiem produkcyjnym

Emulator Cloud Firestore próbuje wiernie odtworzyć działanie usługi produkcyjnej, ale ma pewne istotne ograniczenia.

Obsługa wielu baz danych w Cloud Firestore

Obecnie Emulator Suite UI obsługuje interaktywne tworzenie, edytowanie, usuwanie, monitorowanie żądań i wizualizację zabezpieczeń w przypadku domyślnej bazy danych, ale nie dodatkowych nazwanych baz danych.

Jednak sam emulator tworzy nazwaną bazę danych na podstawie konfiguracji w pliku firebase.json i pośrednio w odpowiedzi na wywołania pakietu SDK lub interfejsu REST API.

Transakcje

Emulator nie implementuje obecnie wszystkich zachowań transakcji widocznych w środowisku produkcyjnym. Podczas testowania funkcji, które obejmują wiele jednoczesnych operacji zapisu w jednym dokumencie, emulator może powoli realizować żądania zapisu. W niektórych przypadkach zwolnienie blokady może potrwać do 30 sekund. W razie potrzeby rozważ odpowiednie dostosowanie limitów czasu testów.

Indeksy

Emulator nie śledzi indeksów złożonych, ale wykonuje każde prawidłowe zapytanie. Przetestuj aplikację na rzeczywistej instancji Cloud Firestore, aby określić, które indeksy będą potrzebne.

Limity

Emulator nie wymusza wszystkich limitów, które są egzekwowane w środowisku produkcyjnym. Na przykład emulator może zezwalać na transakcje, które zostałyby odrzucone przez usługę produkcyjną jako zbyt duże. Zapoznaj się z udokumentowanymi limitami i zaprojektuj aplikację tak, aby ich nie przekraczała.

Co dalej?