Połącz swoją aplikację z emulatorem Cloud Firestore

Przed podłączeniem aplikacji do emulatora Cloud Firestore upewnij się, że rozumiesz ogólny przepływ pracy w pakiecie Firebase Local Emulator Suite oraz że instalujesz i konfigurujesz pakiet Local Emulator Suite oraz przeglądasz jego polecenia CLI .

Wybierz projekt Firebase

Pakiet Firebase Local Emulator Suite emuluje produkty dla pojedynczego projektu Firebase.

Aby wybrać projekt do użycia, przed uruchomieniem emulatorów, w CLI uruchom firebase use w swoim katalogu roboczym. Możesz też przekazać flagę --project do każdego polecenia emulatora.

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

Typ projektu Cechy Używaj z emulatorami
Prawdziwy

Prawdziwy projekt Firebase to taki, który utworzyłeś i skonfigurowałeś (najprawdopodobniej za pomocą konsoli Firebase).

Prawdziwe projekty mają aktywne zasoby, takie jak instancje baz danych, zasobniki pamięci, funkcje lub inne zasoby skonfigurowane dla tego projektu Firebase.

Pracując z prawdziwymi projektami Firebase, możesz uruchomić emulatory dla dowolnego lub wszystkich obsługiwanych produktów.

W przypadku wszystkich produktów, których nie emulujesz, Twoje aplikacje i kod będą wchodzić w interakcję z aktywnym zasobem (instancją bazy danych, zasobnikiem pamięci, funkcją itp.).

Próbny

Projekt demonstracyjny Firebase nie ma prawdziwej konfiguracji Firebase ani aktywnych zasobów. Dostęp do tych projektów można zwykle uzyskać za pośrednictwem ćwiczeń z programowania lub innych samouczków.

Identyfikatory projektów demonstracyjnych mają przedrostek demo- .

Podczas pracy z projektami demonstracyjnymi Firebase Twoje aplikacje i kod wchodzą w interakcję wyłącznie z emulatorami. Jeśli aplikacja podejmie próbę interakcji z zasobem, dla którego nie działa emulator, wykonanie kodu zakończy się niepowodzeniem.

W miarę możliwości zalecamy korzystanie z projektów demonstracyjnych. Korzyści obejmują:

  • Łatwiejsza konfiguracja, ponieważ możesz uruchomić emulatory bez tworzenia projektu Firebase
  • Większe bezpieczeństwo, ponieważ jeśli Twój kod przypadkowo wywoła nieemulowane zasoby (produkcyjne), nie ma szans na zmianę danych, wykorzystanie i rozliczenie
  • Lepsza obsługa w trybie offline, ponieważ nie ma potrzeby dostępu do Internetu, aby pobrać konfigurację SDK.

Instrumentuj swoją aplikację, aby komunikowała się 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 . Użyj pliku firebase.json , aby jawnie przypisać reguły zabezpieczeń Cloud Firestore do nazwanej bazy danych.

Nazwane bazy danych są również tworzone niejawnie w odpowiedzi na wszelkie wywołania interfejsu API SDK lub REST do emulatora, które odwołują się do określonej bazy danych. Takie niejawnie utworzone bazy danych działają na otwartych zasadach .

Obecnie interfejs Emulator Suite obsługuje interaktywną pracę z domyślną bazą danych .

Platformy Android, Apple i internetowe pakiety SDK

Skonfiguruj konfigurację w aplikacji lub zajęcia testowe, aby współdziałać z Cloud Firestore w następujący sposób. Należy zauważyć, że w poniższych przykładach kod aplikacji łączy się z domyślną bazą danych projektu. Przykłady obejmujące dodatkowe bazy danych Cloud Firestore poza domyślną bazą danych można znaleźć w przewodniku dotyczącym wielu baz danych .

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);
Szybki
let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings

Web modular API

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

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

Web namespaced API

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

Aby przetestować funkcje Cloud Functions uruchamiane przez zdarzenia Firestore za pomocą emulatora, nie jest wymagana żadna dodatkowa konfiguracja. Gdy działają emulatory Firestore i Cloud Functions, automatycznie współpracują.

Pakiety SDK administratora

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

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

Jeśli Twój kod działa w emulatorze Cloud Functions, identyfikator projektu i inna konfiguracja są ustawiane automatycznie podczas wywoływania initializeApp .

Jeśli chcesz, aby Twój kod Admin SDK łączył się ze współdzielonym emulatorem działającym w innym środowisku, musisz podać ten sam identyfikator projektu, który ustawiłeś za pomocą interfejsu CLI Firebase . Możesz przekazać identyfikator projektu do bezpośredniego initializeApp lub ustawić zmienną środowiskową GCLOUD_PROJECT .

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

Wyczyść bazę danych pomiędzy testami

Produkcja Firestore nie zapewnia metody SDK platformy do opróżniania bazy danych, ale emulator Firestore udostępnia punkt końcowy REST specjalnie do tego celu, który można wywołać z poziomu konfiguracji/kroku usuwania struktury testowej, z klasy testowej lub z powłoki (np. , z curl ) przed rozpoczęciem testu. Możesz zastosować to podejście jako alternatywę dla zwykłego zamykania procesu emulatora.

W odpowiedniej metodzie wykonaj operację HTTP DELETE, podając identyfikator projektu Firebase, na przykład firestore-emulator-example , do następującego punktu końcowego:

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

Naturalnie, Twój kod powinien czekać 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 uruchamiać funkcje, mając pewność, że stare dane zostaną usunięte między kolejnymi uruchomieniami i będziesz korzystać ze świeżej podstawowej konfiguracji testu.

Importuj i eksportuj dane

Baza danych i emulatory Cloud Storage for Firebase umożliwiają eksport danych z działającej instancji emulatora. Zdefiniuj bazowy zestaw danych do wykorzystania w testach jednostkowych lub przepływach pracy ciągłej integracji, a następnie wyeksportuj go w celu udostępnienia zespołowi.

firebase emulators:export ./dir

W testach przy uruchomieniu emulatora importuj dane bazowe.

firebase emulators:start --import=./dir

Możesz poinstruować emulator, aby eksportował dane po zamknięciu, określają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 importu i eksportu danych działają również z poleceniem firebase emulators:exec . Więcej informacji można znaleźć w dokumentacji poleceń emulatora .

Wizualizuj działanie reguł bezpieczeństwa

Podczas pracy nad pętlami prototypowymi i testowymi możesz korzystać z narzędzi do wizualizacji i raportów udostępnianych przez pakiet Local Emulator Suite.

Użyj Monitora żądań

Emulator Cloud Firestore umożliwia wizualizację żądań klientów w interfejsie użytkownika pakietu Emulator Suite, w tym śledzenie oceny reguł bezpieczeństwa Firebase.

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

Monitor żądań emulatora Firestore pokazujący oceny reguł bezpieczeństwa

Wizualizuj raporty z ocen reguł

Po dodaniu reguł zabezpieczeń do prototypu możesz je debugować za pomocą narzędzi debugowania pakietu Local Emulator Suite.

Po przeprowadzeniu zestawu testów możesz uzyskać dostęp do raportów zasięgu testów, które pokazują, jak została oceniona każda z Twoich reguł bezpieczeństwa.

Aby uzyskać raporty, wykonaj zapytanie do odsłoniętego punktu końcowego w emulatorze, gdy jest on uruchomiony. Aby uzyskać wersję przyjazną dla przeglądarki, użyj następującego adresu URL:

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

Spowoduje to rozbicie reguł na wyrażenia i podwyrażenia, na które można najechać myszką, aby uzyskać więcej informacji, w tym liczbę ocen i zwróconych wartości. Aby uzyskać surową wersję tych danych w formacie JSON, w zapytaniu umieść następujący adres URL:

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

W tym przypadku wersja HTML raportu wyróżnia oceny, które zgłaszają błędy niezdefiniowane i o wartości zerowej:

Czym emulator Cloud Firestore różni się od produkcyjnego

Emulator Cloud Firestore próbuje wiernie odtworzyć zachowanie usługi produkcyjnej z pewnymi znaczącymi ograniczeniami.

Obsługa wielu baz danych dla Cloud Firestore

Obecnie interfejs użytkownika pakietu Emulator Suite obsługuje interaktywne tworzenie, edytowanie, usuwanie, monitorowanie żądań i wizualizację zabezpieczeń dla domyślnej bazy danych, ale nie dla 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 SDK lub API REST.

Transakcje

Emulator nie implementuje obecnie wszystkich zachowań transakcyjnych spotykanych w środowisku produkcyjnym. Podczas testowania funkcji obejmujących wiele równoczesnych zapisów w jednym dokumencie emulator może wolno realizować żądania zapisu. W niektórych przypadkach zwolnienie blokad może zająć do 30 sekund. W razie potrzeby rozważ odpowiednie dostosowanie limitów czasu testu.

Indeksy

Emulator nie śledzi indeksów złożonych i zamiast tego wykona każde prawidłowe zapytanie. Pamiętaj, aby przetestować swoją aplikację na prawdziwej instancji Cloud Firestore, aby określić, które indeksy będą potrzebne.

Granice

Emulator nie egzekwuje wszystkich ograniczeń narzuconych w produkcji. Na przykład emulator może pozwolić na transakcje, które zostałyby odrzucone przez usługę produkcyjną jako zbyt duże. Upewnij się, że znasz udokumentowane limity i że projektujesz aplikację tak, aby aktywnie ich unikać.

Co następne?