Aggiungi hook utente a un'estensione

Puoi fornire agli utenti che installano la tua estensione la possibilità di inserire la propria logica personalizzata nell'esecuzione della tua estensione. Esistono due modi per ottenere questo risultato:

• Eventi Eventarc : per offrire agli utenti un modo per reagire in modo asincrono agli eventi, puoi pubblicare su Eventarc. Gli utenti possono distribuire funzioni del gestore eventi che, ad esempio, inviano notifiche al termine di attività di lunga durata oppure possono definire le proprie funzioni di post-elaborazione.

• Hook sincroni : per offrire agli utenti un modo per aggiungere logica di blocco alla tua estensione, puoi aggiungere hook sincroni in punti predefiniti nel funzionamento dell'estensione. A questi punti, esegui una funzione del provider utente e procedi solo dopo il suo completamento. Le attività di pre-elaborazione spesso rientrano in questa categoria.

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

Eventi Eventarc

Per pubblicare eventi da un'estensione:

1. 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 editore , nome estensione e nome evento sono obbligatori. Si consiglia il campo della versione. 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 iscriversi quando installeranno l'estensione.

2. Nelle funzioni di estensione, importa l'API Eventarc da 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 di tipi di eventi che l'utente ha scelto di pubblicare. Quando inizializzi un canale con questo valore, Admin SDK filtra automaticamente gli eventi non selezionati dall'utente.
   • EVENTARC_CLOUD_EVENT_SOURCE : identificatore dell'origine dell'evento cloud. L'Admin SDK passa automaticamente questo valore nel campo source degli eventi pubblicati. In genere non è necessario utilizzare esplicitamente questa variabile.

   Se gli eventi non erano abilitati al momento dell'installazione, queste variabili non saranno definite. Puoi utilizzare questo fatto per inizializzare un canale di eventi solo quando gli eventi sono abilitati:

   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. Pubblica eventi sul canale nei punti della tua estensione che desideri esporre agli utenti. Per 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: {
         // ...
       }
   });
   

4. Documenta gli eventi che pubblichi nel file PREINSTALL o POSTINSTALL.

   Per ogni evento documentare quanto segue:

   • Lo scopo previsto
   • Il punto nella logica della tua 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 eventi che potrebbero attivare la stessa estensione, generando un ciclo infinito.

Quando pubblichi eventi da un'estensione, gli utenti possono distribuire gestori eventi per rispondere con una logica personalizzata.

Ad esempio, l'esempio seguente elimina l'immagine originale dopo che è stata ridimensionata. 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.appspot.com")
          .file(event.subject)
          .delete();
    });

Per ulteriori informazioni, consulta Attivatori di eventi personalizzati .

Esempio

L' estensione ufficiale Resize Images fornisce un hook asincrono pubblicando su Eventarc dopo aver ridimensionato un'immagine.

Ganci sincroni

Quando desideri fornire agli utenti un hook che deve essere completato con successo affinché una delle funzioni dell'estensione funzioni, utilizza hook sincroni .

Un hook sincrono chiama una Cloud Function richiamabile 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 di estensione.

Per esporre un hook sincrono:

1. Aggiungi un parametro alla tua estensione che consenta agli utenti di configurare l'estensione con l'URL della loro Cloud Function personalizzata. Per 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
   

2. Nel punto dell'estensione in cui desideri esporre l'hook, chiama la funzione utilizzando il suo URL. Per esempio:

   const functions = require('firebase-functions');
   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. Documenta tutti gli hook che rendi disponibili nel file PREINSTALL o POSTINSTALL.

   Per ciascun gancio, documentare quanto segue:

   • Lo scopo previsto
   • Il punto nella logica della tua estensione in cui viene eseguito
   • I suoi input e output attesi
   • Le condizioni (o opzioni) per la sua esecuzione

   Inoltre, avvisa gli utenti di non eseguire alcuna azione nella funzione hook che potrebbe attivare la stessa estensione, risultando in un ciclo infinito.

Esempio

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