Créer des déclencheurs à partir d'événements Cloud Storage

Dans Cloud Run, vous pouvez déclencher des services à partir de Cloud Storage à l'aide d'Eventarc, en réponse aux modifications apportées à Cloud Storage.

Lorsque vous spécifiez un déclencheur Cloud Storage pour votre service, vous choisissez un type d'événement et spécifiez un bucket Cloud Storage. Grâce à ce déclencheur, votre service est appelé chaque fois qu'une modification se produit sur un objet (fichier) dans le bucket spécifié.

Pour que votre service soit déclenché par un événement sur un bucket Cloud Storage, le service et le bucket doivent se trouver dans le même projet Google Cloud .

Pour obtenir des instructions détaillées et des exemples de code permettant de créer des déclencheurs à partir d'événements Cloud Storage, consultez les tutoriels suivants :

Types d'événements Cloud Storage acceptés

Cloud Run accepte les types d'événements Cloud Storage suivants :

Événement Type d'événement Description
Objet finalisé
  • google.cloud.storage.object.v1.finalized (via Eventarc)
 Se produit lorsque vous créez un objet ou écrasez un objet existant, et que Cloud Storage crée une nouvelle génération de cet objet.
Objet supprimé
  • google.cloud.storage.object.v1.deleted (via Eventarc)
 Se produit lorsqu'un objet est définitivement supprimé. Pour en savoir plus, consultez Suppression réversible.
Objet archivé
  • google.cloud.storage.object.v1.archived (via Eventarc)
 Se produit lorsqu'une version active d'un objet devient une version obsolète. Pour en savoir plus, consultez Gestion des versions d'objets.
Métadonnées d'objet mises à jour
  • google.cloud.storage.object.v1.metadataUpdated (via Eventarc)
 Envoyé lorsque vous modifiez les métadonnées d'un objet existant.

Le dépôt Google Events contient des ressources supplémentaires sur l'utilisation des données d'événement.

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, Cloud Logging, Pub/Sub et Cloud Storage :

    Activer les API

  3. Attribuez les rôles et autorisations IAM requis.

Rôles requis pour le compte déployeur

Pour obtenir les autorisations nécessaires pour déclencher des événements Cloud Storage, 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 avec des rôles personnalisés ou d'autres rôles prédéfinis.

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

Créer un déclencheur pour les services

Après avoir déployé un service, vous pouvez configurer un déclencheur à l'aide de la console Google Cloud , de la Google Cloud CLI ou de Terraform.

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 sur le service, accédez à l'onglet Déclencheurs.

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

  6. Dans le volet Déclencheur Eventarc, modifiez les informations 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 Événements tiers dans Eventarc.

    3. Sélectionnez Cloud Storage dans la liste Fournisseur d'événements pour choisir un produit qui fournit le type d'événement permettant de déclencher votre service. Pour obtenir la liste des fournisseurs d'événements, consultez Fournisseurs et destinations d'événements.

    4. Sélectionnez google.cloud.storage.object.v1.finalized 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 Types d'événements.

    5. Dans le champ Bucket, cliquez sur Parcourir pour sélectionner un bucket Cloud Storage que le déclencheur doit surveiller. Les modifications apportées aux objets de ce bucket déclencheront des appels vers votre fonction.

    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. Si vous le souhaitez, cochez la case Activer la nouvelle tentative en cas d'échec pour activer les nouvelles tentatives en cas d'échec de la remise. Sinon, le comportement par défaut est une seule tentative de remise sans nouvelle tentative. Pour en savoir plus, consultez Événements de nouvelle tentative.

    10. 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 et achemine les événements :

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=LOCATION \
    --destination-run-service=DESTINATION_RUN_SERVICE  \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="bucket=BUCKET" \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Remplacez les éléments suivants :

    • TRIGGER_NAME : 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).

      Pour éviter tout problème de performances et de résidence des données, l'emplacement doit correspondre à celui du service Google Cloud qui génère les événements. Pour en savoir plus, consultez la page Emplacements Eventarc.

    • 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) emplacement Cloud Run dans lequel 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.
    • BUCKET est l'identifiant unique du bucket Cloud Storage.
    • SERVICE_ACCOUNT_NAME : nom de votre compte de service géré par l'utilisateur.
    • PROJECT_ID : ID de votre projet Google Cloud .

    Remarques :

    • 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.
    • Vous pouvez également utiliser le flag --max-retry-attempts pour spécifier une seule tentative de distribution d'événement sans nouvelle tentative. La seule valeur valide est 1. Si vous omettez l'indicateur, le comportement de réessai standard s'applique. Pour en savoir plus, consultez Événements de nouvelle tentative.
    • D'autres indicateurs sont disponibles. Pour en savoir plus, consultez les sections sur gcloud eventarc triggers create

Terraform

Pour créer un déclencheur Eventarc pour un service Cloud Run, consultez Créer un déclencheur à l'aide de Terraform.

Créer un déclencheur pour les fonctions

Après avoir déployé une fonction, vous pouvez configurer un déclencheur à l'aide de la console Google Cloud , de Google Cloud CLI ou de Terraform.

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 :

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

    Accédez à Cloud Run

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

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

  4. Sélectionnez Déclencheur Cloud Storage.

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

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

    2. Sélectionnez un type de déclencheur dans la liste :

      • 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 Événements tiers dans Eventarc.

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

    4. Sélectionnez google.cloud.storage.object.v1.finalized 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 Types d'événements.

    5. Laissez le champ Type de contenu des données d'événement tel quel.

    6. Dans le champ Bucket, cliquez sur Parcourir pour sélectionner un bucket Cloud Storage que le déclencheur doit surveiller. Les modifications apportées aux objets de ce bucket déclencheront des appels vers votre fonction.

    7. 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 ressourceGoogle 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 Comprendre les emplacements Eventarc pour en savoir plus sur les emplacements des déclencheurs Eventarc.

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

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

    10. Si vous le souhaitez, cochez la case Activer la nouvelle tentative en cas d'échec pour activer les nouvelles tentatives en cas d'échec de la remise. Sinon, le comportement par défaut est une seule tentative de remise sans nouvelle tentative. Pour en savoir plus, consultez Événements de nouvelle tentative.

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

  7. Cliquez sur Créer.

  8. Dans l'onglet Source, modifiez le code source si nécessaire, puis sélectionnez Enregistrer et redéployer.

gcloud

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

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

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

    Remplacez les éléments suivants :

    • FUNCTION : 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 : point d'entrée de votre fonction dans votre code source. Il s'agit du code que Cloud Run exécute lorsque votre fonction s'exécute. 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 : environnement de l'image de base de votre fonction. Pour en savoir plus sur les images de base et les packages inclus dans chaque image, consultez Images de base de l'environnement d'exécution.

    • REGION : Google Cloud région dans laquelle vous souhaitez déployer votre fonction. Par exemple, europe-west1.

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

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=LOCATION \
    --destination-run-service=FUNCTION  \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="bucket=BUCKET" \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Remplacez les éléments suivants :

    • TRIGGER_NAME : 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).

      Pour éviter tout problème de performances et de résidence des données, l'emplacement doit correspondre à celui du service Google Cloud qui génère les événements. Pour en savoir plus, consultez la page Emplacements Eventarc.

    • FUNCTION : nom de la fonction Cloud Run déployée qui reçoit les événements pour le déclencheur.
    • DESTINATION_RUN_REGION : (facultatif) emplacement Cloud Run dans lequel se trouve la fonction Cloud Run de destination. Si elle n'est pas spécifiée, il est supposé que la fonction 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.
    • BUCKET est l'identifiant unique du bucket Cloud Storage.
    • SERVICE_ACCOUNT_NAME : nom de votre compte de service géré par l'utilisateur.
    • PROJECT_ID : ID de votre projet Google Cloud .

    Remarques :

    • 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.
    • Vous pouvez également utiliser le flag --max-retry-attempts pour spécifier une seule tentative de distribution d'événement sans nouvelle tentative. La seule valeur valide est 1. Si vous omettez l'indicateur, le comportement de réessai standard s'applique. Pour en savoir plus, consultez Événements de nouvelle tentative.
    • D'autres indicateurs sont disponibles. Pour en savoir plus, consultez les sections sur gcloud eventarc triggers create

Terraform

Pour créer un déclencheur Eventarc pour une fonction Cloud Run, consultez Créer un déclencheur à l'aide de Terraform.

Diffusion d'événements

Les déclencheurs Cloud Storage sont implémentés avec les notifications Pub/Sub pour Cloud Storage. Les événements sont soumis aux garanties de diffusion des notifications Pub/Sub.

Un bucket Cloud Storage peut comporter jusqu'à 10 configurations de notification déclenchant un événement spécifique. Si vous dépassez les limites de notifications du bucket, des déploiements de fonctions supplémentaires échoueront avec un message d'erreur semblable à celui-ci :

Cloud Storage bucket ...: Pub/Sub notification limit reached

Pour contourner cette limite, vous pouvez gérer votre propre sujet Pub/Sub et l'enregistrer pour les notifications Cloud Storage du type auquel vous souhaitez que votre fonction réponde. Par exemple, vous pouvez configurer une seule notification pour l'événement de votre choix (comme la création d'un objet) vers un sujet Pub/Sub. Ensuite, ajoutez autant d'abonnés de fonction que nécessaire au sujet pour traiter l'événement et le distribuer à plusieurs destinations. Exemple :

  1. Créez votre propre sujet Pub/Sub.
  2. Créez une seule configuration de notification sur votre bucket Cloud Storage qui se déclenche lors d'un événement spécifique (tel que OBJECT_FINALIZE pour la création d'objet) et envoie l'événement à votre sujet Pub/Sub unique.
  3. Créez une ou plusieurs fonctions déclenchées par votre sujet Pub/Sub.

Vous obtenez ainsi une configuration de notification Cloud Storage, un sujet Pub/Sub et autant de fonctions que nécessaire (dans les limites de distribution très élevées autorisées par Pub/Sub).

Pour en savoir plus sur les limites de Cloud Storage, consultez la page Quotas et limites de Cloud Storage.

Étapes suivantes