Créer des déclencheurs avec Firestore

Ce guide explique comment créer des déclencheurs pour les services et fonctions Cloud Run à partir d'événements Firestore.

Vous pouvez configurer vos services Cloud Run afin qu'ils soient déclenchés par des événements dans une base de données Firestore. Lorsqu'il est déclenché, votre service lit et met à 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, voici ce qui se passe lorsqu'un service Cloud Run est déclenché par des événements Firestore:

  1. Le service attend les modifications apportées à un document donné.

  2. Lorsqu'un changement se produit, le service est déclenché et exécute ses tâches.

  3. Le service reçoit un objet de données contenant un instantané du document concerné. Pour les événements write ou update, 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, par exemple : projects/YOUR_PROJECT_ID/databases/(default)/documents/collection/{document_wildcard}

Spécifier le chemin d'accès aux documents

Pour déclencher votre service, 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 le service.

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-collection addresses, 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 service avec un événement semblable à: 

{
    "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.

Avant de commencer

  1. Assurez-vous d'avoir configuré un nouveau projet pour Cloud Run, comme décrit sur la page de configuration.

  2. Activez les API Artifact Registry, Cloud Build, Cloud Run Admin, Eventarc, Firestore Cloud Logging et Pub/Sub:

    Activer les API

Rôles requis

  1. Si vous êtes le créateur du projet, vous disposez du rôle de base Propriétaire (roles/owner). Par défaut, ce rôle Identity and Access Management (IAM) inclut les autorisations nécessaires pour accéder à la plupart des ressources Google Cloud. Vous pouvez ignorer cette étape.

    Si vous n'êtes pas le créateur du projet, les autorisations requises doivent être accordées au compte principal approprié sur le projet. Par exemple, un compte principal peut être un compte Google (pour les utilisateurs finaux) ou un compte de service (pour les applications et les charges de travail de calcul). Pour en savoir plus, consultez la page Rôles et autorisations pour la destination de votre événement.

    Notez que par défaut, les autorisations Cloud Build incluent des autorisations permettant d'importer et de télécharger des artefacts Artifact Registry.

    Autorisations requises

    Pour obtenir les autorisations nécessaires pour configurer des déclencheurs Firestore, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet:

    Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

    Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

  2. Notez le compte de service Compute Engine par défaut, car vous allez l'associer à un déclencheur Eventarc pour représenter l'identité du déclencheur à des fins de test. Ce compte de service est créé automatiquement après l'activation ou l'utilisation d'un service Google Cloud qui utilise Compute Engine, avec le format d'adresse e-mail suivant :

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Remplacez PROJECT_NUMBER par votre numéro de projet Google Cloud. Vous pouvez trouver le numéro de votre projet sur la page Bienvenue de la console Google Cloud ou en exécutant la commande suivante :

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

    Pour les environnements de production, nous vous recommandons vivement de créer un compte de service et de lui attribuer un ou plusieurs rôles IAM contenant les autorisations minimales requises conformément au principe du moindre privilège.

  3. Par défaut, les services Cloud Run ne peuvent être appelés que par les propriétaires de projet, les éditeurs de projet, ainsi que par les administrateurs et les demandeurs Cloud Run. Vous pouvez contrôler l'accès service par service. Toutefois, à des fins de test, attribuez le rôle Demandeur Cloud Run (run.invoker) au compte de service Compute Engine sur le projet Google Cloud. Cela permet d'accorder le rôle sur tous les services et jobs Cloud Run d'un projet. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker

    Notez que si vous créez un déclencheur pour un service Cloud Run authentifié sans attribuer le rôle Demandeur Cloud Run, le déclencheur est bien créé et actif. Cependant, le déclencheur ne fonctionnera pas comme prévu et un message semblable au suivant s'affichera dans les journaux :

    The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
  4. Attribuez le rôle Récepteur d'événements Eventarc (roles/eventarc.eventReceiver) sur le projet au compte de service Compute Engine par défaut afin que le déclencheur Eventarc puisse recevoir des événements en provenance des fournisseurs d'événements 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver
  5. Si vous avez activé l'agent de service Cloud Pub/Sub le 8 avril 2021 ou à une date antérieure, attribuez le rôle Créateur de jetons du compte de service (roles/iam.serviceAccountTokenCreator) au compte de service pour accepter les requêtes push Pub/Sub authentifiées. Sinon, ce rôle est attribué par défaut : 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

Configurer votre base de données Cloud Firestore

Avant de déployer votre service, vous devez créer une base de données Firestore:

  1. Accédez à la page Données Firestore.

  2. Sélectionnez Créer une base de données.

  3. Cliquez sur Mode natif, puis sélectionnez Continuer.

  4. Dans le champ Nommez votre base de données, saisissez un ID de base de données, par exemple firestore-db.

  5. Dans Type d'emplacement, sélectionnez Région, puis choisissez la région où doit se trouver votre base de données. Ce choix est définitif.

  6. Laissez la section Règles de sécurité telle quelle.

  7. 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.

Créer des déclencheurs

Selon le type de service que vous déployez, vous pouvez:

Créer un déclencheur pour les services

Vous pouvez spécifier un déclencheur après avoir déployé un service.

Cliquez sur l'onglet pour obtenir des instructions concernant l'utilisation de l'outil de votre choix.

Console

  1. Déployez votre service Cloud Run à l'aide de conteneurs ou à partir d'une source.

  2. Dans la console Google Cloud, accédez à Cloud Run:

    Accédez à Cloud Run

  3. Dans la liste des services, cliquez sur un service existant.

  4. Sur la page d'informations du service, accédez à l'onglet Déclencheurs.

  5. Cliquez sur Ajouter un déclencheur, puis sélectionnez Déclencheur Firestore.

  6. Dans le volet Déclencheur Eventarc, modifiez les détails du déclencheur comme suit:

    1. Dans le champ Nom du déclencheur, saisissez un nom pour le déclencheur ou utilisez le nom par défaut.

    2. Sélectionnez un type de déclencheur dans la liste pour spécifier l'un des types de déclencheur suivants:

      • Sources Google pour spécifier des déclencheurs pour Pub/Sub, Cloud Storage, Firestore et d'autres fournisseurs d'événements Google.

      • Tiers pour intégrer des fournisseurs autres que Google qui proposent une source Eventarc. Pour en savoir plus, consultez la section Événements tiers dans Eventarc.

    3. Sélectionnez Firestore dans la liste Fournisseur d'événements pour sélectionner un produit qui fournit le type d'événement pour déclencher votre service. Pour obtenir la liste des fournisseurs d'événements, consultez la section Fournisseurs et destinations d'événements.

    4. Sélectionnez type=google.cloud.firestore.document.v1.created dans la liste Type d'événement. La configuration du déclencheur varie en fonction du type d'événement accepté: Pour en savoir plus, consultez la section Types d'événements.

    5. Dans la section "Filtres", sélectionnez une base de données, une opération et des valeurs d'attribut, ou utilisez les sélections par défaut.

    6. Si le champ Région est activé, sélectionnez un emplacement pour le déclencheur Eventarc. En général, l'emplacement d'un déclencheur Eventarc doit correspondre à celui de la ressource Google Cloud dont vous souhaitez surveiller les événements. Dans la plupart des scénarios, vous devez également déployer votre service dans la même région. Consultez la section Comprendre les emplacements Eventarc pour en savoir plus sur les emplacements des déclencheurs Eventarc.

    7. Dans le champ Compte de service, sélectionnez un compte de service. Les déclencheurs Eventarc sont associés à des comptes de service, destinés à être utilisés comme identité lors de l'appel de votre service. Le compte de service de votre déclencheur Eventarc doit être autorisé à appeler votre service. Par défaut, Cloud Run utilise le compte de service Compute Engine par défaut.

    8. Vous pouvez éventuellement spécifier le chemin d'URL du service auquel envoyer la requête entrante. Il s'agit du chemin relatif sur le service de destination auquel les événements du déclencheur doivent être envoyés. Par exemple: /, /route, route et route/subroute.

    9. Une fois les champs obligatoires renseignés, cliquez sur Enregistrer le déclencheur.

  7. Après avoir créé le déclencheur, vous pouvez vérifier son état en vous assurant qu'une coche s'affiche dans l'onglet Déclencheurs.

gcloud

  1. Déployez votre service Cloud Run à l'aide de conteneurs ou à partir d'une source.

  2. Exécutez la commande suivante pour créer un déclencheur qui filtre les événements:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=SERVICE  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.firestore.document.v1.created" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Remplacez :

    • TRIGGER_NAME par le nom de votre déclencheur.

    • EVENTARC_TRIGGER_LOCATION par l'emplacement du déclencheur Eventarc. En général, l'emplacement d'un déclencheur Eventarc doit correspondre à celui de la ressource Google Cloud dont vous souhaitez surveiller les événements. Dans la plupart des scénarios, vous devez également déployer votre service dans la même région. Pour en savoir plus, consultez la page Emplacements Eventarc.

    • SERVICE par le nom du service que vous déployez.

    • REGION par la région Cloud Run du service.

    • PROJECT_NUMBER par le numéro de votre projet Google Cloud Les déclencheurs Eventarc sont associés à des comptes de service, destinés à être utilisés comme identité lors de l'appel de votre service. Le compte de service de votre déclencheur Eventarc doit être autorisé à appeler votre service. Par défaut, Cloud Run utilise le compte de service Compute par défaut.

    • L'option event-filters spécifie les filtres d'événements que le déclencheur surveille. Les événements correspondant à tous les filtres event-filters déclenchent des appels vers votre service. Chaque déclencheur doit avoir un type d'événement compatible. Vous ne pouvez pas modifier le type de filtre d'événements après sa création. Pour modifier le type de filtre d'événement, vous devez créer un nouveau déclencheur et supprimer l'ancien. Facultatif : vous pouvez répéter l'option --event-filters avec un filtre compatible au format ATTRIBUTE=VALUE pour ajouter d'autres filtres.

Créer un déclencheur pour les fonctions

Cliquez sur l'onglet pour obtenir des instructions concernant l'utilisation de l'outil de votre choix.

Console

Lorsque vous utilisez la console Google Cloud pour créer une fonction, vous pouvez également ajouter un déclencheur à votre fonction. Pour créer un déclencheur pour votre fonction, procédez comme suit:

  1. Dans la console Google Cloud, accédez à Cloud Run :

    Accédez à Cloud Run

  2. Cliquez sur Écrire une fonction, puis saisissez les informations sur la fonction. Pour en savoir plus sur la configuration des fonctions lors du déploiement, consultez la section Déployer des fonctions.

  3. Dans la section Déclencheur, cliquez sur Ajouter un déclencheur.

  4. Sélectionnez Déclencheur Firestore.

  5. Dans le volet Déclencheur Eventarc, modifiez les détails du déclencheur comme suit:

    1. Saisissez un nom pour le déclencheur dans le champ Trigger name (Nom du déclencheur) ou utilisez le nom par défaut.

    2. Sélectionnez un type de déclencheur dans la liste pour spécifier l'un des types de déclencheur suivants:

      • Sources Google pour spécifier des déclencheurs pour Pub/Sub, Cloud Storage, Firestore et d'autres fournisseurs d'événements Google.

      • Tiers pour intégrer des fournisseurs autres que Google qui proposent une source Eventarc. Pour en savoir plus, consultez la section Événements tiers dans Eventarc.

    3. Sélectionnez Firestore dans la liste Fournisseur d'événements pour sélectionner un produit qui fournit le type d'événement pour déclencher votre fonction. Pour obtenir la liste des fournisseurs d'événements, consultez la section Fournisseurs et destinations d'événements.

    4. Sélectionnez type=google.cloud.firestore.document.v1.created dans la liste Type d'événement. La configuration du déclencheur varie en fonction du type d'événement accepté: Pour en savoir plus, consultez la section Types d'événements.

    5. Dans la section "Filtres", sélectionnez une base de données, une opération et des valeurs d'attribut, ou utilisez les sélections par défaut.

    6. Si le champ Région est activé, sélectionnez un emplacement pour le déclencheur Eventarc. En général, l'emplacement d'un déclencheur Eventarc doit correspondre à celui de la ressource Google Cloud dont vous souhaitez surveiller les événements. Dans la plupart des scénarios, vous devez également déployer votre fonction dans la même région. Consultez la section Comprendre les emplacements Eventarc pour en savoir plus sur les emplacements des déclencheurs Eventarc.

    7. Dans le champ Compte de service, sélectionnez un compte de service. Les déclencheurs Eventarc sont associés à des comptes de service, destinés à être utilisés comme identité lors de l'appel de votre fonction. Le compte de service de votre déclencheur Eventarc doit être autorisé à appeler votre fonction. Par défaut, Cloud Run utilise le compte de service Compute Engine par défaut.

    8. Vous pouvez éventuellement spécifier le chemin d'URL du service auquel envoyer la requête entrante. Il s'agit du chemin relatif sur le service de destination auquel les événements du déclencheur doivent être envoyés. Par exemple: /, /route, route et route/subroute.

  6. Une fois les champs obligatoires renseignés, cliquez sur Enregistrer le déclencheur.

gcloud

Lorsque vous créez une fonction à l'aide de gcloud CLI, vous devez d'abord deploy, puis créer un déclencheur. Pour créer un déclencheur pour votre fonction, procédez comme suit:

  1. Pour déployer votre fonction, exécutez la commande suivante dans le répertoire contenant l'exemple de code:

    gcloud beta run deploy FUNCTION \
        --source . \
        --function FUNCTION_ENTRYPOINT \
        --base-image BASE_IMAGE_ID \
        --region REGION

    Remplacez :

    • FUNCTION par le nom de la fonction que vous déployez. Vous pouvez omettre ce paramètre, mais dans ce cas le nom vous sera demandé.

    • FUNCTION_ENTRYPOINT par le point d'entrée de votre fonction dans votre code source. Il s'agit du code exécuté par Cloud Run lors de l'exécution de votre fonction. La valeur de cette option doit être un nom de fonction ou un nom de classe complet qui existe dans votre code source.

    • BASE_IMAGE_ID par l'environnement d'image de base de votre fonction. Pour en savoir plus sur les images de base et les packages inclus dans chaque image, consultez la section Images de base des environnements d'exécution.

    • REGION par la région Google Cloud dans laquelle vous souhaitez déployer votre fonction. Par exemple, us-central1.

  2. Exécutez la commande suivante pour créer un déclencheur qui filtre les événements:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=FUNCTION  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.firestore.document.v1.created" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Remplacez :

    • TRIGGER_NAME par le nom de votre déclencheur.

    • EVENTARC_TRIGGER_LOCATION par l'emplacement du déclencheur Eventarc. En général, l'emplacement d'un déclencheur Eventarc doit correspondre à celui de la ressource Google Cloud dont vous souhaitez surveiller les événements. Dans la plupart des scénarios, vous devez également déployer votre fonction dans la même région. Pour en savoir plus, consultez la page Emplacements Eventarc.

    • FUNCTION par le nom de la fonction que vous déployez.

    • REGION par la région Cloud Run de la fonction.

    • PROJECT_NUMBER par le numéro de votre projet Google Cloud Les déclencheurs Eventarc sont associés à des comptes de service, destinés à être utilisés comme identité lors de l'appel de votre fonction. Le compte de service de votre déclencheur Eventarc doit être autorisé à appeler votre fonction. Par défaut, Cloud Run utilise le compte de service Compute par défaut.

    • L'option event-filters spécifie les filtres d'événements que le déclencheur surveille. Un événement correspondant à tous les filtres event-filters déclenche des appels vers votre fonction. Chaque déclencheur doit avoir un type d'événement compatible. Vous ne pouvez pas modifier le type de filtre d'événements après sa création. Pour modifier le type de filtre d'événement, vous devez créer un nouveau déclencheur et supprimer l'ancien. Facultatif : vous pouvez répéter l'option --event-filters avec un filtre compatible au format ATTRIBUTE=VALUE pour ajouter d'autres filtres.

Étape suivante

  • Consultez des exemples de fonctions déclenchées lorsque vous apportez des modifications à un document au sein d'une collection spécifiée.