Aggiungere hook utente a un'estensione

Puoi consentire agli utenti che installano la tua estensione di inserire la propria logica personalizzata nell'esecuzione dell'estensione. Esistono due modi per farlo:

Eventi Eventarc: per consentire agli utenti di reagire in modo asincrono agli eventi, puoi pubblicare su Eventarc. Gli utenti possono eseguire il deployment di funzioni di gestione degli eventi che, ad esempio, inviano notifiche al completamento di attività a lunga esecuzione oppure possono definire le proprie funzioni di post-elaborazione.
Hook sincroni: per consentire agli utenti di aggiungere logica di blocco alla tua estensione, puoi aggiungere hook sincroni in punti predefiniti dell'operazione dell' estensione. In questi punti, esegui una funzione fornita dall'utente e procedi solo dopo il completamento. Le attività di pre-elaborazione rientrano spesso in questa categoria.

Un'estensione può utilizzare uno o entrambi i metodi.

Eventi Eventarc

Per pubblicare eventi da un'estensione:

Dichiara i tipi di eventi che pubblicherai nel file extension.yaml:
```
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
```
L'identificatore type è composto da diversi campi delimitati da punti. I campi ID publisher, nome estensione e nome evento sono obbligatori. Il campo versione è consigliato. Scegli un nome evento univoco e descrittivo per ogni tipo di evento che pubblichi.

Ad esempio, l'estensione storage-resize-images dichiara un singolo tipo di evento:
```
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.
```
Gli utenti potranno scegliere a quali eventi abbonarsi quando installano l'estensione.
Nelle funzioni dell'estensione, importa l'API Eventarc dall'Admin SDK e inizializza un canale di eventi utilizzando le impostazioni di installazione dell'utente. Queste impostazioni vengono esposte utilizzando le seguenti variabili di ambiente:
- EVENTARC_CHANNEL: il nome completo del canale Eventarc su cui l'utente ha scelto di pubblicare gli eventi.
- EXT_SELECTED_EVENTS: un elenco separato da virgole dei tipi di eventi che l'utente ha scelto di pubblicare. Quando inizializzi un canale con questo valore, l'SDK Admin filtra automaticamente gli eventi che l'utente non ha selezionato.
- EVENTARC_CLOUD_EVENT_SOURCE: l'identificatore dell'origine Cloud Event. L'SDK Admin passa automaticamente questo valore nel campo source degli eventi pubblicati. In genere non è necessario utilizzare esplicitamente questa variabile.
Se gli eventi non sono stati attivati durante l'installazione, queste variabili non saranno definite. Puoi utilizzare questo fatto per inizializzare un canale di eventi solo quando gli eventi sono attivati:
```
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,
  });
```

Pubblica gli eventi sul canale nei punti dell'estensione che vuoi esporre agli utenti. Ad esempio:

// 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: {
      // ...
    }
});

Documenta gli eventi che pubblichi nel file PREINSTALL o POSTINSTALL.

Per ogni evento, documenta quanto segue:
- Lo scopo previsto
- Il punto nella logica dell'estensione in cui viene eseguito
- I dati di output che include
- Le condizioni per la sua esecuzione
Inoltre, avvisa gli utenti di non eseguire azioni nei gestori di eventi che potrebbero attivare la stessa estensione, con conseguente loop infinito.

Quando pubblichi eventi da un'estensione, gli utenti possono eseguire il deployment di gestori di eventi per rispondere con una logica personalizzata.

Ad esempio, il seguente esempio elimina l'immagine originale dopo averne modificato le dimensioni. Tieni presente che questo gestore di esempio utilizza la proprietà subject dell'evento, che in questo caso è il nome file originale dell'immagine.

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.firebasestorage.app")
          .file(event.subject)
          .delete();
    });

Per ulteriori informazioni, consulta Trigger di eventi personalizzati.

Esempio

L'estensione ufficiale Resize Images fornisce un hook asincrono pubblicando su Eventarc dopo aver modificato le dimensioni di un'immagine.

Hook sincroni

Quando vuoi fornire agli utenti un hook che deve essere completato correttamente affinché una delle funzioni dell'estensione funzioni, utilizza gli hook sincroni.

Un hook sincrono chiama una Cloud Function richiamabile tramite HTTPS definita dall'utente e attende il completamento (possibilmente con un valore restituito) prima di continuare. Un errore nella funzione fornita dall'utente genera un errore nella funzione dell'estensione.

Per esporre un hook sincrono:

Aggiungi un parametro all'estensione che consenta agli utenti di configurare l'estensione con l'URL della Cloud Function personalizzata. Ad esempio:

- 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

Nel punto dell'estensione in cui vuoi esporre l'hook, chiama la funzione utilizzando il relativo URL. Ad esempio:

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.
      // ...
    });

Documenta gli hook che rendi disponibili nel file PREINSTALL o POSTINSTALL.

Per ogni hook, documenta quanto segue:
- Lo scopo previsto
- Il punto nella logica dell'estensione in cui viene eseguito
- Gli input e gli output previsti
- Le condizioni (o le opzioni) per la sua esecuzione
Inoltre, avvisa gli utenti di non eseguire azioni nella funzione hook che potrebbero attivare la stessa estensione, con conseguente loop infinito.

Esempio

L'estensione Algolia Search fornisce un hook sincrono per chiamare una funzione di trasformazione fornita dall'utente prima di scrivere su Algolia.

Aggiungere hook utente a un'estensione Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Eventi Eventarc

Esempio

Hook sincroni

Esempio

Aggiungere hook utente a un'estensione