Votre extension peut inclure des fonctions Cloud Tasks qui se déclenchent lorsqu'une instance d'extension passe par l'un des événements de cycle de vie suivants :
- Une instance de l'extension est installée
- Une instance de l'extension est mise à jour vers une nouvelle version
- La configuration d'une instance d'extension est modifiée
L'un des cas d'utilisation les plus importants de cette fonctionnalité est le remplissage des données . Par exemple, supposons que vous créez une extension qui génère des aperçus miniatures des images importées dans un bucket Cloud Storage. Le travail principal de votre extension serait effectué dans une fonction déclenchée par l'événement onFinalize
Cloud Storage. Cependant, seules les images téléchargées après l'installation de l'extension seront traitées. En incluant dans votre extension une fonction déclenchée par l'événement de cycle de vie onInstall
, vous pouvez également générer des aperçus miniatures de toutes les images existantes lorsque l'extension est installée.
Voici d'autres cas d'utilisation des déclencheurs d'événements de cycle de vie :
- Automatisez la configuration post-installation (création d'enregistrements de base de données, indexation, etc.)
- Si vous devez publier des modifications rétrocompatibles, migrez automatiquement les données lors de la mise à jour
Gestionnaires d'événements à cycle de vie court
Si votre tâche peut s'exécuter complètement pendant la durée maximale de Cloud Functions (9 minutes à l'aide de l'API de première génération), vous pouvez écrire votre gestionnaire d'événements de cycle de vie en tant que fonction unique qui se déclenche sur l'événement onDispatch
de la file d'attente des tâches :
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).
});
Ensuite, dans le fichier extension.yaml
de votre extension, procédez comme suit :
Enregistrez votre fonction en tant que ressource d'extension avec le jeu de propriétés
taskQueueTrigger
. Si vous définisseztaskQueueTrigger
sur la carte vide ({}
), votre extension provisionnera une file d'attente Cloud Tasks à l'aide des paramètres par défaut ; vous pouvez éventuellement régler ces paramètres .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: {}
Enregistrez votre fonction en tant que gestionnaire pour un ou plusieurs événements de cycle de vie :
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
Vous pouvez enregistrer des fonctions pour l'un des événements suivants :
onInstall
,onUpdate
etonConfigure
. Tous ces événements sont facultatifs.Recommandé : si la tâche de traitement n'est pas requise pour que votre extension fonctionne, ajoutez un paramètre configuré par l'utilisateur qui permet aux utilisateurs de choisir de l'activer ou non.
Par exemple, ajoutez un paramètre comme celui-ci :
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
Et dans votre fonction, si le paramètre est défini sur
false
, quittez plus tôt :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. // ... });
Exécution de tâches de longue durée
Si votre tâche ne peut pas se terminer dans la durée maximale de Cloud Functions, divisez la tâche en sous-tâches et exécutez chaque sous-tâche dans l'ordre en mettant les tâches en file d'attente avec la méthode TaskQueue.enqueue()
du SDK Admin.
Par exemple, supposons que vous souhaitiez remplir les données Cloud Firestore. Vous pouvez diviser la collection de documents en morceaux à l'aide de curseurs de requête . Après avoir traité un morceau, avancez le décalage de départ et mettez en file d'attente une autre invocation de fonction comme indiqué ci-dessous :
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).
}
});
Ajoutez la fonction à votre extension.yaml
comme décrit dans la section précédente .
Statut de rapport
Lorsque toutes vos fonctions de traitement se terminent, avec succès ou avec une erreur, signalez l'état de la tâche à l'aide des méthodes d'exécution d'extension du SDK Admin. Les utilisateurs peuvent voir cet état sur la page des détails de l'extension dans la console Firebase.
Réussite et erreurs non fatales
Pour signaler l'achèvement réussi et les erreurs non fatales (erreurs qui ne mettent pas l'extension dans un état non fonctionnel), utilisez la méthode d'exécution d'extension setProcessingState()
du SDK Admin :
import { getExtensions } from "firebase-admin/extensions";
// ...
getExtensions().runtime().setProcessingState(processingState, message);
Vous pouvez définir les états suivants :
États non mortels | |
---|---|
PROCESSING_COMPLETE | À utiliser pour signaler l'achèvement réussi de la tâche. Exemple: getExtensions().runtime().setProcessingState( "PROCESSING_COMPLETE", `Backfill complete. Successfully processed ${numSuccess} documents.` ); |
PROCESSING_WARNING | Utilisez pour signaler un succès partiel. Exemple: getExtensions().runtime().setProcessingState( "PROCESSING_WARNING", `Backfill complete. ${numSuccess} documents processed successfully.` + ` ${numFailed} documents failed to process. ${listOfErrors}.` + ` ${instructionsToFixTheProblem}` ); |
PROCESSING_FAILED | Utilisez pour signaler les erreurs qui empêchent la tâche de se terminer, mais ne laissez pas l'extension inutilisable. Exemple: getExtensions().runtime().setProcessingState( "PROCESSING_FAILED", `Backfill failed. ${errorMsg} ${optionalInstructionsToFixTheProblem}.` ); Pour signaler les erreurs qui laissent l'extension inutilisable, appelez |
NONE | Utilisez pour effacer le statut de la tâche. Vous pouvez éventuellement l'utiliser pour effacer le message d'état de la console (par exemple, après qu'un certain temps se soit écoulé depuis la définition de getExtensions().runtime().setProcessingState("NONE"); |
Erreurs fatales
Si une erreur se produit qui empêche l'extension de fonctionner, par exemple, l'échec d'une tâche de configuration requise, signalez l'erreur fatale avec setFatalError()
:
import { getExtensions } from "firebase-admin/extensions";
// ...
getExtensions().runtime().setFatalError(`Post-installation setup failed. ${errorMessage}`);
Réglage de la file d'attente des tâches
Si vous définissez la propriété taskQueueTrigger
sur {}
, votre extension provisionne une file d'attente Cloud Tasks avec les paramètres par défaut lorsqu'une instance d'extension est installée. Vous pouvez également ajuster les limites de simultanéité de la file d'attente de tâches et le comportement des nouvelles tentatives en fournissant des valeurs spécifiques :
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
Consultez Configurer les files d'attente Cloud Tasks dans la documentation Google Cloud pour plus de détails sur ces paramètres.
Exemples
Les extensions officielles storage-resize-images
, firestore-bigquery-export
et firestore-translate-text
utilisent toutes des gestionnaires d'événements de cycle de vie pour remplir les données.