Firebase-Erweiterung installieren

Sie können alle offiziellen Firebase-Erweiterungen über die Firebase-Konsole, die Firebase-CLI (Befehlszeile) oder ein automatisch generiertes SDK installieren und verwalten.

Sehen Sie sich die Unterschiede bei den unterstützten Aktionen für die einzelnen Installationsmethoden an.


Die Installation über ein automatisch generiertes SDK ist eine neue Option zum Installieren und Verwalten von Erweiterungen. Mit dieser Option verwenden Sie die CLI, um automatisch ein Node SDK für eine bestimmte Erweiterungsversion zu generieren, das Sie als normale Abhängigkeit in Ihre JavaScript- oder TypeScript-Cloud-Funktionen importieren können.

Dieses automatisch generierte SDK enthält:

  • Eine Schnittstelle, die die Parameter der Erweiterung und Typdeklarationen für die meisten nicht primitiven Parametertypen darstellt.
  • Eine Konstruktorfunktion, die eine Instanz der Erweiterung initialisiert
  • Eine Erweiterungsklasse, die Eventarc-Trigger für alle von der Erweiterung ausgegebenen Ereignisse enthält.

Nachdem Sie ein Erweiterungs-SDK generiert haben, erfolgt die gesamte Konfiguration der Erweiterung im Code.

Mit dieser Installationsoption kann die Verwaltung mehrerer Erweiterungsinstanzen erheblich vereinfacht werden, insbesondere in Projekten, die Cloud-Funktionen enthalten, die außerhalb von Erweiterungen definiert sind.


Wenn Sie Erweiterungen installieren oder verwalten möchten, muss Ihnen eine der folgenden Rollen zugewiesen sein: Inhaber oder Bearbeiter oder Firebase-Administrator.

Damit Sie eine Erweiterung installieren können, muss Ihr Projekt im Blaze-Tarif (Pay as you go) sein. Die Installation einer Erweiterung ist zwar kostenlos, aber für die Nutzung von Firebase- oder Cloud-Diensten wie Cloud Secret Manager können Gebühren anfallen, wenn die Nutzung die kostenlose Stufe der Dienste übersteigt.

Hinweis

  1. Falls noch nicht geschehen, fügen Sie Ihrem Projekt Firebase hinzu.

  2. Falls noch nicht geschehen, upgraden Sie Ihr Projekt auf den Blaze-Tarif (Pay as you go).

  3. Installieren Sie die neueste Version der Firebase-CLI oder aktualisieren Sie sie.

  4. Notieren Sie sich Ihre Firebase-Projekt-ID oder den zuvor konfigurierten Projektalias.

    • Projekt-ID: Führen Sie firebase projects:list von einer beliebigen Stelle auf Ihrem Computer aus.
    • Projektalias: Führen Sie firebase use in Ihrem lokalen App-Verzeichnis aus.

Schritt 1: Detaillierte Informationen zu einer Erweiterung ansehen

Dieser Schritt ist optional, wird aber dringend empfohlen.

Bevor Sie eine Firebase Extension installieren, sollten Sie sich detaillierte Informationen zur Erweiterung ansehen, z. B.:

  • Funktionsweise der Erweiterung, Vorinstallationsaufgaben und Details zur Erweiterung
  • Allgemeine Identifikationsinformationen und Beschreibung
  • Ob für die Aufgaben der Erweiterung ein Rechnungskonto erforderlich ist
  • Für den Betrieb erforderliche Google-Dienste (APIs) und Zugriffsrollen
  • Ressourcen, die für die Erweiterung erstellt wurden (z. B. Funktionen)
  • Beschreibungen der nutzerkonfigurierbaren Parameter

So rufen Sie die detaillierten Informationen zu einer Erweiterung auf:

  1. Prüfen Sie, ob Sie Ihre Umgebung eingerichtet und eine Erweiterung ausgewählt haben.

  2. Führen Sie den Befehl „extension-info“ von einer beliebigen Stelle auf Ihrem Computer aus:

    firebase ext:info publisher-id/extension-id

    Die Argumente publisher-id und extension-id sind erforderlich und können auf der Seite mit den Vorinstallationsdetails der Erweiterung gefunden werden.

Schritt 2: Erweiterung installieren

Sehen Sie sich vor der Installation die grundlegenden Spezifikationen der Erweiterung an, z. B. aktivierte APIs, erstellte Ressourcen, gewährter Zugriff usw., sowie die Abrechnungsanforderungen.

Bevor Sie fortfahren, müssen Sie Ihre Umgebung eingerichtet und eine Erweiterung ausgewählt haben.

Cloud Functions for Firebase initialisieren

Wenn Sie ein neues Projekt starten oder in Ihrem Projekt noch keine Cloud Functions for Firebase verwendet werden, führen Sie init functions aus:

cd your-project
firebase init functions

Wählen Sie TypeScript oder JavaScript als Sprache für Ihre Funktionen aus.

Wenn in Ihrem Projekt Cloud Functions bereits initialisiert ist, achten Sie darauf, dass Sie Version 5.1.0 oder höher des firebase-functions-Pakets verwenden:

cd your-project/functions
npm upgrade --save firebase-functions

Wenn Sie ESLint verwenden, sollten Sie generierte SDKs möglicherweise aus Ihrer Konfiguration (.eslintrc.js) ausschließen:

ignorePatterns: [
  "/generated/**/*", // Ignore generated files.
  // ...
],

Erweiterungs-SDK generieren

Führen Sie im lokalen Firebase-Verzeichnis den Befehl ext:sdk:install aus.

firebase ext:sdk:install publisher-id/extension-id@version

So installieren Sie beispielsweise Version 0.1.34 der firestore-send-email-Erweiterung:

firebase ext:sdk:install firebase/firestore-send-email@0.1.34

publisher-id und extension-id sind erforderlich und können auf der Seite mit den Vorinstallationsdetails der Erweiterung unter extensions.dev gefunden werden. @version ist optional. Wenn Sie diesen Teil weglassen, wird die neueste Version installiert.

Sie haben zwei Möglichkeiten:

  • --force: Führen Sie alle folgenden Schritte ohne weitere Bestätigung aus:

    • Das SDK wird automatisch generiert, auch wenn bereits eines für dieselbe Erweiterung und Version generiert wurde.
    • Installieren Sie das automatisch generierte SDK-Paket im Cloud Functions-Node-Projekt.

  • --codebase: Der Name der Codebasis, der das SDK hinzugefügt werden soll. Wenn nicht angegeben, wird das SDK mit dem Befehl der Standard-Codebasis functions hinzugefügt.

Mit diesem Befehl wird automatisch ein Knotenpaket mit einem SDK für die Erweiterung erstellt und einer der Codebases für Cloud-Funktionen Ihres Projekts hinzugefügt. Im Standard-Code-Repository (functions) wird das SDK am folgenden Speicherort gespeichert: 

functions/generated/extensions/publisher-id/extension-id/version

Nachdem das SDK generiert wurde, werden Sie gefragt, ob Sie das SDK auch in Ihrem Cloud Functions-Node-Projekt installieren möchten. Antworten Sie auf diesen Prompt mit Yes (Ja).

Erweiterungsinstanzen konfigurieren

Um die Erweiterung zu konfigurieren, importieren Sie das SDK und rufen Sie für jede Erweiterungsinstanz, die Sie installieren möchten, die Konstruktorfunktion auf. Übergeben Sie dazu eine projektweit eindeutige Instanz-ID und die von der Erweiterung benötigten Konfigurationsparameter.

  1. Importieren Sie in Ihrem Cloud Functions-Quellcode den Konstruktor mit der Anweisung, die vom Befehl ext:sdk:install ausgegeben wird.

    TypeScript

    Wenn Sie beispielsweise ein SDK für die Erweiterung firestore-send-email generiert haben, sieht die import-Anweisung in etwa so aus:

    import { firestoreSendEmail } from "@firebase-extensions/firebase-firestore-send-email-sdk";

    Wenn für die Erweiterung geheime Werte wie Passwörter erforderlich sind, benötigen Sie auch die Funktion defineSecret aus dem Cloud Functions SDK:

    import { defineSecret } from "firebase-functions/params";

    JavaScript

    Wenn Sie beispielsweise ein SDK für die Erweiterung firestore-send-email generiert haben, sieht die require-Anweisung in etwa so aus:

    const { firestoreSendEmail } = require("@firebase-extensions/firebase-firestore-send-email-sdk");

    Wenn für die Erweiterung geheime Werte wie Passwörter erforderlich sind, benötigen Sie auch die Funktion defineSecret aus dem Cloud Functions SDK:

    const { defineSecret } = require('firebase-functions/params');

  2. Rufen Sie für jede Instanz, die Sie konfigurieren möchten, die Konstruktorfunktion auf und exportieren Sie das Ergebnis.

    Geben Sie jeder Instanz eine eindeutige ID, die nur Kleinbuchstaben, Ziffern und Bindestriche enthält.

    TypeScript

    export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    JavaScript

    exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    Hinweis: Secret-Werte müssen mit der Funktion defineSecret angegeben werden.

  3. Führen Sie dann Folgendes aus, um die konfigurierten Erweiterungen bereitzustellen: 

    firebase deploy --only functions --project=projectId-or-alias

    Es gelten alle üblichen Cloud Functions-Bereitstellungsoptionen. So stellen Sie beispielsweise eine einzelne Erweiterungsinstanz aus einer bestimmten Codebasis bereit: 

    firebase deploy --only functions:codebase:extension-instance-id --project=projectId-or-alias

Schritt 3: Einrichtung nach der Installation abschließen

Für einige Erweiterungen sind erforderliche oder optionale Schritte erforderlich, die Sie vor der Verwendung ausführen müssen. Diese Anleitung finden Sie auf der Seite mit den Details nach der Installation Ihrer Erweiterung im Extensions-Dashboard der Firebase-Konsole. Der spezifische Link zum Dashboard wird nach der Installation im Terminal angezeigt.

Sie finden diese Anleitung auch in der Datei POSTINSTALL.md, die im Quellverzeichnis der Erweiterung enthalten ist.

Firebase-Ressourcen erstellen

Wenn Sie die Erweiterung so konfiguriert haben, dass Firebase-Ressourcen (Cloud Firestore-Sammlungen, Realtime Database-Pfade, Cloud Storage-Buckets) verwendet werden, die noch nicht vorhanden sind, erstellen Sie sie, bevor Sie die Erweiterung verwenden.

Eventarc-Event-Handler erstellen

Einige Erweiterungen werden in Eventarc veröffentlicht, wenn während der Ausführung wichtige Ereignisse eintreten. Wenn eine Erweiterung Ereignisse veröffentlicht, können Sie Funktionen schreiben, die mit Ihrer eigenen benutzerdefinierten Logik auf diese Ereignisse reagieren. Das kann beispielsweise nützlich sein, um Nutzer zu benachrichtigen, wenn lang andauernde Aufgaben abgeschlossen sind, oder um die Ausgabe einer Erweiterungsfunktion nachzubearbeiten.

Wenn Sie Handler für Ereignisse definieren möchten, die von der Erweiterung ausgegeben werden, können Sie dazu die Triggermethoden der einzelnen Instanzen verwenden:

TypeScript

export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

export const emailErrorHandler = firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

JavaScript

exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

exports.emailErrorHandler = exports.firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

Sie müssen den Ereignis-Handler zusammen mit der Erweiterungsinstanz exportieren.

Nachdem Sie einen Ereignis-Handler definiert haben und jedes Mal, wenn Sie Änderungen an einem vornehmen, müssen Sie sowohl die Erweiterung als auch den Handler neu bereitstellen.

Mehrere Erweiterungsinstanzen installieren

Sie können dieselbe Erweiterung mehrmals im selben Projekt installieren. Jede installierte Instanz kann eine eigene benutzerdefinierte Konfiguration und eigene Erweiterungsressourcen haben. Jede installierte Instanz wird anhand ihrer Instanz-ID identifiziert und referenziert. Diese ist innerhalb Ihres Projekts eindeutig.

Rufen Sie die Konstruktorfunktion des automatisch generierten SDK einmal für jede Instanz auf, die Sie installieren und konfigurieren möchten.

Nächste Schritte