Instalowanie, konfigurowanie i integrowanie Pakietu emulatorów lokalnych

Pakiet emulatorów lokalnych Firebase można zainstalować i skonfigurować w różnych środowiskach testowych i prototypowania, od jednorazowych sesji prototypowania po procesy ciągłej integracji na potrzeby produkcji.

Instalowanie Pakietu emulatorów lokalnych

Przed zainstalowaniem pakietu Emulator Suite musisz mieć:

• Node.js w wersji 16.0 lub nowszej.
• Java JDK w wersji 11 lub nowszej.

Aby zainstalować pakiet Emulator Suite:

1. Zainstaluj interfejs wiersza poleceń Firebase. Jeśli wiersz poleceń Firebase nie jest jeszcze zainstalowany, zainstaluj go teraz. Aby korzystać z Pakietów emulatorów, musisz mieć interfejs wiersza poleceń w wersji 8.14.0 lub nowszej. Aby sprawdzić, która wersja jest zainstalowana, uruchom to polecenie:

   firebase --version

2. Jeśli nie zostało to jeszcze zrobione, zainicjuj bieżący katalog roboczy jako projekt Firebase, postępując zgodnie z instrukcjami wyświetlanymi na ekranie, aby określić, których usług chcesz używać:

   firebase init

3. Skonfiguruj Pakiet emulatorów. To polecenie uruchamia kreatora konfiguracji, który umożliwia wybranie interesujących Cię emulatorów, pobranie odpowiednich plików binarnych emulatora i ustawienie portów emulatora, jeśli domyślne nie są odpowiednie.

   firebase init emulators

Po zainstalowaniu emulatora nie są wykonywane żadne sprawdzania aktualizacji ani żadne dodatkowe automatyczne pobierania, dopóki nie zaktualizujesz wersji Firebase CLI.

Skonfiguruj Pakiet emulatorów

Opcjonalnie możesz skonfigurować porty sieciowe emulatorów i ścieżkę do definicji reguł zabezpieczeń w pliku firebase.json:

• Zmień porty emulatora, uruchamiając polecenie firebase init emulators lub edytując firebase.json ręcznie.
• Zmień ścieżkę do definicji reguł zabezpieczeń, edytując firebase.jsonręcznie.

Jeśli nie skonfigurujesz tych ustawień, emulatory będą nasłuchiwać na swoich portach domyślnych, a emulatory Cloud Firestore, Realtime Database i Cloud Storage for Firebase będą działać z otwartym zabezpieczeniami danych.

Konfiguracja portu

Każdy emulator wiąże się z innym portem w maszynie z preferowaną wartością domyślną.

Konfiguracja identyfikatora projektu

W zależności od sposobu wywoływania emulatorów możesz uruchomić kilka instancji emulatora z różnymi identyfikatorami projektów Firebase lub kilka instancji emulatora dla danego identyfikatora projektu. W takich przypadkach instancje emulatora działają w oddzielnym środowisku.

Zazwyczaj warto ustawić jeden identyfikator projektu dla wszystkich wywołań emulatora, aby Emulator Suite UI, różne emulatory produktów i wszystkie działające instancje danego emulatora mogły prawidłowo komunikować się we wszystkich przypadkach.

Local Emulator Suite wysyła ostrzeżenia, gdy wykryje w środowisku wiele identyfikatorów projektu. Możesz jednak zastąpić to zachowanie, ustawiając w pliku firebase.json klucz singleProjectMode na wartość false.

Niezgodności w deklaracjach identyfikatora projektu możesz sprawdzić w tych miejscach:

• Projekt domyślny w wierszu poleceń. Domyślnie identyfikator projektu będzie po uruchomieniu pobierany z projektu wybranego za pomocą firebase init lub firebase use. Aby wyświetlić listę projektów (i sprawdzić, który z nich jest wybrany), kliknij firebase projects:list.
• Testy jednostkowe reguł. Identyfikator projektu jest często podawany w wywołaniach metod biblioteki Unit Testing w bibliotece initializeTestEnvironment lub initializeTestApp.
• Flaga wiersza poleceń --project. Przekazywanie flagi interfejsu wiersza poleceń Firebase--project zastępuje projekt domyślny. Upewnij się, że wartość flagi jest zgodna z identyfikatorem projektu w testach jednostkowych i inicjalizacji aplikacji.

Sprawdź też konfiguracje identyfikatorów projektów na poszczególnych platformach, które zostały ustawione podczas konfigurowania platform Apple, Androida i projektów internetowych.

Konfiguracja reguł zabezpieczeń

Emulatory będą używać konfiguracji reguł zabezpieczeń z kluczy konfiguracji database, firestore i storage w konfiguracji firebase.json.

{
  // Existing firebase configuration ...
  "database": {
    "rules": "database.rules.json"
  },
  "firestore": {
    "rules": "firestore.rules"
  },
  "storage": {
    "rules": "storage.rules"
  }

  // ...

  // Optional emulator configuration. Default
  // values are used if absent.
  "emulators": {
    "singleProjectMode": false, // do not warn on detection of multiple project IDs
    "firestore": {
      "port": "8080"
    },
    "ui": {
      "enabled": true,      // Default is `true`
      "port": 4000          // If unspecified, see CLI log for selected port
    },
    "auth": {
      "port": "9099"
    },
    "pubsub": {
      "port": "8085"
    }
  }
}

Określanie opcji Javy

Emulator Realtime Database, emulator Cloud Firestore i część emulatora Cloud Storage for Firebase są oparte na Javie, którą można dostosowywać za pomocą flag JVM za pomocą zmiennej środowiskowej JAVA_TOOL_OPTIONS.

Jeśli na przykład wystąpią błędy związane z przestrzenią sterty Java, możesz zwiększyć maksymalny rozmiar stosu Java do 4 GB:

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

Wiele flag można podać w cudzysłowie oddzielone spacjami, np. JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g". Flagi mają wpływ tylko na komponenty emulatorów oparte na Javie i nie mają wpływu na inne części interfejsu wiersza poleceńFirebase, takie jak Emulator Suite UI.

Uruchamianie emulatorów

Możesz uruchomić emulatory tak, aby działały do momentu ich ręcznego wyłączenia, lub tak, aby działały przez czas trwania określonego skryptu testowego, a następnie automatycznie się wyłączyły.

Metoda firebase emulators:exec jest zazwyczaj bardziej odpowiednia do przepływów pracy w ramach ciągłej integracji.

Eksportowanie i importowanie danych emulatora

Dane z emulacji Authentication, Cloud Firestore, Realtime Database i Cloud Storage for Firebase można eksportować i wykorzystywać jako udostępniany wspólny podstawowy zbiór danych. Te zbiory danych możesz importować za pomocą flagi --import, jak opisano powyżej.

Integracja z systemem CI

Uruchamianie obrazów skonteneryzowanych w Pakiecie emulatorów

Instalacja i konfiguracja pakietu Emulator Suite z kontenerami w typowej konfiguracji CI jest prosta.

Pamiętaj o kilku kwestiach:

• Pliki JAR są instalowane i przechowywane w pamięci podręcznej w ~/.cache/firebase/emulators/.

  • Aby uniknąć wielokrotnego pobierania, możesz dodać tę ścieżkę do konfiguracji pamięci podręcznej CI.

• Jeśli w Twoim repozytorium nie ma pliku firebase.json, musisz dodać argument wiersza poleceń do polecenia emulators:start lub emulators:exec, aby określić, które emulatory mają być uruchamiane. Na przykład:
  --only functions,firestore.

Generowanie tokena uwierzytelniania (tylko emulator hostingu)

Jeśli Twoje przepływy ciągłej integracji korzystają z Firebase Hosting, musisz zalogować się za pomocą tokena, aby uruchomić firebase emulators:exec. Pozostałe emulatory nie wymagają logowania.

Aby wygenerować token, uruchom firebase login:ci w środowisku lokalnym. Nie należy tego robić w systemie CI. Wykonaj instrukcje uwierzytelniania. Ten krok musisz wykonać tylko raz w każdym projekcie, ponieważ token będzie ważny we wszystkich kompilacjach. Token powinien być traktowany jak hasło. Nie należy go ujawniać.

Jeśli Twoje środowisko CI umożliwia określenie zmiennych środowiskowych, których można używać w skryptach kompilacji, utwórz zmienną środowiskową o nazwie FIREBASE_TOKEN, a jej wartością niech będzie ciąg znaków tokenu dostępu. Wiersz poleceń Firebase automatycznie wczyta zmienną środowiskową FIREBASE_TOKEN, a emulatory uruchomią się prawidłowo.

W ostatniej chwili możesz po prostu dodać token do skryptu kompilacji, ale pamiętaj, aby nieautoryzowane strony nie miały do niego dostępu. W przypadku tego zaimplementowanego sztywno podejścia możesz dodać --token "YOUR_TOKEN_STRING_HERE" do polecenia firebase emulators:exec.

Korzystanie z interfejsu API REST w Emulatorze

Wyświetlenie listy uruchomionych emulatorów

Aby wyświetlić listę obecnie uruchomionych emulatorów, wyślij żądanie GET do punktu końcowego /emulators w centrum emulatorów.

curl localhost:4400/emulators

Wynikiem będzie obiekt JSON zawierający listę wszystkich uruchomionych emulatorów i ich konfiguracji hosta/portu, np.:

{
  "hub":{
    "name": "hub",
    "host": "localhost",
    "port": 4400
  },
  "functions": {
    "name": "functions",
    "host": "localhost",
    "port": 5001
  }
  "firestore": {
    "name": "firestore",
    "host": "localhost",
    "port": 8080
  }
}

Włączanie i wyłączanie funkcji uruchamiających w tle

W niektórych sytuacjach musisz tymczasowo wyłączyć lokalne funkcje i wyzwalacze rozszerzeń. Możesz na przykład usunąć wszystkie dane w emulatorze Cloud Firestore bez uruchamiania żadnych funkcji onDelete, które działają w emulatorze Cloud Functions lub Extensions.

Aby tymczasowo wyłączyć lokalne funkcje wyzwalające, wyślij żądanie PUT do punktu końcowego /functions/disableBackgroundTriggers w Emulator Hub.

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

W rezultacie powstanie obiekt JSON zawierający szczegółowe informacje na temat bieżącego stanu.

{
  "enabled": false
}

Aby włączyć lokalne aktywatory funkcji po ich wyłączeniu, wyślij PUT żądanie do punktu końcowego /functions/enableBackgroundTriggers w Emulator Hub.

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

Wynikiem będzie obiekt JSON zawierający szczegółowe informacje o bieżącym stanie.

{
  "enabled": true
}

Integracja pakietu SDK emulatora

Tabele w tej sekcji wskazują, które emulatory są obsługiwane przez pakiety klienta i pakiety Admin SDK. W przyszłości oznacza, że obsługa emulatora jest planowana, ale jeszcze niedostępna.

Dostępność pakietu SDK klienta

Dostępność pakietu Admin SDK