Łączenie aplikacji z emulatorem Cloud Firestore

Przed połączeniem aplikacji z emulatorem Cloud Firestore upewnij się, że znasz ogólny przepływ pracy Pakietu emulatorów lokalnych Firebase, a także zainstalujesz i skonfigurujesz pakiet emulatorów lokalnych oraz sprawdź jego polecenia interfejsu wiersza poleceń.

Wybierz projekt Firebase

Pakiet emulatorów lokalnych Firebase emuluje usługi dla pojedynczego projektu 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 demonstracyjnych.

W miarę możliwości zalecamy używanie projektów demonstracyjnych. Korzyści:

• Łatwiejsza konfiguracja – emulatory można uruchamiać bez konieczności tworzenia projektu Firebase
• Większe bezpieczeństwo: jeśli Twój kod przypadkowo wywoła nieemulowane zasoby (produkcyjne), nie będzie możliwości zmiany danych, wykorzystania ani płatności
• Lepsza obsługa offline, ponieważ nie trzeba mieć dostępu do internetu, aby pobrać konfigurację pakietu SDK.

Dostosuj aplikację, aby rozmawiać z emulatorami

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 pośrednio w odpowiedzi na dowolne wywołania emulatora pakietu SDK lub interfejsu API REST, które odwołują się do konkretnej bazy danych. Takie niejawnie utworzone bazy danych działają za pomocą otwartych reguł.

Aby interaktywnie korzystać z domyślnych i nazwanych baz danych w interfejsie pakietu emulatorów, zaktualizuj adres URL na pasku adresu przeglądarki, wybierając 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 ją do wersji localhost:4000/firestore/ecommerce/data.

Android, platformy Apple i pakiety SDK dla aplikacji internetowych

Skonfiguruj konfigurację w aplikacji lub klasy testowe do interakcji z Cloud Firestore w następujący sposób. Pamiętaj, że w przykładach poniżej 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 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ć Cloud Functions uruchamiane przez zdarzenia Firestore za pomocą emulatora, nie musisz niczego konfigurować. Gdy emulatory Firestore i Cloud Functions są uruchomione, automatycznie współpracują ze sobą.

Pakiety Admin SDK

Pakiety 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 emulatorze Cloud Functions, identyfikator projektu i inne ustawienia są automatycznie ustawiane podczas wywoływania funkcji initializeApp.

Jeśli chcesz, by kod pakietu Admin SDK łączył się ze współdzielonym emulatorem działającym w innym środowisku, musisz podać ten sam identyfikator projektu, który został ustawiony w interfejsie wiersza poleceń Firebase. Identyfikator projektu możesz przekazać bezpośrednio do funkcji 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

Wersja produkcyjna Firestore nie udostępnia metody opróżniania bazy danych przez pakiet SDK, ale emulator Firestore udostępnia na potrzeby tego celu punkt końcowy REST, który można wywołać podczas konfigurowania platformy testowej lub etapu usuwania, z klasy testowej lub z powłoki (np. za pomocą curl) przed rozpoczęciem testu. Możesz użyć tego rozwiązania jako alternatywy dla prostego wyłączenia procesu emulatora.

W odpowiedniej metodzie wykonaj operację usuwania HTTP, podając identyfikator projektu Firebase, np. firestore-emulator-example, do tego 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, czy czyszczenie 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 zaimplementowaniu takiego kroku możesz sekwencjonować testy i aktywować funkcje z pewnością, że stare dane zostaną trwale usunięte między uruchomieniami, a przy tym używasz nowej podstawowej konfiguracji testu.

Importowanie i eksportowanie danych

Emulatory bazy danych i Cloud Storage dla Firebase umożliwiają eksportowanie danych z uruchomionej instancji emulatora. Zdefiniuj podstawowy zestaw danych do wykorzystania w testach jednostkowych lub przepływach pracy w trybie ciągłej integracji, a następnie wyeksportuj go, aby udostępnić w całym zespole.

firebase emulators:export ./dir

W testach podczas uruchamiania emulatora zaimportuj dane podstawowe.

firebase emulators:start --import=./dir

Możesz poinstruować emulator, aby po wyłączeniu wyeksportował dane, podając ścieżkę eksportu lub po prostu ścieżkę przekazywaną 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 znajdziesz w dokumentacji poleceń emulatora.

Wizualizacja aktywności reguł zabezpieczeń

Podczas pracy nad prototypami i pętlami testowymi możesz korzystać z narzędzi do wizualizacji i raportów z Pakietu emulatorów lokalnych.

Korzystanie z Monitora żądań

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

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

Wizualizacja raportów oceny reguł

Po dodaniu reguł zabezpieczeń do prototypu możesz je debugować za pomocą narzędzi do debugowania w pakiecie emulatorów lokalnych.

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

Aby pobrać raporty, wyślij zapytanie do ujawnionego punktu końcowego w emulatorze, gdy jest on uruchomiony. Aby uzyskać wersję dostosowaną do przeglądarki, 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, które możesz najechać kursorem na dodatkowe informacje, m.in. o liczbie ocen i zwróconych wartościach. W przypadku nieprzetworzonych danych w wersji JSON umieść w zapytaniu ten adres URL:

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

W wersji HTML raportu są tu wyróżnione oceny, które powodują wystąpienie błędów o niezdefiniowanej wartości i błędach o wartości null:

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

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

Obsługa wielu baz danych Cloud Firestore

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

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

Transakcje

Emulator nie implementuje obecnie wszystkich działań transakcji występujących w środowisku produkcyjnym. Gdy testujesz funkcje obejmujące wiele równoczesnych zapisów w jednym dokumencie, emulator może wolno wykonywać żądania zapisu. W niektórych przypadkach odblokowanie blokady może potrwać do 30 sekund. W razie potrzeby możesz odpowiednio dostosować czasy oczekiwania na testy.

Indeksy

Emulator nie śledzi indeksów złożonych i zamiast tego wykonuje wszystkie prawidłowe zapytania. Pamiętaj, aby przetestować swoją aplikację z prawdziwą instancją Cloud Firestore, aby określić, których indeksów potrzebujesz.

Limity

Emulator nie wymusza wszystkich limitów egzekwowanych w środowisku produkcyjnym. Emulator może na przykład zezwalać na transakcje, które zostałyby odrzucone przez usługę produkcyjną jako za duże. Zapoznaj się z udokumentowanymi limitami i zaprojektuj aplikację tak, by aktywnie ich unikać.

Co dalej?

• Wyselekcjonowany zestaw filmów i szczegółowe przykłady instrukcji znajdziesz na playliście szkoleniowej na temat emulatorów Firebase.
• Zbadaj zaawansowane przypadki użycia obejmujące testowanie reguł zabezpieczeń i pakiet SDK Test Firebase: Testuj reguły zabezpieczeń (Firestore).
• Ponieważ aktywowane funkcje to typowa integracja z Cloud Firestore, więcej o emulatorze Cloud Functions dla Firebase dowiesz się z artykułu Lokalne uruchamianie funkcji.