Déclencheurs Cloud Storage

Dans Cloud Functions, un déclencheur Cloud Storage permet d'appeler une fonction en réponse aux modifications de Cloud Storage. Lorsque vous spécifiez un déclencheur Cloud Storage pour une fonction, vous choisissez un type d'événement et spécifiez un bucket Cloud Storage. Votre fonction est appelée chaque fois qu'une modification se produit sur un objet (fichier) dans le bucket spécifié.

Les types d'événements Cloud Storage suivants sont acceptés :

Event Type d'événement Description
Objet finalisé
  • 2e génération : google.cloud.storage.object.v1.finalized (via Eventarc)
  • 1re génération : google.storage.object.finalize
 Se produit lorsqu'un objet est créé ou qu'un objet existant est remplacé et qu'une nouvelle génération de cet objet est créée.
Objet supprimé
  • 2e génération : google.cloud.storage.object.v1.deleted (via Eventarc)
  • 1re génération : google.storage.object.delete
 Se produit lorsqu'un objet est définitivement supprimé.
Objet archivé
  • 2e génération : google.cloud.storage.object.v1.archived (via Eventarc)
  • 1re génération : google.storage.object.archive
 Se produit lorsqu'une version active d'un objet devient une version archivée. Pour en savoir plus, consultez la page Gestion des versions des objets.
Métadonnées d'objet mises à jour
  • 2e génération : google.cloud.storage.object.v1.metadataUpdated (via Eventarc)
  • 1re génération : google.storage.object.metadataUpdate
 Se produit lorsque les métadonnées d'un objet existant changent.

Pour qu'une fonction utilise un déclencheur Cloud Storage, elle doit être mise en œuvre en tant que fonction basée sur les événements :

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

Autorisations

Pour utiliser des déclencheurs Cloud Storage dans Cloud Functions (2e génération), l'Agent de service Cloud Storage doit disposer du rôle IAM Éditeur Pub/Sub (roles/pubsub.publisher) sur votre projet. Cette exigence ne s'applique pas à Cloud Functions (1re génération).

Déploiement

Vous pouvez spécifier un déclencheur Cloud Storage lorsque vous déployez une fonction. Consultez la page Déployer une fonction Cloud pour obtenir des instructions générales sur le déploiement d'une fonction. Consultez la suite de cette page pour obtenir des informations supplémentaires spécifiques à la configuration des déclencheurs Cloud Storage lors du déploiement.

gcloud

Si vous déployez à l'aide de gcloud CLI, vous pouvez utiliser le type d'événement Objet finalisé Cloud Storage avec les options suivantes :

gcloud functions deploy YOUR_FUNCTION_NAME \
--trigger-bucket=YOUR_STORAGE_BUCKET \
[--retry] \
...

Pour utiliser des types d'événements autres que le type Objet finalisé, utilisez les options suivantes :

  • Pour Cloud Functions (2nd gen), procédez comme suit :

    gcloud functions deploy YOUR_FUNCTION_NAME \
--gen2 \
--trigger-event-filters="type=EVENT_TYPE" \
--trigger-event-filters="bucket=YOUR_STORAGE_BUCKET" \
...

    Lorsque vous déployez des fonctions de 2e génération, spécifiez uniquement le nom du bucket, sans le premier gs://. Exemple : --trigger-event-filters="bucket=my-bucket".

  • Pour Cloud Functions (1st gen), procédez comme suit :

    gcloud functions deploy YOUR_FUNCTION_NAME \
--trigger-event=EVENT_TYPE \
--trigger-resource=YOUR_STORAGE_BUCKET \
...

Anciens événements Cloud Storage

Les anciennes fonctions de Cloud Functions (1st gen) utilisent les anciennes notifications de changement d'objet pour les déclencheurs Cloud Storage :

gcloud functions deploy YOUR_FUNCTION_NAME \
--trigger-event=providers/cloud.storage/eventTypes/object.change \
--trigger-resource=YOUR_STORAGE_BUCKET \
...

Ce type d'événement est compatible avec les anciennes fonctions qui utilisent déjà ces événements. Toutefois, nous vous déconseillons d'utiliser ce type d'événement, car il se peut qu'il soit supprimé ultérieurement.

Console

Si vous effectuez un déploiement à l'aide de la console Google Cloud, vous pouvez configurer un déclencheur Cloud Storage dans la section Déclencheur.

  • Pour Cloud Functions (2nd gen), procédez comme suit :

    1. Dans le champ Type de déclencheur, sélectionnez Cloud Storage.

    2. Dans le champ Type d'événement, sélectionnez un événement déclencheur. La valeur par défaut est google.cloud.storage.object.v1.finalized.

      Pour un événement Cloud Storage qui utilise Cloud Audit Logs, reportez-vous aux instructions de configuration du déclencheur pour un déclencheur Eventarc.

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

    4. Cochez ou décochez la case Réessayer après échec pour vérifier si Cloud Functions relance automatiquement un appel de fonction ayant échoué. Pour en savoir plus, consultez la section Effectuer de nouvelles tentatives d'exécution des fonctions basées sur des événements.

    5. Cliquez sur Plus d'options pour effectuer une configuration supplémentaire sur votre déclencheur :

      • Dans le champ Type de déclencheur, spécifiez l'une des sources Google, Personnalisé ou Tiers :

        • Les sources Google vous permettent de spécifier des déclencheurs pour Pub/Sub, Cloud Storage, Firestore et d'autres fournisseurs d'événements Google. Dans le volet Déclencheur Eventarc, utilisez le champ Fournisseur d'événements pour sélectionner le produit qui fournit le type d'événement que vous souhaitez déclencher pour votre fonction. Ensuite, dans le champ Événement, sélectionnez l'événement que vous souhaitez utiliser comme déclencheur.

        • L'option Personnalisé vous permet de produire et de consommer des événements à partir du code de votre application. Suivez les instructions du volet Déclencheur Eventarc pour créer un canal. Un canal est une ressource utilisée comme pipeline pour fournir des événements personnalisés aux producteurs auprès des utilisateurs. Les événements personnalisés sont publiés dans un canal et un déclencheur Eventarc s'abonne à ces événements.

        • L'option Tiers vous permet d'intégrer des fournisseurs autres que Google qui proposent une source Eventarc. Pour plus d'informations, consultez la section Événements tiers dans Eventarc.

      • Dans le champ Événement, sélectionnez un événement déclencheur. La valeur par défaut est google.cloud.storage.object.v1.finalized.

      • Dans le champ Compte de service, vous pouvez si vous le souhaitez sélectionner un compte de service à utiliser comme identité du déclencheur Eventarc. Pour en savoir plus, consultez la section Identité du déclencheur.

    6. Cliquez sur Enregistrer le déclencheur.

  • Pour Cloud Functions (1st gen), procédez comme suit :

    1. Dans le champ Type de déclencheur, sélectionnez Cloud Storage.
    2. Dans le champ Type d'événement, sélectionnez un type d'événement.
    3. 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.
    4. Cochez ou décochez la case Réessayer après échec pour vérifier si les appels de fonction ayant échoué sont automatiquement relancés. Pour en savoir plus, consultez la section Effectuer de nouvelles tentatives d'exécution des fonctions basées sur des événements.

Diffusion d'événements

Les déclencheurs Cloud Storage sont mis en œuvre avec des 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 en savoir plus, consultez la page Quotas et limites de Cloud Storage.

Étapes suivantes