Router des événements Cloud Firestore vers Cloud Run

Un déclencheur Eventarc déclare votre intérêt pour un événement ou un ensemble d'événements spécifique. Vous pouvez configurer le routage d'événements en spécifiant des filtres pour le déclencheur, y compris la source de l'événement et le service Cloud Run cible.

Eventarc fournit des événements au destinataire d'événements au format CloudEvents via une requête HTTP.

Cloud Firestore est compatible avec le contexte d'authentification en tant qu'attribut d'extension au format CloudEvents. Lorsque vous créez un déclencheur, vous pouvez appliquer cet attribut de type événement pour filtrer les événements avec des informations d'authentification.

Ces instructions vous montrent comment configurer le routage d'événements vers votre service Cloud Run déclenché par un événementCloud Firestore direct. Pour en savoir plus, consultez la liste des événements directs compatibles.

Préparer la création d'un déclencheur

Avant de créer un déclencheur, procédez comme suit :

Console

  1. Dans la console Google Cloud, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

    Accéder au sélecteur de projet

  2. Activez les API Cloud Logging, Eventarc et Eventarc Publishing.

    Activer les API

  3. Le cas échéant, activez l'API associée aux événements directs. Par exemple, pour les événements Cloud Firestore , activez l'APICloud Firestore .

  4. Si vous n'en avez pas encore, créez un compte de service géré par l'utilisateur, puis accordez-lui les rôles et les autorisations nécessaires pour qu'Eventarc puisse gérer les événements de votre service cible.

    1. Dans la console Google Cloud, accédez à la page Créer un compte de service.

      Accéder à la page "Créer un compte de service"

    2. Sélectionnez votre projet.

    3. Dans le champ Nom du compte de service, saisissez un nom. La console Google Cloud remplit le champ ID du compte de service en fonction de ce nom.

      Dans le champ Description du compte de service, saisissez une description. Exemple : Service account for event trigger.

    4. Cliquez sur Créer et continuer.

    5. Pour fournir un accès approprié, dans la liste Sélectionner un rôle, sélectionnez les rôles IAM (Identity and Access Management) requis à attribuer à votre compte de service pour les appels authentifiés ou non authentifiés. Pour en savoir plus, consultez la page Rôles et autorisations pour les cibles Cloud Run.

      Pour ajouter des rôles supplémentaires, cliquez sur Ajouter un autre rôle et ajoutez chaque rôle supplémentaire.

    6. Cliquez sur Continuer.

    7. Pour terminer la création du compte, cliquez sur OK.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Activez les API Cloud Logging, Eventarc et Eventarc Publishing.

    gcloud services enable logging.googleapis.com \
  eventarc.googleapis.com \
  eventarcpublishing.googleapis.com

  3. Le cas échéant, activez l'API associée aux événements directs. Par exemple, pour les événements Cloud Firestore , activez firestore.googleapis.com.

  4. Si vous n'en avez pas encore, créez un compte de service géré par l'utilisateur, puis accordez-lui les rôles et les autorisations nécessaires pour qu'Eventarc puisse gérer les événements de votre service cible.

    1. Créez le compte de service :

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Remplacez SERVICE_ACCOUNT_NAME par le nom du compte de service. Il doit comporter entre 6 et 30 caractères alphanumériques pouvant inclure des minuscules et des tirets. Une fois le compte de service créé, vous ne pouvez pas en modifier le nom.

    2. Accordez les rôles ou autorisations Identity and Access Management (IAM) requis pour les appels authentifiés ou non authentifiés. Pour en savoir plus, consultez la page Rôles et autorisations pour les cibles Cloud Run.

Créer un déclencheur

Vous pouvez créer un déclencheur Eventarc à l'aide de Google Cloud CLI ou de la console Google Cloud.

Console

  1. Dans la console Google Cloud, accédez à la page Déclencheurs d'Eventarc.

    Accéder à la page "Déclencheurs"

  2. Cliquez sur Créer un déclencheur.
  3. Saisissez un nom de déclencheur

    Il s'agit de l'ID du déclencheur, qui doit commencer par une lettre. Il peut contenir jusqu'à 63 lettres minuscules, chiffres ou traits d'union.

  4. Pour le champ Type de déclencheur, sélectionnez Sources Google.
  5. Dans la liste Fournisseur d'événements, sélectionnez Cloud Firestore.

    Notez que le nom du fournisseur d'événements utilisé dans la documentation Google Cloud associée peut ne pas avoir le préfixe Cloud ou Google Cloud. Par exemple, sur la console, Memorystore pour Redis est appelé Google Cloud Memorystore pour Redis.

  6. Dans la liste Type d'événement, sélectionnez un type d'événement parmi les événements directs.
  7. Dans la liste Type de contenu des données d'événement, sélectionnez l'encodage de la charge utile de l'événement.

    Pour les événements directs de Cloud Firestore, il doit s'agir de application/protobuf et les données d'événement sont un tableau d'octets. Pour en savoir plus sur les messages protobuf pour les événements Cloud Firestore, consultez la page Événements courants.

  8. Dans la liste Région, sélectionnez la même région que le service Google Cloud qui génère des événements.

    Pour en savoir plus, consultez la page Emplacements Eventarc.

  9. Le cas échéant, cliquez sur Ajouter un filtre et spécifiez les éléments suivants :
    1. Dans le champ Attribut 1, en fonction de l'événement direct que vous avez choisi, sélectionnez l'ID de ressource pouvant servir de filtre d'événement.
    2. Sélectionnez un opérateur :
      • Égal à
      • Format de chemin d'accès: applicable aux ressources document (mode natif) et entity (mode Datastore). Utilisez des caractères génériques pour répondre aux modifications correspondant à un format. Un caractère générique * correspond à un seul segment, tandis qu'un caractère générique multisegment ** correspond à zéro ou plusieurs segments du format. Exemple :
        /users/* ou /users/{userId} Renvoie tous les documents de la collection /users. Ne correspond pas aux documents des sous-collections telles que /users/marie/messages/33e2IxYBD9enzS50SJ68.
        /users/** Renvoie tous les documents de la collection /users et les documents des sous-collections telles que /users/marie/messages/33e2IxYBD9enzS50SJ68

        Pour en savoir plus, consultez la page Comprendre les formats de chemin d'accès.

    3. Dans le champ Valeur d'attribut 1, saisissez la valeur exacte ou appliquez un format de chemin d'accès en fonction de l'opérateur que vous avez choisi.
    4. Si d'autres filtres d'attributs sont applicables, cliquez sur Ajouter un filtre et spécifiez les valeurs appropriées.
  10. Sélectionnez le compte de service qui appellera votre service ou workflow.

    Vous pouvez également créer un nouveau compte de service.

    Cela spécifie l'adresse e-mail du compte de service Identity and Access Management (IAM) associée au déclencheur et auquel vous avez précédemment attribué les rôles spécifiques requis par Eventarc.

  11. Dans la liste Destination de l'événement, sélectionnez Cloud Run.
  12. Sélectionner un service.

    Il s'agit du nom du service qui reçoit les événements du déclencheur. Le service doit se trouver dans le même projet que le déclencheur et recevoir des événements sous forme de requêtes HTTP POST envoyées à son chemin d'URL racine (/), à chaque déclenchement de l'événement.

  13. Vous pouvez éventuellement spécifier le Chemin de l'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. Exemple : /, /route, route, route/subroute.

  14. Cliquez sur Créer.

    15. Une fois le déclencheur créé, vous ne pouvez plus modifier les filtres de source d'événement. À la place, vous devez créer un nouveau déclencheur et supprimer l'ancien. Pour en savoir plus, consultez la section Gérer les déclencheurs.

gcloud

Vous pouvez créer un déclencheur en exécutant une commande gcloud eventarc triggers create, associée aux options obligatoires et facultatives.

Les options varient selon que vous exécutez Firestore en mode natif ou en mode Datastore. Reportez-vous à la page Choisir entre le mode natif et le mode Datastore pour en savoir plus.

Mode natif

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-run-service=DESTINATION_RUN_SERVICE \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="database=DATABASE" \
    --event-filters="namespace=NAMESPACE" \
    --event-filters-path-pattern="document=DOCUMENT" \
    --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"

Mode Datastore

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-run-service=DESTINATION_RUN_SERVICE \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="database=DATABASE" \
    --event-filters="namespace=NAMESPACE" \
    --event-filters-path-pattern="entity=ENTITY" \
    --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"

Remplacez les éléments suivants :

  • TRIGGER : l'ID du déclencheur ou un identifiant complet.

  • LOCATION : l'emplacement du déclencheur Eventarc. Vous pouvez également définir la propriété eventarc/location (par exemple, gcloud config set eventarc/location us-central1).

    Les déclencheurs Cloud Firestore pour Eventarc ne sont disponibles que dans certains emplacements et le déclencheur doit se trouver dans le même emplacement que la base de données Cloud Firestore. Pour en savoir plus, consultez les pages Emplacements Eventarc et Emplacements Cloud Firestore.

  • DESTINATION_RUN_SERVICE : nom du service Cloud Run qui reçoit les événements pour le déclencheur. Le service peut se trouver dans l'un des emplacements compatibles avec Cloud Run et ne doit pas nécessairement se trouver au même emplacement que le déclencheur. Cependant, le service doit se trouver dans le même projet que le déclencheur et recevoir des événements sous forme de requêtes HTTP POST envoyées à son chemin d'URL racine (/), à chaque déclenchement de l'événement.
  • DESTINATION_RUN_REGION : (facultatif) région dans laquelle se trouve le service Cloud Run de destination. Si elle n'est pas spécifiée, il est supposé que le service se trouve dans la même région que le déclencheur.
  • EVENT_FILTER_TYPE : identifiant de l'événement. Un événement est généré lorsqu'un appel d'API pour la méthode réussit. Pour les opérations de longue durée, l'événement n'est généré qu'à la fin de l'opération et uniquement si l'action s'est bien déroulée. Pour obtenir la liste des types d'événements acceptés, consultez la section Types d'événements Google acceptés par Eventarc.
    • Cloud Firestore n'accepte les types d'événements suivants qu'en mode natif uniquement.

    • google.cloud.firestore.document.v1.created : l'événement est envoyé lorsqu'un document est écrit pour la première fois.
    • google.cloud.firestore.document.v1.created.withAuthContext : l'événement avec des attributs de type informations d'authentification est envoyé lorsqu'un document est écrit pour la première fois.
    • google.cloud.firestore.document.v1.updated : l'événement est envoyé lorsqu'un document existe déjà et qu'une valeur y a été modifiée.
    • google.cloud.firestore.document.v1.updated.withAuthContext : l'événement avec des attributs de type informations d'authentification est envoyé lorsqu'un document existe déjà et qu'une valeur y a été modifiée.
    • google.cloud.firestore.document.v1.deleted : l'événement est envoyé lorsqu'un document est supprimé.
    • google.cloud.firestore.document.v1.deleted.withAuthContext : un événement avec des attributs de type informations d'authentification est envoyé lorsqu'un document est supprimé.
    • google.cloud.firestore.document.v1.written : l'événement est envoyé lorsqu'un document est créé, mis à jour ou supprimé.
    • google.cloud.firestore.document.v1.written.withAuthContext : l'événement avec des attributs de type informations d'authentification est envoyé lorsqu'un document est créé, mis à jour ou supprimé.

    Cloud Firestore n'accepte les types d'événements suivants qu'en mode Datastore uniquement. Dans Cloud Firestore en mode Datastore, les objets de données sont appelés entités.

    • google.cloud.datastore.entity.v1.created : l'événement est envoyé lorsqu'une entité est écrite pour la première fois.
    • google.cloud.datastore.entity.v1.created.withAuthContext : l'événement avec des attributs de type informations d'authentification est envoyé lorsqu'une entité est écrite pour la première fois.
    • google.cloud.datastore.entity.v1.updated : l'événement est envoyé lorsqu'une entité existe déjà et qu'une valeur y a été modifiée.
    • google.cloud.datastore.entity.v1.updated.withAuthContext : l'événement avec des attributs de type informations d'authentification est envoyé lorsqu'une entité existe déjà et qu'une valeur y a été modifiée.
    • google.cloud.datastore.entity.v1.deleted : l'événement est envoyé lorsqu'une entité est supprimée.
    • google.cloud.datastore.entity.v1.deleted.withAuthContext : un événement avec des attributs de type informations d'authentification est envoyé lorsqu'une entité est supprimée.
    • google.cloud.datastore.entity.v1.written : l'événement est envoyé lorsqu'une entité est créée, mise à jour ou supprimée.
    • google.cloud.datastore.entity.v1.written.withAuthContext : un événement avec des attributs de type informations d'authentification est envoyé lorsqu'une entité est créée, mise à jour ou supprimée.
  • DATABASE : base de données Firestore. Pour spécifier le nom de la base de données par défaut, utilisez (default).
  • NAMESPACE (facultatif) : espace de noms de la base de données Firestore. Pour l'espace de noms par défaut en mode Datastore, utilisez (default). S'il n'est pas spécifié, une correspondance de caractère générique (*) est effectuée avec toutes les occurrences.
  • DOCUMENT (facultatif) : applicable aux instances de base de données s'exécutant en mode natif uniquement. Chemin d'accès de la base de données à partir de laquelle vous souhaitez recevoir des événements à partir du moment où les données sont créées, mises à jour ou supprimées dans ce chemin d'accès. L'opérateur peut être l'un des opérateurs suivants :
    • Égal à. Par exemple : --event-filters="document=DOCUMENT"
    • Format de chemin d'accès (par exemple, --event-filters-path-pattern="document=DOCUMENT")

      Utilisez des caractères génériques pour répondre aux modifications apportées aux documents correspondant à un format. Un caractère générique * correspond à un seul segment, tandis qu'un caractère générique multisegment ** correspond à zéro ou plusieurs segments du format. Exemple :

      /users/* ou /users/{userId} Renvoie tous les documents de la collection /users. Ne correspond pas aux documents des sous-collections telles que /users/marie/messages/33e2IxYBD9enzS50SJ68
      /users/** Renvoie tous les documents de la collection /users et les documents des sous-collections telles que /users/marie/messages/33e2IxYBD9enzS50SJ68
      Pour en savoir plus, consultez la page Comprendre les formats de chemin d'accès.
  • ENTITY (facultatif) : applicable aux instances de base de données s'exécutant en mode Datastore uniquement. Chemin d'accès de la base de données à partir de laquelle vous souhaitez recevoir des événements à partir du moment où les données sont créées, mises à jour ou supprimées dans ce chemin d'accès. L'opérateur peut être l'un des opérateurs suivants :
    • Égal à. Par exemple : --event-filters="document=ENTITY"
    • Format de chemin d'accès (par exemple, --event-filters-path-pattern="ENTITY=ENTITY")

      Pour en savoir plus, consultez la page Comprendre les formats de chemin d'accès.

      Vous devrez peut-être échapper les caractères dans les ID de genre et les ID d'entité. L'échappement d'un caractère permet au filtre d'événement d'interpréter correctement l'ID. Pour en savoir plus, consultez la section Échappement des caractères.

  • EVENT_DATA_CONTENT_TYPE : encodage de la charge utile de l'événement. Pour les événements directs de Firestore, il doit s'agir de application/protobuf et les données d'événement sont un tableau d'octets. Pour en savoir plus sur les messages protobuf pour les événements Cloud Firestore, consultez la page Événements courants.
  • SERVICE_ACCOUNT_NAME : nom de votre compte de service géré par l'utilisateur.
  • PROJECT_ID : ID de votre projet Google Cloud.

Remarques :

  • Pour les événements directs de Cloud Firestore, l'encodage de la charge utile d'événement est application/protobuf.
  • L'option --event-filters="type=EVENT_FILTER_TYPE" est obligatoire. Si aucun autre filtre d'événement n'est défini, les événements de toutes les ressources sont mis en correspondance.
  • EVENT_FILTER_TYPE ne peut pas être modifié après sa création. Pour modifier EVENT_FILTER_TYPE, créez un nouveau déclencheur et supprimez l'ancien.
  • Chaque déclencheur peut comporter plusieurs filtres d'événement, séparés par une virgule et spécifiés dans une option --event-filters=[ATTRIBUTE=VALUE,…], ou vous pouvez répéter l'option pour ajouter d'autres filtres. Seuls les événements correspondant à tous les filtres sont envoyés à la destination. Les caractères génériques et les expressions régulières ne sont pas acceptés. Toutefois, lorsque vous utilisez l'option --event-filters-path-pattern, vous pouvez définir un format de chemin d'accès pour les ressources.
  • L'option --service-account permet de spécifier l'adresse e-mail du compte de service IAM (Identity and Access Management) associée au déclencheur.
  • Vous pouvez éventuellement spécifier un chemin d'accès relatif dans le service Cloud Run de destination auquel les événements du déclencheur doivent être envoyés, à l'aide de l'option --destination-run-path.

Exemple :

gcloud eventarc triggers create helloworld-trigger \
    --location=us-east1 \
    --destination-run-service=helloworld-events \
    --destination-run-region=us-east1 \
    --event-filters="type=google.cloud.firestore.document.v1.updated" \
    --event-filters="database=my-database" \
    --event-filters-path-pattern="document=users/my-document-*" \
    --event-data-content-type="application/protobuf" \
    --service-account=${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com

Cette commande crée un déclencheur appelé helloworld-trigger pour l'événement identifié comme google.cloud.firestore.document.v1.updated dans l'instance de base de données my-database exécutée en mode natif et filtre les événements pour les chemins document correspondant à users/my-document-.

Répertorier un déclencheur

Vous pouvez confirmer la création d'un déclencheur en répertoriant les déclencheurs Eventarc à l'aide de Google Cloud CLI ou de la console Google Cloud.

Console

  1. Dans la console Google Cloud, accédez à la page Déclencheurs d'Eventarc.

    Accéder à la page "Déclencheurs"

    Cette page répertorie vos déclencheurs dans tous les emplacements et inclut des détails tels que les noms, les régions, les fournisseurs d'événements, les destinations, etc.

  2. Pour filtrer vos déclencheurs, procédez comme suit :

    1. Cliquez sur Filtrer ou sur le champ Filtrer les déclencheurs.
    2. Dans la liste Propriétés, sélectionnez une option permettant de filtrer les déclencheurs.

    Vous pouvez sélectionner une seule propriété ou utiliser l'opérateur logique OR pour ajouter d'autres propriétés.

  3. Pour trier vos déclencheurs, à côté d'un en-tête de colonne compatible, cliquez sur Trier.

gcloud

Exécutez la commande suivante pour répertorier vos déclencheurs :

gcloud eventarc triggers list --location=-

Cette commande répertorie vos déclencheurs dans tous les emplacements et inclut des détails tels que les noms, les types, les destinations et les états.

Étapes suivantes