Gestisci gli eventi del ciclo di vita delle estensioni

La tua estensione può includere funzioni Cloud Tasks che vengono attivate quando un'istanza di estensione attraversa uno dei seguenti eventi del ciclo di vita:

È installata un'istanza dell'estensione
Un'istanza dell'estensione viene aggiornata a una nuova versione
La configurazione di un'istanza di estensione viene modificata

Uno dei casi d'uso più importanti di questa funzionalità è il riempimento dei dati. Ad esempio, supponiamo che tu stia creando un'estensione che genera anteprime in miniatura delle immagini caricate in un bucket Cloud Storage. Il lavoro principale dell'estensione verrà svolto in una funzione attivata dall'evento onFinalize Cloud Storage. Tuttavia, verranno elaborate solo le immagini caricate dopo l'installazione dell'estensione. Se includi nella tua estensione una funzione attivata dall'evento del ciclo di vita onInstall, puoi anche generare anteprime in miniatura di eventuali immagini esistenti quando l'estensione viene installata.

Altri casi d'uso dei trigger di eventi del ciclo di vita includono:

Automatizza la configurazione post-installazione (creazione di record di database, indicizzazione e così via)
Se devi pubblicare modifiche incompatibili con le versioni precedenti, esegui automaticamente la migrazione dei dati durante l'aggiornamento

Gestori di eventi del ciclo di vita di breve durata

Se la tua attività può essere eseguita completamente entro la durata Cloud Functions massima (9 minuti utilizzando l'API di prima generazione), puoi scrivere il gestore di eventi del ciclo di vita come una singola funzione che viene attivata dall'evento onDispatch della coda delle attività:

export const myTaskFunction = functions.tasks.taskQueue()
  .onDispatch(async () => {
    // Complete your lifecycle event handling task.
    // ...

    // When processing is complete, report status to the user (see below).
  });

Quindi, nel file extension.yaml dell'estensione:

Registra la tua funzione come risorsa di estensione con il set di proprietà taskQueueTrigger. Se imposti taskQueueTrigger sulla mappa vuota ({}), l'estensione eseguirà il provisioning di una coda Cloud Tasks utilizzando le impostazioni predefinite. Puoi anche ottimizzare queste impostazioni.

resources:
  - name: myTaskFunction
    type: firebaseextensions.v1beta.function
    description: >-
      Describe the task performed when the function is triggered by a lifecycle
      event
    properties:
      location: ${LOCATION}
      taskQueueTrigger: {}

Registra la tua funzione come gestore di uno o più eventi del ciclo di vita:
```
resources:
  - ...
lifecycleEvents:
  onInstall:
    function: myTaskFunction
    processingMessage: Resizing your existing images
  onUpdate:
    function: myOtherTaskFunction
    processingMessage: Setting up your extension
  onConfigure:
    function: myOtherTaskFunction
    processingMessage: Setting up your extension
```
Puoi registrare funzioni per uno qualsiasi dei seguenti eventi: onInstall, onUpdate e onConfigure. Tutti questi eventi sono facoltativi.

Nota :il messaggio che specifichi qui viene impostato automaticamente come stato di elaborazione dell'estensione nella console Firebase quando viene attivata la funzione. Per aggiornare o cancellare lo stato di elaborazione al termine del lavoro della funzione, chiama setProcessingState() come descritto nella sezione Stato del report.

Consigliato: se l'attività di elaborazione non è necessaria per il funzionamento dell'estensione, aggiungi un parametro configurato dall'utente che consenta agli utenti di scegliere se attivarlo.

Ad esempio, aggiungi un parametro come il seguente:

params:
  - param: DO_BACKFILL
    label: Backfill existing images
    description: >
      Should existing, unresized images in the Storage bucket be resized as well?
    type: select
    options:
      - label: Yes
        value: true
      - label: No
        value: false

E nella funzione, se il parametro è impostato su false, esci in anticipo:

export const myTaskFunction = functions.tasks.taskQueue()
  .onDispatch(async () => {
    if (!process.env.DO_BACKFILL) {
      await runtime.setProcessingState(
        "PROCESSING_COMPLETE",
        "Existing images were not resized."
      );
      return;
    }
    // Complete your lifecycle event handling task.
    // ...
  });

Eseguire attività di lunga durata

Se l'attività non può essere completata entro la durata massima di Cloud Functions, dividi l'attività in attività secondarie ed esegui ogni attività secondaria in sequenza mettendo in coda i job con il metodo TaskQueue.enqueue() dell'SDK Admin.

Ad esempio, supponiamo di voler eseguire il backfill dei dati Cloud Firestore. Puoi dividere la raccolta di documenti in blocchi utilizzando i cursori di query. Dopo aver elaborato un blocco, avanza l'offset iniziale e metti in coda un'altra chiamata di funzione come mostrato di seguito:

import { getFirestore } from "firebase-admin/firestore";
import { getFunctions } from "firebase-admin/functions";

exports.backfilldata = functions.tasks.taskQueue().onDispatch(async (data) => {
  // When a lifecycle event triggers this function, it doesn't pass any data,
  // so an undefined offset indicates we're on our first invocation and should
  // start at offset 0. On subsequent invocations, we'll pass an explicit
  // offset.
  const offset = data["offset"] ?? 0;

  // Get a batch of documents, beginning at the offset.
  const snapshot = await getFirestore()
    .collection(process.env.COLLECTION_PATH)
    .startAt(offset)
    .limit(DOCS_PER_BACKFILL)
    .get();
  // Process each document in the batch.
  const processed = await Promise.allSettled(
    snapshot.docs.map(async (documentSnapshot) => {
      // Perform the processing.
    })
  );

  // If we processed a full batch, there are probably more documents to
  // process, so enqueue another invocation of this function, specifying
  // the offset to start with.
  //
  // If we processed less than a full batch, we're done.
  if (processed.length == DOCS_PER_BACKFILL) {
    const queue = getFunctions().taskQueue(
      "backfilldata",
      process.env.EXT_INSTANCE_ID
    );
    await queue.enqueue({
      offset: offset + DOCS_PER_BACKFILL,
    });
  } else {
      // Processing is complete. Report status to the user (see below).
  }
});

Aggiungi la funzione a extension.yaml come descritto nella sezione precedente.

Stato della segnalazione

Al termine di tutte le funzioni di elaborazione, correttamente o con un errore, segnala lo stato dell'attività utilizzando i metodi di runtime dell'estensione dell'SDK Admin. Gli utenti possono visualizzare questo stato nella pagina dei dettagli dell'estensione nella console Firebase.

Completamento riuscito ed errori non irreversibili

Per segnalare il completamento riuscito e gli errori non irreversibili (errori che non rendono l'estensione non funzionante), utilizza il metodo di runtime dell'estensione setProcessingState() dell'SDK Admin:

import { getExtensions } from "firebase-admin/extensions";

// ...

getExtensions().runtime().setProcessingState(processingState, message);

Puoi impostare i seguenti stati:

Stati non irreversibili
`PROCESSING_COMPLETE`	Utilizzalo per segnalare il completamento di un'attività. Esempio: getExtensions().runtime().setProcessingState( "PROCESSING_COMPLETE", `Backfill complete. Successfully processed ${numSuccess} documents.` );
`PROCESSING_WARNING`	Utilizzare per segnalare la riuscita parziale. Esempio: getExtensions().runtime().setProcessingState( "PROCESSING_WARNING", `Backfill complete. ${numSuccess} documents processed successfully.` + ` ${numFailed} documents failed to process. ${listOfErrors}.` + ` ${instructionsToFixTheProblem}` );
`PROCESSING_FAILED`	Utilizzalo per segnalare errori che impediscono il completamento dell'attività, ma non rendono inutilizzabile l'estensione. Esempio: getExtensions().runtime().setProcessingState( "PROCESSING_FAILED", `Backfill failed. ${errorMsg} ${optionalInstructionsToFixTheProblem}.` ); Per segnalare errori che rendono l'estensione inutilizzabile, chiama `setFatalError()`.
`NONE`	Utilizza questa opzione per cancellare lo stato dell'attività. Puoi utilizzare questa opzione per cancellare il messaggio di stato dalla console (ad esempio, dopo un certo periodo di tempo trascorso dall'impostazione di `PROCESSING_COMPLETE`). Esempio: getExtensions().runtime().setProcessingState("NONE");

Errori irreversibili

Se si verifica un errore che impedisce il funzionamento dell'estensione, ad esempio un'attività di configurazione obbligatoria non riuscita, segnala l'errore irreversibile con setFatalError():

import { getExtensions } from "firebase-admin/extensions";

// ...

getExtensions().runtime().setFatalError(`Post-installation setup failed. ${errorMessage}`);

Ottimizzazione della coda di attività

Se imposti la proprietà taskQueueTrigger su {}, la tua estensione eseguirà il provisioning di una coda di Cloud Tasks con le impostazioni predefinite quando viene installata un'istanza dell'estensione. In alternativa, puoi ottimizzare i limiti di concorrenza e il comportamento di ripetizione della coda di attività fornendo valori specifici:

resources:
  - name: myTaskFunction
    type: firebaseextensions.v1beta.function
    description: >-
      Perform a task when triggered by a lifecycle event
    properties:
      location: ${LOCATION}
      taskQueueTrigger:
        rateLimits:
          maxConcurrentDispatches: 1000
          maxDispatchesPerSecond: 500
        retryConfig:
          maxAttempts: 100  # Warning: setting this too low can prevent the function from running
          minBackoffSeconds: 0.1
          maxBackoffSeconds: 3600
          maxDoublings: 16
lifecycleEvents:
  onInstall: 
    function: myTaskFunction
    processingMessage: Resizing your existing images
  onUpdate:
    function: myTaskFunction
    processingMessage: Setting up your extension
  onConfigure:
    function: myOtherTaskFunction
    processingMessage: Setting up your extension

Per informazioni dettagliate su questi parametri, consulta Configurare le code Cloud Tasks nella documentazione di Google Cloud.

Non tentare di specificare i parametri della coda di attività trasmettendoli a taskQueue(). Queste impostazioni vengono ignorate a favore della configurazione in extension.yaml e delle impostazioni di configurazione predefinite.

Ad esempio, questo non funzionerà:

export const myBrokenTaskFunction = functions.tasks
  // DON'T DO THIS IN AN EXTENSION! THESE SETTINGS ARE IGNORED.
  .taskQueue({
    retryConfig: {
      maxAttempts: 5,
      minBackoffSeconds: 60,
    },
    rateLimits: {
      maxConcurrentDispatches: 1000,
      maxDispatchesPerSecond: 10,
    },
  })
  .onDispatch(
    // ...
  );

La proprietà taskQueueTrigger in extension.yaml è l'unico modo per configurare le code di attività di un'estensione.

Esempi

Le estensioni ufficiali storage-resize-images, firestore-bigquery-export e firestore-translate-text utilizzano tutte i gestori di eventi del ciclo di vita per eseguire il backfill dei dati.