Votre extension peut inclure Cloud Tasks fonctions qui se déclenche lorsqu'une instance d'extension passe par l'une des conditions suivantes : les événements du cycle de vie:
- 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. Pour
Supposons que vous créiez une extension qui génère des aperçus de vignettes.
d'images importées dans un bucket Cloud Storage. Tâche principale de votre extension
est effectuée dans une fonction déclenchée par l'événement Cloud Storage onFinalize
.
Toutefois, seules les images importées après l'installation de l'extension seront
traités. En incluant dans votre extension une fonction déclenchée par
onInstall
, vous pouvez aussi générer des vignettes des aperçus
des images existantes lors de l'installation de l'extension.
Voici d'autres cas d'utilisation des déclencheurs d'événements de cycle de vie:
- Automatiser la configuration post-installation (création d'enregistrements de base de données, indexation, etc.)
- Si vous devez publier des modifications incompatibles avec les versions antérieures, migrez automatiquement données lors de la mise à jour
Gestionnaires d'événements de cycle de vie de courte durée
Si votre tâche peut s'exécuter entièrement dans le
durée maximale de Cloud Functions (9
minutes à l'aide de l'API de première génération), vous pouvez écrire votre événement de cycle de vie
comme une fonction unique qui se déclenche sur l'événement onDispatch
de la file d'attente de 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
taskQueueTrigger
. définie. 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 ajuster 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 les événements suivants:
onInstall
,onUpdate
etonConfigure
. Tous ces événements sont facultatifs.Recommandé: Si la tâche de traitement n'est pas nécessaire pour que votre extension fonctionne, ajoutez un paramètre configuré par l'utilisateur qui laisse aux utilisateurs le choix de l'activer ou non.
Par exemple, ajoutez un paramètre semblable à 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
Dans votre fonction, si le paramètre est défini sur
false
, quittez-la 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écuter des tâches de longue durée
Si votre tâche ne peut pas être terminée dans la durée maximale de Cloud Functions, divisez-la en sous-tâches et exécutez chaque sous-tâche dans l'ordre en mettant en file d'attente des tâches avec la méthode TaskQueue.enqueue()
du SDK Admin.
Par exemple, supposons que vous souhaitiez remplir des données Cloud Firestore. Vous pouvez diviser la collection de documents en fragments à l'aide de curseurs de requêtes ; Après le traitement d'un fragment, avancez le décalage de départ et mettez un autre en file d'attente 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 les
section précédente.
État des rapports
Lorsque toutes vos fonctions de traitement sont terminées, que ce soit avec succès ou avec une , signalez l'état de la tâche à l'aide de l'environnement d'exécution des extensions du SDK Admin méthodes. Les utilisateurs peuvent voir cet état sur la page d'informations de l'extension dans le Console Firebase.
Exécution réussie et erreurs non fatales
Pour signaler les erreurs d'exécution réussie et les erreurs non fatales (les erreurs qui n'entraînent pas
dans un état non fonctionnel), utilisez la bibliothèque
Méthode d'exécution de l'extension setProcessingState()
:
import { getExtensions } from "firebase-admin/extensions";
// ...
getExtensions().runtime().setProcessingState(processingState, message);
Vous pouvez définir les états suivants:
États non fatals | |
---|---|
PROCESSING_COMPLETE |
Permet de signaler l'achèvement des tâches. Exemple : getExtensions().runtime().setProcessingState( "PROCESSING_COMPLETE", `Backfill complete. Successfully processed ${numSuccess} documents.` ); |
PROCESSING_WARNING |
Permet d'indiquer une réussite partielle. Exemple : getExtensions().runtime().setProcessingState( "PROCESSING_WARNING", `Backfill complete. ${numSuccess} documents processed successfully.` + ` ${numFailed} documents failed to process. ${listOfErrors}.` + ` ${instructionsToFixTheProblem}` ); |
PROCESSING_FAILED |
À utiliser pour signaler les erreurs qui empêchent l'exécution de la tâche, mais qui ne rendent pas l'extension inutilisable. Exemple : getExtensions().runtime().setProcessingState( "PROCESSING_FAILED", `Backfill failed. ${errorMsg} ${optionalInstructionsToFixTheProblem}.` ); Pour signaler les erreurs qui ne rendent pas l'extension inutilisable, appelez
|
NONE |
Permet d'effacer l'état de la tâche. Vous pouvez éventuellement
l'utiliser pour effacer
le message d'état de la console (par exemple, après un certain nombre
temps écoulé depuis la configuration de getExtensions().runtime().setProcessingState("NONE"); |
Erreurs fatales
Si une erreur empêche l'extension de fonctionner, par exemple
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égler la file d'attente de tâches
Si vous définissez la propriété taskQueueTrigger
sur {}
, votre extension provisionnera une file d'attente Cloud Tasks avec les paramètres par défaut lorsqu'une instance d'extension sera installée. Vous pouvez également ajuster la 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 la section Configurer des files d'attente Cloud Tasks. dans la documentation Google Cloud pour en savoir plus sur ces paramètres.
N'essayez pas de spécifier des paramètres de file d'attente de tâches en les transmettant à taskQueue()
.
Ces paramètres sont ignorés au profit de la configuration dans extension.yaml
et
les valeurs de configuration par défaut.
Par exemple, la solution ci-dessous ne fonctionnera pas :
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 propriété taskQueueTrigger
dans extension.yaml
est le seul moyen de configurer les files d'attente de tâches d'une extension.
Exemples
Le storage-resize-images
officiel,
firestore-bigquery-export
,
et firestore-translate-text
les extensions utilisent toutes des gestionnaires d'événements de cycle de vie pour remplir les données.