Łączenie aplikacji z emulatorem Cloud Firestore

Zanim połączysz aplikację z emulatorem Cloud Firestore, upewnij się, że znasz ogólny przepływ pracy Pakietu emulatorów lokalnych Firebase oraz że zainstalujesz i skonfigurujesz Pakiet emulatorów lokalnych, a także przejrzyj jego polecenia interfejsu wiersza poleceń.

Wybierz projekt Firebase

Pakiet emulatorów lokalnych Firebase emuluje usługi związane z jednym projektem Firebase.

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

Pakiet emulatorów lokalnych obsługuje emulację prawdziwych projektów Firebase i projektów prezentacyjnych.

Zalecamy, aby w miarę możliwości korzystać z projektów demonstracyjnych. W ten sposób możesz zapewnić im dostęp do tych korzyści:

• Łatwiejsza konfiguracja, ponieważ emulatory można uruchamiać bez konieczności tworzenia projektu Firebase.
• Silniejsze bezpieczeństwo, ponieważ jeśli Twój kod przypadkowo wywoła zasoby nieemulowane (produkcyjne), nie ma szans na zmianę danych, ich wykorzystanie i płatności
• Lepsza obsługa offline, ponieważ nie musisz łączyć się z internetem, aby pobrać konfigurację pakietu SDK.

Dostosuj aplikację do emulatorów

Po uruchomieniu 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 domyślnie w odpowiedzi na wszystkie wywołania pakietu SDK lub interfejsu API REST kierowane do emulatora, które odwołują się do konkretnej bazy danych. Takie niejawnie tworzone bazy danych działają z regułami otwartymi.

Aby w interfejsie Pakietu emulatorów interaktywnie pracować z domyślnymi i nazwanymi bazami danych, na pasku adresu przeglądarki zaktualizuj URL, wybierając domyślną lub nazwane 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, zmień ją na localhost:4000/firestore/ecommerce/data.

Platformy Android, Apple i internetowe pakiety SDK

Aby skonfigurować konfigurację w aplikacji lub klasy testowe pod kątem interakcji z Cloud Firestore, wykonaj poniższe czynności. Zwróć uwagę, że w poniższych przykładach kod aplikacji łączy się z domyślną bazą danych projektu. Przykłady innych baz danych Cloud Firestore poza domyślną bazą danych znajdziesz w przewodniku dotyczącym wielu baz danych.

// 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
}
EmulatorSuite.kt

// 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);
EmulatorSuite.java

let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

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

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

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

Aby przetestować funkcje w Cloud Functions aktywowane przez zdarzenia Firestore za pomocą emulatora, nie jest wymagana dodatkowa konfiguracja. Gdy emulatory Firestore i Cloud Functions są uruchomione, automatycznie współpracują ze sobą.

Pakiety Admin SDK

Pakiety Firebase Admin SDK 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 ramach emulatora Cloud Functions, identyfikator projektu i inne konfiguracje są automatycznie ustawiane przy wywołaniu funkcji initializeApp.

Jeśli chcesz, by Twój kod pakietu Admin SDK łączył się ze współdzielonym emulatorem działającym w innym środowisku, musisz podać ten sam identyfikator projektu, który ustawiasz w interfejsie wiersza poleceń Firebase. Możesz przekazać identyfikator projektu bezpośrednio do usługi initializeApp lub ustawić zmienną środowiskową GCLOUD_PROJECT.

admin.initializeApp({ projectId: "your-project-id" });

export GCLOUD_PROJECT="your-project-id"

Czyszczenie bazy danych między testami

Usługa Firestore nie udostępnia metody pakietu SDK platformy produkcyjnej do opróżnienia bazy danych, ale emulator Firestore zapewnia w tym celu punkt końcowy REST, który można wywołać z poziomu konfiguracji platformy testowej/tearDown, z klasy testowej lub z powłoki (np. curl). Tym sposobem możesz użyć tej metody, aby po prostu wyłączyć proces emulatora.

W odpowiedniej metodzie wykonaj operację usunięcia HTTP, 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"

Twój kod powinien oczywiście czekać na potwierdzenie REST o zakończeniu lub niepowodzeniu opróżniania.

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 zaimplementowaniu takiego kroku możesz utworzyć sekwencję testów i aktywować funkcje, mając pewność, że stare dane zostaną trwale usunięte między uruchomieniami i będziesz korzystać z nowej, podstawowej konfiguracji testu.

Importowanie i eksportowanie danych

Baza danych i emulatory Cloud Storage dla Firebase umożliwiają eksportowanie danych z działającej instancji emulatora. Zdefiniuj bazowy zbiór danych do wykorzystania w testach jednostkowych lub przepływach pracy w trybie ciągłej integracji, a następnie wyeksportuj je, aby udostępnić je członkom zespołu.

firebase emulators:export ./dir

Podczas uruchamiania emulatora zaimportuj dane podstawowe podczas testów.

firebase emulators:start --import=./dir

Możesz polecić emulatorowi eksportowanie danych po wyłączeniu, podając ścieżkę eksportu lub po prostu używając ścieżki przekazywanej do flagi --import.

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

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

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

Opracując prototyp i pętle testowe, możesz korzystać z narzędzi do wizualizacji i raportów dostępnych w Pakiecie emulatorów lokalnych.

Używanie Monitora żądań

Emulator Cloud Firestore umożliwia wizualizację żądań klientów w interfejsie pakietu emulatorów, w tym śledzenie ocen przez reguły zabezpieczeń Firebase.

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

Wizualizacja raportów oceny reguł

Dodając reguły zabezpieczeń do prototypu, możesz je debugować za pomocą narzędzi do debugowania Pakietu emulatorów lokalnych.

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

Aby uzyskać te raporty, wyślij w emulatorze zapytanie do ujawnionego punktu końcowego, gdy jest on uruchomiony. W przypadku wersji przeznaczonej do wyświetlania w przeglądarce użyj tego adresu URL:

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

Spowoduje to podział reguł na wyrażenia i wyrażenia podrzędne, po których możesz najechać na nie kursorem, aby uzyskać więcej informacji, w tym liczbę ocen i zwróconych wartości. W przypadku nieprzetworzonej wersji JSON tych danych uwzględnij w zapytaniu ten adres URL:

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

W tym przykładzie w wersji HTML raportu wyróżnione są oceny, które generują niezdefiniowane błędy i błędy o wartości null:

Czym różni się emulator Cloud Firestore od wersji produkcyjnej

Emulator Cloud Firestore próbuje wiernie odtworzyć działanie usługi produkcyjnej z pewnymi ograniczeniami.

Obsługa wielu baz danych w Cloud Firestore

Obecnie interfejs użytkownika Pakietu emulatorów obsługuje interaktywne tworzenie, edytowanie, usuwanie, monitorowanie żądań i wizualizację zabezpieczeń domyślnej bazy danych, ale nie dodatkowych nazwanych baz danych.

Sam emulator tworzy jednak nazwaną bazę danych na podstawie konfiguracji w pliku firebase.json i domyślnie w odpowiedzi na wywołania pakietu SDK lub interfejsu API REST.

Transakcje

Emulator nie implementuje obecnie wszystkich zachowań związanych z transakcjami, które można zaobserwować w środowisku produkcyjnym. Gdy testujesz funkcje, które wymagają wielu równoczesnych zapisów w jednym dokumencie, emulator może działać wolno z pełnym żądaniem zapisu. W niektórych przypadkach odblokowanie może potrwać do 30 sekund. W razie potrzeby rozważ odpowiednie dostosowanie czasu oczekiwania testu.

Indeksy

Emulator nie śledzi indeksów złożonych i zamiast tego wykonuje wszystkie prawidłowe zapytania. Przetestuj aplikację w rzeczywistej instancji Cloud Firestore, aby dowiedzieć się, których indeksów potrzebujesz.

Limity

Emulator nie egzekwuje wszystkich limitów wymuszanych w środowisku produkcyjnym. Emulator może na przykład zezwolić na transakcje, które zostałyby odrzucone przez usługę produkcyjną jako zbyt duże. Upewnij się, że znasz udokumentowane limity i projektujesz swoją aplikację w taki sposób, aby aktywnie ich unikać.

Co dalej?

• Wyselekcjonowany zestaw filmów i szczegółowe przykłady instrukcji znajdziesz na playliście szkoleniowej dotyczącej emulatorów Firebase.
• Przeanalizuj zaawansowane przypadki użycia obejmujące testowanie reguł zabezpieczeń i pakiet SDK Firebase Test: Testowanie reguł zabezpieczeń (Firestore).
• Ponieważ aktywowane funkcje to typowa integracja z Cloud Firestore, więcej informacji o emulatorze Cloud Functions dla Firebase znajdziesz w artykule Uruchamianie funkcji lokalnie.