Nutzer-Hooks zu einer Erweiterung hinzufügen

Sie können Nutzern, die Ihre Erweiterung installieren, die Möglichkeit bieten, ihre eigenen in die Ausführung der Erweiterung integriert werden soll. Es gibt zwei Möglichkeiten, erreichen Sie dies:

  • Eventarc-Ereignisse: Damit können Nutzer asynchron auf können Sie in Eventarc veröffentlichen. Nutzer können Event-Handler bereitstellen Funktionen, die z. B. Benachrichtigungen nach längerer Ausführungszeit Aufgaben erledigt haben oder eigene Nachbearbeitungsfunktionen definieren können.

  • Synchrone Hooks, um Nutzern die Möglichkeit zu geben, eine Blockierlogik zu Ihrem -Erweiterung können Sie synchrone Hooks an vordefinierten Punkten im wie die Erweiterung funktioniert. An diesen Punkten führen Sie eine User-Provider-Funktion aus, und erst fortfahren, wenn der Vorgang abgeschlossen ist. Vorverarbeitungsaufgaben fallen häufig dieser Kategorie.

Für eine Erweiterung kann entweder eine oder beide Methoden verwendet werden.

Eventarc-Ereignisse

So veröffentlichen Sie Ereignisse aus einer Erweiterung:

  1. Deklarieren Sie in der Datei extension.yaml die Ereignistypen, die Sie veröffentlichen möchten:

    events:
  - type: publisher-id.extension-name.version.event-name
    description: event-description
  - type: publisher-id.extension-name.version.another-event-name
    description: another-event-description

    Die Kennzeichnung type besteht aus mehreren durch Punkte getrennten Feldern. Die Die Felder publisher ID, Erweiterungsname und Ereignisname erforderlich. Das Versionsfeld wird empfohlen. Wählen Sie einen eindeutigen und aussagekräftigen Ereignisnamens für jeden von Ihnen veröffentlichten Ereignistyp angezeigt.

    Beispiel: Die Erweiterung storage-resize-images deklariert einen einzelnen Ereignistyp:

    events:
  - type: firebase.extensions.storage-resize-images.v1.complete
    description: |
      Occurs when image resizing completes. The event will contain further
      details about specific formats and sizes.

    Nutzer können auswählen, welche Ereignisse sie abonnieren möchten, installieren Sie die Erweiterung.

  2. Importieren Sie in den Erweiterungsfunktionen die Eventarc API aus dem Admin SDK. und initialisieren Sie einen Ereigniskanal mithilfe der Installationseinstellungen des Nutzers. Diese Einstellungen werden über die folgenden Umgebungsvariablen freigegeben:

    • EVENTARC_CHANNEL: Der vollständige Name des Eventarc-Kanals, in dem der Nutzer Ereignisse veröffentlichen möchte.
    • EXT_SELECTED_EVENTS: eine durch Kommas getrennte Liste von Ereignistypen, die der Nutzer die Sie zum Veröffentlichen ausgewählt haben. Wenn Sie einen Kanal mit diesem Wert initialisieren, Mit dem Admin SDK werden Ereignisse, die der Nutzer nicht ausgewählt hat, automatisch herausgefiltert.
    • EVENTARC_CLOUD_EVENT_SOURCE: die Cloud-Ereignis-Quell-ID. Die Das Admin SDK übergibt diesen Wert automatisch im Feld source von veröffentlichten Ereignissen. In der Regel müssen Sie diesen Code .

    Wenn Ereignisse bei der Installation nicht aktiviert waren, werden diese Variablen nicht definiert. Sie können einen Ereigniskanal nur dann initialisieren, wenn Ereignisse aktiviert sind:

    import * as admin from "firebase-admin";
import {getEventarc} from 'firebase-admin/eventarc';

admin.initializeApp();

// Set eventChannel to a newly-initialized channel, or `undefined` if events
// aren't enabled.
const eventChannel =
  process.env.EVENTARC_CHANNEL &&
  getEventarc().channel(process.env.EVENTARC_CHANNEL, {
    allowedEventTypes: process.env.EXT_SELECTED_EVENTS,
  });

  3. Ereignisse an den gewünschten Stellen in der Erweiterung auf dem Kanal veröffentlichen für Nutzer sichtbar wird. Beispiel:

    // If events are enabled, publish a `complete` event to the configured
// channel.
eventChannel && eventChannel.publish({
    type: 'firebase.extensions.storage-resize-images.v1.complete',
    subject: filename,  // the name of the original file
    data: {
      // ...
    }
});

  4. Dokumentieren Sie die Ereignisse, die Sie veröffentlichen, entweder in PREINSTALL oder POSTINSTALL. -Datei.

    Dokumentieren Sie für jedes Ereignis Folgendes:

    • Zweck
    • Den Punkt in der Logik der Erweiterung, der ausgeführt wird
    • Die darin enthaltenen Ausgabedaten
    • Die Bedingungen für die Ausführung

    Außerdem solltest du Nutzer warnen, keine Aktionen in ihrem Ereignis auszuführen. Handler, die dieselbe Erweiterung auslösen könnten, was zu einer unendlichen Schleife

Wenn du Ereignisse aus einer Erweiterung veröffentlichst, können Nutzer Event-Handler bereitstellen mit benutzerdefinierter Logik.

Im folgenden Beispiel wird das Originalbild gelöscht, nachdem es in der Größe angepasst. Beachten Sie, dass dieser Beispiel-Handler das Attribut subject von das Ereignis, in diesem Fall der ursprüngliche Dateiname des Bildes.

exports.onimageresized = onCustomEventPublished(
    "firebase.extensions.storage-resize-images.v1.complete",
    (event) => {
      logger.info("Received image resize completed event", event);
      // For example, delete the original.
      return admin.storage()
          .bucket("my-project.appspot.com")
          .file(event.subject)
          .delete();
    });

Weitere Informationen finden Sie unter Trigger für benutzerdefinierte Ereignisse. Informationen.

Beispiel

Die offizielle Erweiterung zur Größenanpassung von Bildern bietet einen asynchronen Hook durch Veröffentlichung in Eventarc nach der Größenänderung.

Synchrone Hooks

Wenn Sie Nutzern einen Hook zur Verfügung stellen möchten, der erfolgreich abgeschlossen werden muss Verwenden Sie synchrone Hooks, damit eine Ihrer Erweiterungsfunktionen funktioniert.

Ein synchroner Hook ruft eine benutzerdefinierte HTTPS-Callable Cloud auf. Funktion ein und wartet auf den Abschluss (möglicherweise mit einem zurückgegebener Wert), bevor Sie fortfahren. Fehler in der vom Nutzer bereitgestellten Funktion führt zu einem Fehler in der Erweiterungsfunktion.

So geben Sie einen synchronen Hook frei:

  1. Fügen Sie Ihrer Erweiterung einen Parameter hinzu, mit dem Nutzer die Erweiterung mit der URL zu ihrer benutzerdefinierten Cloud-Funktion konfigurieren können. Beispiel:

    - param: PREPROCESSING_FUNCTION
  label: Pre-processing function URL
  description: >
    An HTTPS callable function that will be called to transform the input data
    before it is processed by this function.
  type: string
  example: https://us-west1-my-project-id.cloudfunctions.net/preprocessData
  required: false

  2. Rufen Sie an der Stelle in Ihrer Erweiterung, an der Sie den Hook sichtbar machen möchten, die Methode -Funktion mithilfe ihrer URL. Beispiel:

    const functions = require('firebase-functions/v1');
const fetch = require('node-fetch');

const preprocessFunctionURL = process.env.PREPROCESSING_FUNCTION;

exports.yourFunctionName = functions.firestore.document("collection/{doc_id}")
    .onWrite((change, context) => {
      // PREPROCESSING_FUNCTION hook begins here.
      // If a preprocessing function is defined, call it before continuing.
      if (preprocessFunctionURL) {
        try {
          await fetch(preprocessFunctionURL); // Could also be a POST request if you want to send data.
        } catch (e) {
          // Preprocessing failure causes the function to fail.
          functions.logger.error("Preprocessor error:", e);
          return;
        }
      }
      // End of PREPROCESSING_FUNCTION hook.

      // Main function logic follows.
      // ...
    });

  3. Dokumentieren Sie alle Hooks, die Sie in den PREINSTALL- oder POSTINSTALL-Datei.

    Dokumentieren Sie für jeden Hook Folgendes:

    • Zweck
    • Den Punkt in der Logik der Erweiterung, der ausgeführt wird
    • Die erwarteten Ein- und Ausgaben
    • Die Bedingungen (oder Optionen) für die Ausführung

    Außerdem sollten Sie Nutzer warnen, in der Hook-Funktion keine Aktionen auszuführen, die dieselbe Erweiterung auslösen könnten, was zu einer endlosen Schleife führen würde.

Beispiel

Algolia Search-Erweiterung bietet einen synchronen Hook zum Aufruf einer vom Nutzer bereitgestellten Transformationsfunktion bevor sie an Algolia geschrieben haben.