Firebase-Erweiterung installieren

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

Lesen Sie die Unterschiede bei den unterstützten Aktionen für jede Installationsmethode.


Die Installation mit einem automatisch generierten SDK ist eine neue Option zum Installieren und Verwalten von Erweiterungen. Mit dieser Option generieren Sie mit der Befehlszeile automatisch ein Node SDK für eine bestimmte Erweiterungsversion, 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 darstellt, und Typdeklarationen für die meisten nicht primitiven Parametertypen.
  • Eine Konstruktorfunktion, die eine Instanz der Erweiterung initialisiert
  • Eine Erweiterungsklasse, die Eventarc-Trigger für alle von der Erweiterung gesendeten Ereignisse enthält.

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

Mit dieser Installationsoption lässt sich die Verwaltung mehrerer Erweiterungsinstanzen erheblich vereinfachen, insbesondere in Projekten, die Cloud-Funktionen enthalten, die außerhalb von Erweiterungen definiert sind.


Wenn Sie Erweiterungen installieren oder verwalten möchten, müssen Sie eine der folgenden Rollen haben: Inhaber oder Bearbeiter oder Firebase-Administrator.

Wenn Sie eine Erweiterung installieren möchten, muss für Ihr Projekt der Blaze-Tarif (Pay as you go) verwendet werden. Die Installation einer Erweiterung ist kostenlos. Es können jedoch Kosten für die Nutzung von Firebase-Diensten oder Cloud-Diensten wie Cloud Secret Manager anfallen, wenn Ihre Nutzung die kostenlose Stufe der Dienste überschreitet.

Hinweis

  1. Fügen Sie Ihrem Projekt Firebase hinzu, falls noch nicht geschehen.

  2. Falls noch nicht geschehen, führen Sie ein Upgrade auf den Blaze-Tarif (Pay-as-you-go) durch.

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

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

    • Projekt-ID: Mit dieser ID können Sie firebase projects:list von überall auf Ihrem Computer aus ausführen.
    • Projektalias: Führen Sie firebase use aus dem lokalen App-Verzeichnis aus.

Schritt 1: Detaillierte Informationen zu einer Erweiterung aufrufen

Dieser Schritt ist optional, wird aber dringend empfohlen.

Bevor Sie eine Firebase Extension installieren, sollten Sie sich ausführliche Informationen zur Erweiterung ansehen, darunter:

  • Funktionsweise der Erweiterung, alle Aufgaben vor der Installation und Details zur Erweiterung
  • Allgemeine Informationen zur Identifizierung 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 von Nutzern konfigurierbaren Parameter

So rufen Sie die Details einer Erweiterung auf:

  1. Sie müssen Ihre Umgebung eingerichtet und eine Erweiterung ausgewählt haben.

  2. Sie können den Befehl „extension-info“ von überall auf Ihrem Computer ausführen:

    firebase ext:info publisher-id/extension-id

    Die Argumente publisher-id und extension-id sind erforderlich und finden Sie auf der Detailseite zur Vorinstallation der Erweiterung.

Schritt 2: Erweiterung installieren

Lesen Sie sich vor der Installation die grundlegenden Spezifikationen für die Erweiterung durch (z. B. aktivierte APIs, erstellte Ressourcen, gewährter Zugriff usw.) und 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 erstellen 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 die Funktionen aus.

Wenn in Ihrem Projekt bereits Cloud Functions initialisiert wurden, müssen 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 auch aus Ihrer Konfiguration ausschließen (.eslintrc.js):

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

Erweiterungs-SDK generieren

Führen Sie den Befehl ext:sdk:install in Ihrem lokalen Firebase-Verzeichnis 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 Details zur Vorinstallation der Erweiterung auf extensions.dev gefunden werden. @version ist optional. Wenn Sie diesen Teil weglassen, wird mit dem Tool die neueste Version installiert.

Sie haben zwei Möglichkeiten:

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

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

  • --codebase: Der Name der Codebasis, der das SDK hinzugefügt werden soll. Wenn Sie keinen Wert angeben, wird das SDK der Standard-Codebase functions hinzugefügt.

Mit diesem Befehl wird ein Node-Paket mit einem SDK erstellt, das automatisch für die Erweiterung generiert wird. Dieses Paket wird dann einer der Cloud Functions-Codebases Ihres Projekts hinzugefügt. In der Standard-Codebasis (functions) wird das SDK an folgendem Speicherort gespeichert: 

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

Nachdem das SDK generiert wurde, werden Sie gefragt, ob Sie es auch in Ihrem Cloud Functions-Node-Projekt installieren möchten. Beantworten Sie diese Aufforderung mit Ja.

Erweiterungsinstanzen konfigurieren

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

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

    TypeScript

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

    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 außerdem die Funktion defineSecret aus dem Cloud Functions SDK:

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

    JavaScript

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

    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 außerdem 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",
});

    Geheime 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

    Alle üblichen Optionen für die Bereitstellung von Cloud Functions gelten. So stellen Sie beispielsweise eine einzelne Erweiterungs-Instanz 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 vor der Verwendung erforderliche oder optionale Schritte erforderlich. Diese Anleitung finden Sie auf der Seite mit den Details Ihrer Erweiterung im Extensions-Dashboard der Firebase-Konsole nach der Installation. Der Link zum Dashboard wird nach der Installation im Terminal angezeigt.

Diese Anleitung finden Sie auch in der Datei POSTINSTALL.md im Quellverzeichnis der Erweiterung.

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 diese, bevor Sie die Erweiterung verwenden.

Eventarc-Ereignis-Handler erstellen

Einige Erweiterungen veröffentlichen in Eventarc, wenn während der Ausführung wichtige Ereignisse auftreten. 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 langlaufende Aufgaben abgeschlossen sind, oder um die Ausgabe einer Erweiterungsfunktion zu verarbeiten.

Wenn Sie Handler für eines der von der Erweiterung gesendeten Ereignisse definieren möchten, können Sie 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 Erweiterungs-Instanz exportieren.

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

Mehrere Erweiterungsinstanzen installieren

Sie können dieselbe Erweiterung mehrmals in dasselbe Projekt installieren. Jede installierte Instanz kann eine eigene benutzerdefinierte Konfiguration und eigene Erweiterungsressourcen haben. Sie identifizieren und verweisen auf jede installierte Instanz anhand ihrer Instanz-ID, die innerhalb Ihres Projekts eindeutig ist.

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

Nächste Schritte