Łączenie aplikacji z emulatorem Cloud Firestore

Zanim połączysz aplikację z emulatorem Cloud Firestore, upewnij się, że rozumiesz ogólny przepływ pracy Firebase Local Emulator Suite, oraz że zainstalujesz i skonfigurujesz Local Emulator Suite i zapoznasz się z jego poleceniami CLI.

Wybieranie projektu w Firebase

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

Aby wybrać projekt, którego chcesz używać, przed uruchomieniem emulatorów wpisz w CLI polecenie firebase use w katalogu roboczym. Możesz też przekazać flagę --project do każdego polecenia emulatora.

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

Jeśli to możliwe, zalecamy używanie projektów demonstracyjnych. W ten sposób możesz zapewnić im dostęp do tych korzyści:

• Łatwiejsza konfiguracja, ponieważ możesz uruchamiać emulatory bez tworzenia projektu w Firebase.
• Większe bezpieczeństwo, ponieważ jeśli Twój kod przypadkowo wywoła nieemulowane (produkcyjne) zasoby, nie będzie możliwości zmiany danych, użycia ani rozliczenia.
• Lepsza obsługa offline, ponieważ nie musisz uzyskiwać dostępu do internetu, aby pobrać konfigurację pakietu SDK.

Instrumentowanie aplikacji do 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 niejawnie utworzone bazy danych działają z otwartymi regułami.

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

• Aby na przykład przeglądać dane w domyślnej instancji, zaktualizuj adres URL do localhost:4000/firestore/default/data.
• Aby przeglądać dane w instancji o nazwie ecommerce, zaktualizuj adres URL 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 określisz edition w obu konfiguracjach, 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 do internetu

Skonfiguruj klasy testowe lub konfigurację w aplikacji, aby wchodzić w interakcje z Cloud Firestore w ten sposób. Pamiętaj, że w tych przykładowych aplikacjach kod łączy się z domyślną bazą danych projektu. Przykłady dotyczące dodatkowych Cloud Firestore baz danych 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 wywoływane przez zdarzenia Firestore za pomocą emulatora, nie musisz niczego dodatkowo konfigurować. Gdy działają zarówno emulator Firestore, jak i emulator Cloud Functions, automatycznie współpracują ze sobą.

Admin SDKs

Pakiety Firebase Admin SDK automatycznie łączą się z Cloud Firestore emulatorem, 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 konfigurowane podczas wywoływania initializeApp.

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

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

export GCLOUD_PROJECT="your-project-id"

Interfejs Cloud Firestore REST API

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

Pełna ścieżka wywołania REST ma postać:

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

Aby na przykład wyświetlić listę wszystkich dokumentów w kolekcji users projektu 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 wersja Firestore nie udostępnia metody pakietu SDK do czyszczenia bazy danych, ale emulator Firestore udostępnia punkt końcowy REST specjalnie do tego celu, który można wywołać z poziomu konfiguracji lub wyłączania platformy testowej, klasy testowej lub powłoki (np. za pomocą curl) przed rozpoczęciem testu. Możesz użyć tego podejścia jako alternatywy dla zwykłego zamykania procesu emulatora.

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

Oczywiście Twój kod powinien czekać na potwierdzenie REST, że czyszczenie się zakończyło lub nie powiodło.

Tę operację możesz wykonać w powłoce:

// 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 wywoływać funkcje z pewnością, ż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 uruchomionej instancji emulatora. Zdefiniuj podstawowy zestaw danych, których chcesz używać w testach jednostkowych lub przepływach pracy 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 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 importowania i eksportowania danych działają też z poleceniem firebase emulators:exec. Więcej informacji znajdziesz w dokumentacji poleceń emulatora.

Wizualizowanie aktywności reguł zabezpieczeń

Podczas pracy nad prototypem i testowania 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 wizualizowanie żądań klientów w Emulator Suite UI, w tym śledzenie oceny Firebase Security Rules.

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

Wizualizowanie raportów oceny reguł

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

Po uruchomieniu zestawu testów możesz uzyskać dostęp do raportów pokrycia testami, które pokazują, jak oceniana była każda z reguł zabezpieczeń.

Aby uzyskać raporty, podczas działania emulatora wyślij zapytanie do udostępnionego punktu końcowego. Aby uzyskać wersję przyjazną dla przeglądarki, użyj tego adresu URL:

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

Dzieli on reguły na wyrażenia i podwyrażenia, nad którymi możesz najechać kursorem, aby uzyskać więcej informacji, w tym liczbę ocen i zwrócone wartości. Aby uzyskać wersję tych danych w formacie JSON, w zapytaniu uwzględnij ten adres URL:

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

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

Różnice między emulatorem Cloud Firestore a wersją produkcyjną

Emulator Cloud Firestore próbuje wiernie odtworzyć zachowanie 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 w przypadku 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 REST API.

Transakcje

Emulator nie implementuje obecnie wszystkich zachowań transakcji obserwowanych w środowisku produkcyjnym. Podczas testowania funkcji, które obejmują wiele równoczesnych zapisów w jednym dokumencie, emulator może wolno wykonywać żądania zapisu. W niektórych przypadkach zwolnienie blokad 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 i zamiast tego wykonuje każde prawidłowe zapytanie. Aby określić, których indeksów będziesz potrzebować, przetestuj aplikację w prawdziwej Cloud Firestore instancji.

Limity

Emulator nie wymusza wszystkich limitów obowiązujących 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 unikać.

Co dalej?

• Aby zapoznać się z wyselekcjonowanym zestawem filmów i szczegółowymi instrukcjami z przykładami, obejrzyj playlistę szkoleń na temat emulatorów Firebase.
• Poznaj zaawansowane przypadki użycia związane z testowaniem reguł zabezpieczeń i pakietem Firebase Test SDK: Testowanie reguł zabezpieczeń (Firestore).
• Ponieważ funkcje wywoływane są typową integracją z Cloud Firestore, dowiedz się więcej o emulatorze Cloud Functions for Firebase w artykule Uruchamianie funkcji lokalnie.