Zarządzanie konfiguracjami projektów za pomocą pliku manifestu rozszerzeń

Manifest rozszerzeń to lista instancji rozszerzeń i ich konfiguracji. Dzięki plikowi manifestu możesz:

  • Udostępnianie konfiguracji rozszerzeń innym osobom
  • kopiować konfigurację rozszerzeń między różnymi projektami (np. z projektu testowego do projektu produkcyjnego);
  • Wdrażanie wszystkich rozszerzeń jednocześnie
  • Sprawdź, jak rozszerzenia działają w aplikacji, za pomocą Firebase Local Emulator Suite
  • Zatwierdzanie konfiguracji rozszerzeń w systemie kontroli wersji
  • Uwzględnianie rozszerzeń w potoku CI/CD

Plik manifestu rozszerzenia składa się z 2 części:

  • Sekcja extensions w firebase.json, czyli mapa identyfikatorów instancji do odniesienia do wersji rozszerzenia. Przykład:

    {
 "extensions": {
   "my-bigquery-extension": "firebase/firestore-bigquery-export@^0.1.18",
   "my-image-resizer": "firebase/storage-resize-images@^0.1.22",
 }
}

  • .env pliki zawierające konfigurację każdej instancji rozszerzenia w extensions/ podkatalogu katalogu projektu Firebase. Na przykład instancja storage-resize-images może mieć plik .env podobny do tego:

    IMAGE_TYPE=jpeg
LOCATION=us-central1
IMG_BUCKET=${param:PROJECT_ID}.firebasestorage.app
IMG_SIZES=100x100
DELETE_ORIGINAL_FILE=false

Tworzenie pliku manifestu rozszerzeń

Manifest rozszerzenia można utworzyć na 3 sposoby:

  • Zarządzanie plikiem manifestu rozszerzeń za pomocą wiersza poleceń Firebase
  • Eksportowanie konfiguracji rozszerzeń projektu
  • Ręczna edycja plików manifestu

Pierwsze 2 metody opisujemy poniżej.

Zarządzanie plikiem manifestu rozszerzeń za pomocą wiersza poleceń Firebase

Większość poleceń interfejsu Firebase CLI ext: możesz uruchamiać z opcją --local, aby zaktualizować plik manifestu rozszerzeń bez wprowadzania zmian w bieżącej konfiguracji projektu.

Przykład:

firebase ext:install --local firebase/firestore-bigquery-export

Uruchomienie powyższego polecenia spowoduje wyświetlenie prośby o skonfigurowanie najnowszej wersji rozszerzenia firebase/firestore-bigquery-export i zapisanie konfiguracji w pliku manifestu, ale nie spowoduje wdrożenia konfiguracji w projekcie.

Oto więcej przykładów poleceń, które modyfikują plik manifestu rozszerzenia:

# ext:configure changes the params for an extension instance in your extensions manifest
$ firebase ext:configure my-bigquery-extension --local

# ext:update --local updates an instance in your extensions manifest
# to the latest version of that extension
$ firebase ext:update my-bigquery-extension --local

# You can also specify a version if you don't want to update to the latest version
$ firebase ext:update my-bigquery-extension firebase/firestore-bigquery-export@0.1.10 --local 

# ext:uninstall --local removes an instance from your extensions manifest
$ firebase ext:uninstall my-bigquery-extension --local

Eksportowanie konfiguracji rozszerzeń projektu

Aby zapisać bieżącą konfigurację rozszerzeń projektu w pliku manifestu:

  1. Jeśli nie masz jeszcze skonfigurowanego wiersza poleceń Firebase, skonfiguruj go.
  2. W wierszu poleceń przejdź do katalogu projektu. (Katalog projektu zawiera plik firebase.json).
  3. Uruchom polecenie ext:export: 
    firebase ext:export

Polecenie ext:export doda do pliku firebase.json sekcję extensions. Dodatkowo polecenie ext:export tworzy katalog extensions zawierający plik .env dla każdej zainstalowanej instancji rozszerzenia. Te pliki zawierają parametry konfiguracji każdej instancji.

Testowanie konfiguracji rozszerzeń za pomocą narzędzia Firebase Local Emulator Suite

Po dodaniu do manifestu rozszerzeń kilku instancji rozszerzeń możesz je przetestować za pomocą Local Emulator Suite.

  1. Zainstaluj i skonfiguruj Local Emulator Suite.

  2. Rozpocznij Local Emulator Suite:

    • Aby uruchomić Pakiet emulatorów w trybie interaktywnym, wpisz:firebase emulators:start
    • Aby uruchomić Pakiet emulatorów i wykonać skrypt testowy, wpisz:firebase emulators:exec my-test.sh

Jeśli w pliku manifestu masz wymienione instancje rozszerzeń, narzędzie Local Emulator Suite pobierze kod źródłowy tych rozszerzeń do ~/.cache/firebase/extensions. Po pobraniu Local Emulator Suite zostanie uruchomiony i będziesz mieć możliwość wywoływania dowolnych funkcji wyzwalanych w tle w rozszerzeniach oraz łączenia aplikacji z pakietem Emulator, aby przetestować ich integrację z aplikacją.

Wdrażanie konfiguracji rozszerzeń w projekcie

Po dodaniu do pliku manifestu rozszerzenia kilku instancji rozszerzenia możesz wdrożyć go w projekcie za pomocą interfejsu wiersza poleceń Firebase. Gdy wdrażasz za pomocą pliku manifestu rozszerzeń, instalujesz, aktualizujesz i konfigurujesz wszystkie instancje rozszerzeń w pliku manifestu w projekcie naraz.

Aby wdrożyć plik manifestu rozszerzeń:

  1. W wierszu poleceń przejdź do katalogu zawierającego zapisaną konfigurację rozszerzeń. (Jest to katalog, który zawiera firebase.json. Jeśli właśnie uruchomiono ext:export, jesteś już w odpowiednim katalogu).
  2. Uruchom polecenie deploy. Jeśli chcesz wdrożyć rozszerzenia w innym projekcie niż bieżący, podaj też --project=: 
    firebase deploy --only extensions –-project=YOUR_PROJECT_ID

Polecenie deploy zweryfikuje każdą konfigurację instancji, zapyta, czy chcesz usunąć z projektu docelowego instancje rozszerzeń, które nie są wymienione w firebase.json, a następnie wdroży wszystkie instancje rozszerzeń.

Konfiguracje rozszerzeń dotyczące konkretnych projektów

Zapisane konfiguracje rozszerzeń można wykorzystać do wdrażania w wielu różnych projektach, np. w projekcie testowym i produkcyjnym. W takim przypadku wartości niektórych parametrów mogą się różnić w zależności od projektu. Umożliwiają to pliki .env związane z projektem:

  • Wartości parametrów, które różnią się w poszczególnych projektach, umieść w extensions/EXTENSION_INSTANCE_ID.env.YOUR_PROJECT_ID.
  • Wartości parametrów udostępnionych umieść w extensions/EXTENSION_INSTANCE_ID.env.

Czasami podczas emulowania rozszerzeń możesz chcieć użyć innej wartości parametru, np. podać testowy klucz interfejsu API zamiast klucza produkcyjnego. Umieść te parametry w pliku .local:

  • Umieść w sekcji extensions/EXTENSION_INSTANCE_ID.env.local parametry niebędące tajnymi, których chcesz używać podczas emulacji.
  • Umieść wartości parametrów tajnych w extensions/EXTENSION_INSTANCE_ID.secret.local