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
  • kopiować konfigurację rozszerzeń między różnymi projektami (np. z projektu roboczego do projektu produkcyjnego);
  • Wdrażanie wszystkich rozszerzeń naraz
  • Testowanie działania rozszerzeń w aplikacji za pomocą Firebase Local Emulator Suite
  • Zatwierdzanie konfiguracji rozszerzeń w kontroli wersji
  • 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ą identyfikatorów instancji na odwołania 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",
 }
}

  • pliki .env zawierające konfigurację każdego wystąpienia rozszerzenia w podkatalogu extensions/ w 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}.appspot.com
IMG_SIZES=100x100
DELETE_ORIGINAL_FILE=false

Tworzenie pliku manifestu rozszerzeń

Manifest 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 pierwsze 2 metody.

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

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

Przykład:

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

Po wykonaniu tego polecenia pojawi się prośba o skonfigurowanie najnowszej wersji rozszerzenia firebase/firestore-bigquery-export i zapisanie konfiguracji w pliku manifestu. Nie zostanie jednak wdrożona konfiguracja w Twoim projekcie.

Oto kilka 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 tego nie zrobiono, skonfiguruj wiersz poleceń Firebase.
  2. W wierszu powłoki przejdź do katalogu projektu. (plik firebase.json znajduje się w katalogu projektu).
  3. Uruchom polecenie ext:export: 
    firebase ext:export

Polecenie ext:export spowoduje dodanie sekcji 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 dla każdej instancji.

Testowanie konfiguracji rozszerzeń za pomocą Firebase Local Emulator Suite

Po dodaniu do pliku manifestu rozszerzeń niektórych 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: firebase emulators:start
    • Aby uruchomić Pakiet emulatorów i wykonać skrypt testowy, wykonaj te czynności:firebase emulators:exec my-test.sh

Jeśli masz w pliku manifestu instancje rozszerzeń, Local Emulator Suite pobierze kod źródłowy tych rozszerzeń do ~/.cache/firebase/extensions. Po ich pobraniu rozpocznie się Local Emulator Suite, dzięki czemu będziesz mieć możliwość wywołania dowolnej funkcji wywoływanej w tle przez rozszerzenia oraz połączenia aplikacji z pakietem emulatorów, aby przetestować ich integrację z Twoją aplikacją.

Wdrażanie konfiguracji rozszerzeń w projekcie

Po dodaniu do pliku manifestu rozszerzenia kilku jego instancji możesz wdrożyć go w projekcie za pomocą wiersza poleceń Firebase. Wdrażając 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ń w powłoce przejdź do katalogu zawierającego zapisaną konfigurację rozszerzeń. (to katalog zawierający firebase.json). Jeśli właśnie uruchomiono ext:export, katalog jest już prawidłowy.
  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 zweryfikuje każdą konfigurację instancji, zapyta, czy chcesz usunąć z projektu docelowego wszystkie instancje rozszerzenia, które nie są wymienione w firebase.json, a następnie wdrożyć wszystkie instancje rozszerzenia.

Konfiguracje rozszerzeń związane z poszczególnymi projektami

Zapisane konfiguracje rozszerzeń można wdrażać w różnych projektach, np. w projekcie testowym i produkcyjnym. W takim przypadku niektóre wartości parametrów mogą się różnić w zależności od projektu. Pliki .env związane z projektem umożliwiają:

  • Dodaj do extensions/EXTENSION_INSTANCE_ID.env.YOUR_PROJECT_ID wartości parametrów, które różnią się między projektami
  • Wpisz wartości udostępnionych parametrów w polu extensions/EXTENSION_INSTANCE_ID.env.

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

  • W polu extensions/EXTENSION_INSTANCE_ID.env.local umieść parametry niepoufne, których chcesz używać podczas emulacji.
  • Umieść wartości tajnych parametrów w polu extensions/EXTENSION_INSTANCE_ID.secret.local