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