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

Plik manifestu 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 przejściowego do produkcyjnego);
  • Wdrażanie wszystkich rozszerzeń naraz
  • Przetestuj działanie rozszerzeń w aplikacji za pomocą Firebase Local Emulator Suite
  • Zatwierdzanie konfiguracji rozszerzeń w systemie kontroli źródła
  • Uwzględnianie rozszerzeń w potoku CI/CD

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

  • Sekcja extensions w pliku firebase.json, która jest mapą identyfikatora instancji do odwołania do wersji rozszerzenia. Na przykład:

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

  • Pliki .env zawierające konfigurację każdej instancji rozszerzenia w podkatalogu extensions/ katalogu projektu w 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ń

Plik manifestu rozszerzeń można utworzyć na 3 sposoby:

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

Poniżej opisujemy 2 pierwsze metody.

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

Większość poleceń ext: interfejsu wiersza poleceń Firebase możesz uruchamiać z opcją --local, aby aktualizować plik manifestu rozszerzeń bez zmiany bieżącej konfiguracji projektu.

Na 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 kilka dodatkowych przykładów poleceń, które modyfikują plik manifestu rozszerzeń:

# 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, wykonaj te czynności:

  1. Jeśli jeszcze nie masz skonfigurowanego interfejsu wiersza poleceń Firebase, zrób to teraz.
  2. W wierszu poleceń powłoki przejdź do katalogu projektu. (Katalog projektu zawiera plik firebase.json).
  3. Uruchom polecenie ext:export: 
    firebase ext:export

Polecenie ext:export doda sekcję extensions do pliku firebase.json. 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ą Firebase Local Emulator Suite

Po dodaniu instancji rozszerzeń do pliku manifestu 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 emulatora w trybie interaktywnym, wykonaj polecenie: firebase emulators:start
    • Aby uruchomić pakiet emulatorów i wykonać skrypt testowy, uruchom: firebase emulators:exec my-test.sh

Jeśli w pliku manifestu masz wymienione instancje rozszerzeń, Local Emulator Suite pobierze kod źródłowy tych rozszerzeń do ~/.cache/firebase/extensions. Po ich pobraniu uruchomi się Local Emulator Suite i będzie można aktywować dowolne funkcje rozszerzeń wywoływane w tle oraz połączyć aplikację z pakietem emulatora, aby przetestować ich integrację z aplikacją.

Wdrażanie konfiguracji rozszerzeń w projekcie

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

Aby wdrożyć plik manifestu rozszerzeń:

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

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

Konfiguracje rozszerzeń związane z projektem

Zapisane konfiguracje rozszerzeń można wykorzystać do wdrożenia w wielu różnych projektach, na przykład w projekcie przejściowym i produkcyjnym. W takim przypadku niektóre wartości parametrów mogą być różne dla każdego projektu. Umożliwiają to pliki .env związane z projektem:

  • Wartości parametrów, które różnią się między projektami, umieść w pliku extensions/EXTENSION_INSTANCE_ID.env.YOUR_PROJECT_ID.
  • Wartości parametrów wspólnych umieść w elemencie 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 produkcyjnego. Umieść te parametry w pliku .local:

  • Umieść parametry, które nie są tajne i których chcesz używać podczas emulacji, w pliku extensions/EXTENSION_INSTANCE_ID.env.local
  • Umieść wartości parametrów obiektu tajnego w extensions/EXTENSION_INSTANCE_ID.secret.local