Déclencheurs Firestore (2e génération)
Vous pouvez configurer vos fonctions Cloud afin qu'elles soient déclenchées par des événements dans une base de données Firestore. Une fois déclenchée, votre fonction peut lire et mettre à jour une base de données Firestore en réponse à ces événements via les API et bibliothèques clientes Firestore.
Dans un cycle de vie typique, une fonction Firestore effectue les opérations suivantes :
Attend les modifications apportées à un document donné.
Se déclenche lorsqu'un événement se produit et exécute ses tâches.
Reçoit un objet de données contenant un instantané du document affecté. Pour les événements
write
ouupdate
, l'objet de données contient des instantanés représentant l'état du document avant et après l'événement déclencheur.
Types d'événement
Firestore accepte les événements create
, update
, delete
et write
. L'événement write
englobe toutes les modifications apportées à un document.
Type d'événement | Déclencheur |
---|---|
google.cloud.firestore.document.v1.created (par défaut) |
Déclenché lorsqu'un document est écrit pour la première fois. |
google.cloud.firestore.document.v1.updated |
Déclenché lorsqu'un document existe déjà et qu'une valeur y a été modifiée. |
google.cloud.firestore.document.v1.deleted |
Déclenché lorsqu'un document contenant des données est supprimé. |
google.cloud.firestore.document.v1.written |
Déclenché lorsqu'un document est créé, mis à jour ou supprimé. |
Les caractères génériques sont écrits dans les déclencheurs à l'aide d'accolades, comme suit : "projects/YOUR_PROJECT_ID/databases/(default)/documents/collection/{document_wildcard}"
Spécifier le chemin d'accès aux documents
Pour déclencher votre fonction, spécifiez un chemin d'accès de document à écouter. Le chemin d'accès aux documents doit se trouver dans le même projet Google Cloud que la fonction.
Voici quelques exemples de chemins d'accès aux documents valides :
users/marie
: déclencheur valide. Surveille un seul document,/users/marie
.users/{username}
: déclencheur valide. Surveille tous les documents d'utilisateur. Les caractères génériques permettent de surveiller tous les documents de la collection.users/{username}/addresses
: déclencheur non valide. Renvoie à la sous-collectionaddresses
, et non à un document.users/{username}/addresses/home
: déclencheur valide. Surveille le document d'adresses personnelles de tous les utilisateurs.users/{username}/addresses/{addressId}
: déclencheur valide. Surveille tous les documents d'adresses.users/{user=**}
: déclencheur valide. Surveille tous les documents d'utilisateur et tous les documents des sous-collections associées à chaque document d'utilisateur, telles que/users/userID/address/home
ou/users/userID/phone/work
.
Caractères génériques et paramètres
Si vous ne connaissez pas le nom du document spécifique que vous souhaitez surveiller, utilisez un caractère générique ({wildcard}
) à la place de l'ID du document :
users/{username}
: écoute les modifications apportées à tous les documents d'utilisateur.
Dans cet exemple, lorsqu'un champ de n'importe quel document de la collection users
est modifié, il correspond au caractère générique {username}
.
Si un document de la collection users
comporte des sous-collections et qu'un champ de l'une d'entre elles est modifié, le caractère générique {username}
n'est pas déclenché. Si votre objectif est de répondre aux événements dans les sous-collections, utilisez le caractère générique multisegment {username=**}
.
Les correspondances de caractères génériques sont extraites du chemin du document. Vous pouvez définir autant de caractères génériques que vous le souhaitez pour remplacer les ID explicites de collection ou de document. Vous ne pouvez utiliser qu'un seul caractère générique multisegment, tel que {username=**}
.
Structures d'événements
Ce déclencheur appelle votre fonction avec un événement semblable à celui-ci :
{ "oldValue": { // Update and Delete operations only A Document object containing a pre-operation document snapshot }, "updateMask": { // Update operations only A DocumentMask object that lists changed fields. }, "value": { // A Document object containing a post-operation document snapshot } }
Chaque objet Document
contient un ou plusieurs objets Value
. Consultez la documentation de référence de l'objet Value
pour obtenir plus d'informations sur les types de valeurs. C'est particulièrement utile si vous utilisez un langage saisi, tel que Go, pour écrire vos fonctions.
Examples
Les exemples suivants montrent comment écrire des fonctions qui répondent à un déclencheur Firestore.
Avant de commencer
- Connectez-vous à votre compte Google Cloud. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Vérifiez que la facturation est activée pour votre projet Google Cloud.
-
Activer les API Cloud Functions, Cloud Build, Artifact Registry, Eventarc, Logging, Pub/Sub, and Cloud Run.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Vérifiez que la facturation est activée pour votre projet Google Cloud.
-
Activer les API Cloud Functions, Cloud Build, Artifact Registry, Eventarc, Logging, Pub/Sub, and Cloud Run.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Préparez votre environnement de développement.
Node.js
Python
Go
Java
C#
Ruby
PHP
Si la gcloud CLI est déjà installée, mettez-le à jour en exécutant la commande suivante :
gcloud components update
Configurer votre base de données Cloud Firestore
Vous devez disposer d'une base de données Firestore pour tester les exemples de ce document. Celle-ci doit être en place avant de déployer vos fonctions. Si vous ne disposez pas encore d'une base de données Firestore, créez-en une comme suit :
Accédez à la page Données Firestore.
Cliquez sur Sélectionner le mode natif.
Choisissez la région (emplacement) où doit être située votre base de données. Ce choix est définitif.
Cliquez sur Créer une base de données.
Le modèle de données Firestore est constitué de collections contenant des documents. Chaque document contient un ensemble de paires clé/valeur.
Les fonctions que vous créez dans ce tutoriel sont déclenchées lorsque vous apportez des modifications à un document au sein d'une collection spécifiée.
Exemple 1 : Fonction Hello Firestore
L'exemple de fonction Cloud suivant imprime les champs d'un événement déclencheur Firestore :
Node.js
Utilisez protobufjs pour décoder les données d'événement. Incluez la propriété google.events.cloud.firestore.v1
data.proto
dans votre source.
Python
Go
Java
C#
Déployer la fonction Hello Firestore
Si ce n'est pas déjà fait, configurez votre base de données Firestore.
Pour déployer la fonction Hello Firestore avec un déclencheur Firestore, exécutez la commande suivante dans le répertoire contenant l'exemple de code (ou, dans le cas de Java, le fichier
pom.xml
) :gcloud functions deploy FUNCTION_NAME \ --gen2 \ --runtime=RUNTIME \ --region=REGION \ --trigger-location=TRIGGER REGION \ --source=. \ --entry-point=ENTRY_POINT \ --trigger-event-filters=type=google.cloud.firestore.document.v1.written \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='users/{username}'
Remplacez les éléments suivants :
FUNCTION_NAME
: nom de votre fonction déployéeRUNTIME
: environnement d'exécution de langage utilisé par votre fonctionREGION
: région dans laquelle déployer votre fonctionTRIGGER_REGION
: emplacement du déclencheur, qui doit correspondre à la région de la base de données Firestore.ENTRY_POINT
: point d'entrée de votre fonction dans votre code source. Il s'agit du code qui est exécuté lors de l'exécution de votre fonction.
Laissez les autres champs inchangés :
--trigger-event-filters=type=google.cloud.firestore.document.v1.written
spécifie que la fonction est déclenchée lors de la création, de la mise à jour ou de la suppression d'un document, selon le type d'événementgoogle.cloud.firestore.document.v1.written
.--trigger-event-filters=database='(default)'
spécifie la base de données Firebase. Pour spécifier le nom de la base de données par défaut, utilisez(default)
.--trigger-event-filters-path-pattern=document='users/{username}'
fournit le format de chemin d'accès des documents à surveiller pour y détecter des modifications pertinentes. Ce format de chemin d'accès indique que tous les documents de la collectionusers
doivent être surveillés. Pour en savoir plus, consultez la page Comprendre les formats de chemin d'accès.
Tester la fonction Hello Firestore
Pour tester la fonction Hello Firestore, configurez une collection appelée users
dans votre base de données Firestore :
Sur la page des données Firestore, cliquez sur Commencer une collection.
Spécifiez
users
comme ID de collection.Pour commencer à ajouter le premier document de la collection, sous Ajouter le premier document, acceptez l'ID de document généré automatiquement.
Ajoutez au moins un champ pour le document, en spécifiant un nom et une valeur. Dans cet exemple, nous ajoutons un champ nommé "username" dont la valeur est "rowan".
Lorsque vous avez terminé, cliquez sur Save (Enregistrer).
Cette action crée un document, ce qui va donc déclencher votre fonction.
Pour vérifier que votre fonction a été déclenchée, cliquez sur le nom de la fonction associée dans la page de présentation de Cloud Functions, dans la console Google Cloud, pour afficher la page Détails de la fonction.
Accédez à l'onglet Journaux et recherchez cette chaîne :
Function triggered by change to: //firestore.googleapis.com/projects/your-project-id/databases/(default)'
Exemple 2 : Fonction de conversion en majuscules
Cet exemple récupère la valeur ajoutée par l'utilisateur, convertit la chaîne à cet emplacement en majuscules, et remplace la valeur par la chaîne en majuscules :
Node.js
Utilisez protobufjs pour décoder les données d'événement. Incluez la propriété google.events.cloud.firestore.v1
data.proto
dans votre source.
Python
Go
Java
C#
Déployer la fonction de conversion en majuscules
Si ce n'est pas déjà fait, configurez votre base de données Firestore.
Utilisez la commande suivante pour déployer une fonction qui est déclenchée par des événements d'écriture sur le document
companies/{CompanyId}
:gcloud functions deploy FUNCTION_NAME \ --gen2 \ --runtime=RUNTIME \ --trigger-location=TRIGGER REGION \ --region=REGION \ --source=. \ --entry-point=ENTRY_POINT \ --trigger-event-filters=type=google.cloud.firestore.document.v1.written \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='messages/{pushId}'
Remplacez les éléments suivants :
FUNCTION_NAME
: nom de votre fonction déployéeRUNTIME
: environnement d'exécution de langage utilisé par votre fonctionREGION
: région dans laquelle déployer votre fonctionTRIGGER_REGION
: emplacement du déclencheur, qui doit correspondre à la région de la base de données Firestore.ENTRY_POINT
: point d'entrée de votre fonction dans votre code source. Il s'agit du code qui est exécuté lors de l'exécution de votre fonction.
Laissez les autres champs inchangés :
--trigger-event-filters=type=google.cloud.firestore.document.v1.written
spécifie que la fonction est déclenchée lors de la création, de la mise à jour ou de la suppression d'un document, selon le type d'événementgoogle.cloud.firestore.document.v1.written
.--trigger-event-filters=database='(default)'
spécifie la base de données Firestore. Pour spécifier le nom de la base de données par défaut, utilisez(default)
.--trigger-event-filters-path-pattern=document='messages/{pushId}'
fournit le format de chemin d'accès des documents à surveiller pour y détecter des modifications pertinentes. Ce format de chemin d'accès indique que tous les documents de la collectionmessages
doivent être surveillés. Pour en savoir plus, consultez la page Comprendre les formats de chemin d'accès.
Tester la fonction de conversion en majuscules
Pour tester la fonction de conversion en majuscules que vous venez de déployer, configurez une collection appelée messages
dans votre base de données Firestore :
Accédez à la page des données Firestore.
Cliquez sur Commencer une collection.
Spécifiez
messages
comme ID de collection.Pour commencer à ajouter le premier document de la collection, sous Ajouter le premier document, acceptez l'ID de document généré automatiquement.
Pour déclencher votre fonction déployée, ajoutez un document dont le nom de champ est "original", la valeur de ce champ étant un mot minuscule, par exemple :
Lorsque vous enregistrez le document, le mot en minuscules du champ de valeur est converti en majuscules.
Si vous modifiez ensuite la valeur du champ pour y faire figurer des lettres minuscules, la fonction va à nouveau être déclenchée, ce qui va convertir toutes les lettres minuscules en majuscules.
Limites
- L'ordre n'est pas garanti. Les modifications rapides peuvent déclencher des appels de fonctions dans un ordre inattendu.
- Bien que les événements soient diffusés une fois au moins, un même événement peut produire plusieurs appels de fonction. Évitez de dépendre de procédés dits "exactement une fois" et écrivez des fonctions idempotentes.
- Un déclencheur est associé à une seule base de données. Vous ne pouvez pas créer un déclencheur qui correspond à plusieurs bases de données.
- La suppression d'une base de données ne supprime pas automatiquement les déclencheurs de cette base de données. Le déclencheur cesse de diffuser des événements, mais continue d'exister jusqu'à ce que vous le supprimiez.