Instalowanie, konfigurowanie i integrowanie Pakietu emulatorów lokalnych

Pakiet emulatorów lokalnych Firebase można zainstalować i skonfigurować w różnych środowiskach testowych i prototypowych, 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 nie masz jeszcze zainstalowanego wiersza poleceń Firebase, 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.

Konfigurowanie pakietu 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 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 domyślnych portach, a emulatory Cloud Firestore, Realtime Database i Cloud Storage for Firebase będą działać z otwartą ochroną danych.

Konfiguracja portu

Każdy emulator łączy się z innym portem na komputerze przy użyciu preferowanej wartości domyślnej.

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), użyj 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. Podanie parametru Firebase wiersza poleceń --project zastąpi 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 Java

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ępują błędy związane z pamięcią sterty w Java, możesz zwiększyć maksymalny rozmiar sterty 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 ciągłej integracji.

Eksportowanie i importowanie danych emulatora

Dane z emulacji Authentication, Cloud Firestore, Realtime Database i Cloud Storage for Firebase możesz eksportować i wykorzystywać jako wspólny podstawowy zbiór danych, który można udostępniać. Te zbiory danych można importować za pomocą parametru --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.

Należy pamiętać o kilku kwestiach:

• Pliki JAR są instalowane i przechowywane w pamięci podręcznej w folderze ~/.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ą zostać uruchomione. 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. Postępuj zgodnie z instrukcjami, aby uwierzytelnić konto. Wystarczy, że wykonasz ten krok tylko raz na projekt, ponieważ token będzie ważny w przypadku wszystkich kompilacji. Token należy traktować jak hasło. Należy zachować go w tajemnicy.

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 podejścia z użyciem zaimplementowanych w kodzie wartości możesz dodać --token "YOUR_TOKEN_STRING_HERE" do polecenia firebase emulators:exec.

Korzystanie z interfejsu API REST w Emulatorze

Wyświetlanie listy uruchomionych emulatorów

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

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 są wykonywane 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

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

{
  "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 SDK klienta i Admin SDK. W przyszłości oznacza, że obsługa emulatora jest planowana, ale jeszcze niedostępna.

Dostępność klienta SDK

Dostępność pakietu Admin SDK