Projektkonfigurationen mit dem Erweiterungsmanifest verwalten

Ein Erweiterungsmanifest ist eine Liste von Erweiterungsinstanzen und ihren Konfigurationen. Mit dem Manifest können Sie Folgendes tun:

  • Erweiterungskonfiguration mit anderen teilen
  • Erweiterungskonfiguration zwischen verschiedenen Projekten kopieren (z. B. von Ihrem Staging-Projekt in Ihr Produktionsprojekt)
  • Alle Erweiterungen gleichzeitig bereitstellen
  • Mit dem Firebase Local Emulator Suite testen, wie Ihre Erweiterungen mit Ihrer App funktionieren
  • Erweiterungskonfiguration in die Versionsverwaltung übertragen
  • Erweiterungen in Ihre CI/CD-Pipeline einbinden

Ein Erweiterungsmanifest besteht aus zwei Teilen:

  • Der Abschnitt extensions Ihrer firebase.json, der eine Zuordnung von Instanz-ID zu Erweiterungsversionsreferenz enthält. Beispiel:

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

  • .env-Dateien mit der Konfiguration für jede Ihrer Erweiterungsinstanzen im Unterverzeichnis extensions/ Ihres Firebase-Projektverzeichnisses. Eine Instanz von storage-resize-images könnte beispielsweise eine .env-Datei wie die folgende haben:

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

Erweiterungsmanifest erstellen

Es gibt drei Möglichkeiten, ein Erweiterungsmanifest zu erstellen:

  • Erweiterungsmanifest mit der Firebase CLI verwalten
  • Erweiterungskonfiguration eines Projekts exportieren
  • Manifestdateien manuell bearbeiten

Die ersten beiden Methoden werden im Folgenden erläutert.

Erweiterungsmanifest mit der Firebase CLI verwalten

Sie können die meisten ext:-Befehle der Firebase CLI mit der Option --local ausführen, um das Erweiterungsmanifest zu aktualisieren, ohne die aktuelle Konfiguration des Projekts zu ändern.

Beispiel:

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

Wenn Sie den obigen Befehl ausführen, werden Sie aufgefordert, die aktuelle Version der firebase/firestore-bigquery-export-Erweiterung zu konfigurieren und die Konfiguration im Manifest zu speichern. Die Konfiguration wird jedoch nicht in Ihrem Projekt bereitgestellt.

Hier sind einige weitere Beispiele für Befehle, mit denen das Erweiterungsmanifest geändert wird:

# 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

Erweiterungskonfiguration eines Projekts exportieren

So speichern Sie die aktuelle Erweiterungskonfiguration eines Projekts im Manifest:

  1. Richten Sie die Firebase CLI ein, falls noch nicht geschehen.
  2. Wechseln Sie in einer Shell-Eingabeaufforderung in das Projektverzeichnis. (Ihr Projektverzeichnis enthält die Datei firebase.json).
  3. Führen Sie den Befehl ext:export aus: 
    firebase ext:export

Mit dem Befehl ext:export wird der Datei firebase.json ein Abschnitt extensions hinzugefügt. Außerdem wird mit dem Befehl ext:export ein extensions-Verzeichnis erstellt, das für jede installierte Erweiterungsinstanz eine .env-Datei enthält. Diese Dateien enthalten die Konfigurationsparameter für die einzelnen Instanzen.

Erweiterungskonfiguration mit dem Firebase Local Emulator Suite testen

Nachdem Sie Ihrem Erweiterungsmanifest einige Erweiterungsinstanzen hinzugefügt haben, können Sie sie mit dem Local Emulator Suite testen.

  1. Installieren und konfigurieren Sie die Local Emulator Suite.

  2. Local Emulator Suite starten:

    • So führen Sie die Emulator Suite interaktiv aus: firebase emulators:start
    • Führen Sie den folgenden Befehl aus, um die Emulator Suite zu starten und ein Testskript auszuführen: firebase emulators:exec my-test.sh

Wenn in Ihrem Manifest Erweiterungsinstanzen aufgeführt sind, lädt die Local Emulator Suite den Quellcode dieser Erweiterungen in ~/.cache/firebase/extensions herunter. Nach dem Herunterladen wird die Local Emulator Suite gestartet und Sie können alle im Hintergrund ausgelösten Funktionen der Erweiterungen auslösen und Ihre App mit der Emulator-Suite verbinden, um die Integration in Ihre App zu testen.

Erweiterungskonfiguration in einem Projekt bereitstellen

Nachdem Sie Ihrem Erweiterungsmanifest einige Erweiterungsinstanzen hinzugefügt haben, können Sie es mit der Firebase CLI in einem Projekt bereitstellen. Wenn Sie ein Erweiterungsmanifest bereitstellen, werden alle Erweiterungsinstanzen im Manifest gleichzeitig in einem Projekt installiert, aktualisiert und konfiguriert.

So stellen Sie ein Erweiterungsmanifest bereit:

  1. Wechseln Sie in einer Shell-Eingabeaufforderung in das Verzeichnis, das die gespeicherte Erweiterungskonfiguration enthält. (Dies ist das Verzeichnis, das firebase.json enthält. Wenn Sie gerade ext:export ausgeführt haben, befinden Sie sich bereits im richtigen Verzeichnis.
  2. Führen Sie den Befehl deploy aus: Wenn Sie die Erweiterungen in einem anderen Projekt als dem aktuellen bereitstellen möchten, geben Sie auch --project= an: 
    firebase deploy --only extensions –-project=YOUR_PROJECT_ID

Mit dem Befehl deploy wird jede Instanzkonfiguration validiert. Sie werden gefragt, ob Sie Erweiterungsinstanzen aus Ihrem Zielprojekt löschen möchten, die nicht in firebase.json aufgeführt sind. Anschließend werden alle Erweiterungsinstanzen bereitgestellt.

Projektspezifische Erweiterungskonfigurationen

Gespeicherte Erweiterungskonfigurationen können für die Bereitstellung in mehreren verschiedenen Projekten verwendet werden, z. B. in einem Staging-Projekt und einem Produktionsprojekt. Dabei müssen einige Parameterwerte möglicherweise für jedes Projekt unterschiedlich sein. Projektspezifische .env-Dateien machen dies möglich:

  • Fügen Sie Parameterwerte, die sich zwischen Projekten unterscheiden, in extensions/EXTENSION_INSTANCE_ID.env.YOUR_PROJECT_ID ein.
  • Legen Sie freigegebene Parameterwerte in extensions/EXTENSION_INSTANCE_ID.env ab.

Manchmal möchten Sie beim Emulieren Ihrer Erweiterungen einen anderen Parameterwert verwenden, z. B. einen Test-API-Schlüssel anstelle eines Produktionsschlüssels. Fügen Sie diese Parameter in eine .local-Datei ein:

  • Fügen Sie nicht geheime Parameter, die Sie während der Emulation verwenden möchten, in extensions/EXTENSION_INSTANCE_ID.env.local ein.
  • Fügen Sie geheime Parameterwerte in extensions/EXTENSION_INSTANCE_ID.secret.local ein.