Déclencher des fonctions depuis Cloud Storage à l'aide d'Eventarc

---

Preview — Cloud Run functions

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Ce tutoriel explique comment déployer une fonction basée sur des événements dans Cloud Run et utiliser Eventarc pour déclencher la fonction en réponse aux événements Cloud Storage à l'aide de la Google Cloud CLI.

En spécifiant des filtres pour un déclencheur Eventarc, vous pouvez configurer le routage des événements, y compris la source et la cible des événements. Dans l'exemple de ce tutoriel, la mise à jour d'un bucket Cloud Storage déclenche l'événement et une requête est envoyée à votre fonction sous la forme d'une requête HTTP.

Objectifs

Au cours de ce tutoriel, vous allez :

1. Créer un bucket Cloud Storage qui servira de source d'événements.
2. Déployer une fonction basée sur des événements
3. Créer un déclencheur Eventarc
4. Déclencher la fonction en important un fichier dans Cloud Storage

Coûts

Dans ce document, vous utilisez les composants facturables suivants de Google Cloud :

• Artifact Registry
• Cloud Build
• Cloud Run
• Cloud Storage
• Eventarc

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût. Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai gratuit.

Avant de commencer

Les contraintes de sécurité définies par votre organisation peuvent vous empêcher d'effectuer les étapes suivantes. Pour obtenir des informations de dépannage, consultez la page Développer des applications dans un environnement Google Cloud limité.

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
2. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

5. Make sure that billing is enabled for your Google Cloud project.

6. Install the Google Cloud CLI.

7. To initialize the gcloud CLI, run the following command:

   gcloud init

8. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

9. Make sure that billing is enabled for your Google Cloud project.

10. Si vous n'utilisez pas Cloud Shell, mettez à jour les composants Google Cloud CLI et connectez-vous à l'aide de votre compte :

    gcloud components update
    gcloud auth login

11. Activer les API :

    gcloud services enable artifactregistry.googleapis.com \
        cloudbuild.googleapis.com \
        eventarc.googleapis.com \
        run.googleapis.com \
        storage.googleapis.com

12. Définissez les variables de configuration à utiliser dans ce tutoriel:

    export REGION=us-central1
    gcloud config set run/region ${REGION}
    gcloud config set run/platform managed
    gcloud config set eventarc/location ${REGION}

13. Si vous êtes soumis à une règle d'administration de restriction de domaine limitant les appels non authentifiés pour votre projet, vous devez accéder au service déployé comme décrit dans la section Tester les services privés.

Définir les 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.

   Autorisations requises

   Pour obtenir les autorisations nécessaires pour suivre ce tutoriel, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

   • Éditeur Cloud Build (roles/cloudbuild.builds.editor)
   • Administrateur Cloud Run (roles/run.admin)
   • Développeur de source Cloud Run (roles/run.sourceDeveloper)
   • Administrateur Eventarc (roles/eventarc.admin)
   • Accesseur de vues de journaux (roles/logging.viewAccessor)
   • Administrateur de projet IAM (roles/resourcemanager.projectIamAdmin)
   • Administrateur de compte de service (roles/iam.serviceAccountAdmin)
   • Utilisateur du compte de service (roles/iam.serviceAccountUser)
   • Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin)
   • Administrateur de l'espace de stockage (roles/storage.admin)

   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 :

   [e-mail]

   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.

   Remarque :

   La contrainte liée aux règles d'administration iam.automaticIamGrantsForDefaultServiceAccounts empêche l'attribution automatique du rôle "Éditeur" aux comptes de service par défaut. Si vous avez créé votre organisation après le 3 mai 2024, cette contrainte est appliquée par défaut.

   Nous vous recommandons vivement d'appliquer cette contrainte pour désactiver l'attribution automatique de rôles. Si vous désactivez l'attribution automatique de rôles, vous devez choisir les rôles à attribuer aux comptes de service par défaut, puis attribuer ces rôles vous-même.

   Si le compte de service par défaut dispose déjà du rôle Éditeur, nous vous recommandons de le remplacer par des rôles moins permissifs. Pour modifier les rôles du compte de service en toute sécurité, utilisez Policy Simulator pour voir l'impact de la modification, puis attribuez et révoquez les rôles appropriés.

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:[e-mail] \
       --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:[e-mail] \
       --role=roles/eventarc.eventReceiver

5. Avant de créer un déclencheur pour des événements directs à partir de Cloud Storage, attribuez le rôle Éditeur Pub/Sub (roles/pubsub.publisher) à l'agent de service Cloud Storage :

   SERVICE_ACCOUNT="$(gcloud storage service-agent --project=PROJECT_ID)"
   
   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:${SERVICE_ACCOUNT}" \
       --role='roles/pubsub.publisher'

6. 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:[e-mail] \
       --role=roles/iam.serviceAccountTokenCreator

Créer un bucket Cloud Storage

Créez un bucket Cloud Storage qui servira de source d'événements :

gcloud storage buckets create -l us-central1 gs://PROJECT_ID-bucket/

Remarque : Le bucket Cloud Storage doit se trouver dans le même projet Google Cloud et dans la même région ou emplacement multirégional que le déclencheur Eventarc.

Écrire une fonction basée sur des événements

Pour écrire une fonction basée sur des événements, procédez comme suit:

Node.js

1. Créez un répertoire nommé helloGCS et modifiez les sous-répertoires comme suit :

      mkdir helloGCS
      cd helloGCS
   

2. Créez un fichier package.json dans le répertoire helloGCS pour spécifier les dépendances Node.js:

   {
     "name": "nodejs-docs-samples-functions-v2-storage",
     "version": "0.0.1",
     "private": true,
     "license": "Apache-2.0",
     "author": "Google LLC",
     "repository": {
       "type": "git",
       "url": "https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git"
     },
     "engines": {
       "node": ">=16.0.0"
     },
     "scripts": {
       "test": "c8 mocha -p -j 2 test/*.test.js --timeout=60000"
     },
     "dependencies": {
       "@google-cloud/functions-framework": "^3.0.0"
     },
     "devDependencies": {
       "c8": "^10.0.0",
       "mocha": "^10.0.0",
       "sinon": "^18.0.0",
       "supertest": "^7.0.0"
     }
   }
   

3. Créez un fichier index.js dans le répertoire helloGCS avec l'exemple Node.js suivant:

   const functions = require('@google-cloud/functions-framework');
   
   // Register a CloudEvent callback with the Functions Framework that will
   // be triggered by Cloud Storage.
   functions.cloudEvent('helloGCS', cloudEvent => {
     console.log(`Event ID: ${cloudEvent.id}`);
     console.log(`Event Type: ${cloudEvent.type}`);
   
     const file = cloudEvent.data;
     console.log(`Bucket: ${file.bucket}`);
     console.log(`File: ${file.name}`);
     console.log(`Metageneration: ${file.metageneration}`);
     console.log(`Created: ${file.timeCreated}`);
     console.log(`Updated: ${file.updated}`);
   });

Python

1. Créez un répertoire nommé helloGCS et modifiez les sous-répertoires comme suit :

      mkdir helloGCS
      cd helloGCS
   

2. Créez un fichier requirements.txt dans le répertoire helloGCS pour spécifier les dépendances Python:

   functions-framework==3.5.0
   cloudevents==1.11.0

   Cela ajoute les packages requis par l'exemple.

3. Créez un fichier main.py dans le répertoire helloGCS avec l'exemple Python suivant:

   from cloudevents.http import CloudEvent
   
   import functions_framework
   
   
   # Triggered by a change in a storage bucket
   @functions_framework.cloud_event
   def hello_gcs(cloud_event: CloudEvent) -> tuple:
       """This function is triggered by a change in a storage bucket.
   
       Args:
           cloud_event: The CloudEvent that triggered this function.
       Returns:
           The event ID, event type, bucket, name, metageneration, and timeCreated.
       """
       data = cloud_event.data
   
       event_id = cloud_event["id"]
       event_type = cloud_event["type"]
   
       bucket = data["bucket"]
       name = data["name"]
       metageneration = data["metageneration"]
       timeCreated = data["timeCreated"]
       updated = data["updated"]
   
       print(f"Event ID: {event_id}")
       print(f"Event type: {event_type}")
       print(f"Bucket: {bucket}")
       print(f"File: {name}")
       print(f"Metageneration: {metageneration}")
       print(f"Created: {timeCreated}")
       print(f"Updated: {updated}")
   
       return event_id, event_type, bucket, name, metageneration, timeCreated, updated
   
   

Déployer une fonction basée sur des événements

Déployez la fonction nommée helloworld-events en exécutant la commande suivante dans le répertoire contenant l'exemple de code:

Node.js

gcloud beta run deploy helloworld-events \
      --source . \
      --function helloGCS \
      --base-image nodejs20 \
      --region us-central1

Python

gcloud beta run deploy helloworld-events \
      --source . \
      --function hello_gcs \
      --base-image python312 \
      --region us-central1

Une fois le déploiement terminé, Google Cloud CLI affiche une URL sur laquelle le service helloworld-events est en cours d'exécution.

Créer un déclencheur Eventarc

Le déclencheur Eventarc envoie des événements à partir du bucket Cloud Storage vers le service Cloud Run helloworld-events.

1. Créez un déclencheur filtrant les événements Cloud Storage :

   gcloud eventarc triggers create TRIGGER_NAME  \
       --location=${REGION} \
       --destination-run-service=helloworld-events  \
       --destination-run-region=${REGION} \
       --event-filters="type=google.cloud.storage.object.v1.finalized" \
       --event-filters="bucket=PROJECT_ID-bucket" \
       --service-account=[e-mail]

   Remplacez :

   • TRIGGER_NAME par le nom de votre déclencheur.
   • PROJECT_ID par l'ID de votre projet Google Cloud
   • PROJECT_NUMBER par le numéro de votre projet Google Cloud

   Notez que lorsque vous créez un déclencheur Eventarc pour la première fois dans un projet Google Cloud, le provisionnement de l'agent de service Eventarc peut prendre quelques instants. Ce problème peut généralement être résolu en essayant à nouveau de créer le déclencheur. Pour en savoir plus, consultez Erreurs d'autorisation refusée.

2. Vérifiez que le déclencheur a bien été créé. Notez que, bien que votre déclencheur soit créé immédiatement, il peut falloir jusqu'à deux minutes pour qu'il soit pleinement opérationnel.

   gcloud eventarc triggers list --location=${REGION}

   La sortie devrait ressembler à ce qui suit :

   NAME: helloworld-events
   TYPE: google.cloud.storage.object.v1.finalized
   DESTINATION: Cloud Run service: helloworld-events
   ACTIVE: Yes
   LOCATION: us-central1
   

Générer et afficher un événement

Importez un fichier texte dans le bucket Cloud Storage pour générer un événement acheminé vers la fonction. Cloud Run Functions consigne l'événement dans les journaux de service.

1. Importez un fichier texte dans Cloud Storage pour générer un événement:

    echo "Hello World" > random.txt
    gcloud storage cp random.txt gs://PROJECT_ID-bucket/random.txt
   

   L'importation génère un événement, et Cloud Run Functions consigne le message de l'événement.

2. Pour afficher l'entrée de journal, procédez comme suit :

   1. Filtrez les entrées de journal et renvoyez la sortie au format JSON :

      gcloud logging read "resource.labels.service_name=helloworld-events AND textPayload:random.txt" --format=json
      

   2. Recherchez une entrée de journal semblable à ceci :

      [
        {
         ....
          "resource": {
            "labels": {
              ....
              "location": "us-central1",
              .....
              "service_name": "helloworld-events"
            },
          },
          "textPayload": "File: random.txt",
           .....
        }
      ]
      

      Remarque : Si vous ne voyez pas d'entrée de journal, attendez quelques minutes et relancez la commande gcloud logging read. Une fois créé, le déclencheur peut prendre jusqu'à deux minutes pour commencer à filtrer les événements.

      L'affichage des journaux peut nécessiter quelques instants. S'ils n'apparaissent pas immédiatement, patientez une minute et vérifiez de nouveau.

Lorsque l'entrée de journal s'affiche, cela signifie que vous avez bien déployé une fonction basée sur des événements déclenchée lorsqu'un fichier texte a été importé dans Cloud Storage.

Effectuer un nettoyage

Si vous avez créé un projet pour ce tutoriel, supprimez-le. Si vous avez utilisé un projet existant et que vous souhaitez le conserver sans les modifications du présent tutoriel, supprimez les ressources créées pour ce tutoriel.

Supprimer le projet

Le moyen le plus simple d'empêcher la facturation est de supprimer le projet que vous avez créé pour ce tutoriel.

Pour supprimer le projet :

Attention : La suppression d'un projet entraîne les effets décrits ci-dessous :

• Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour les tâches décrites dans ce document et que vous le supprimez, vous supprimerez également tout autre travail effectué dans le projet.
• Les ID de projets personnalisés sont perdus. Lorsque vous avez créé ce projet, vous avez peut-être créé un ID de projet personnalisé que vous souhaitez utiliser à l'avenir. Pour conserver les URL qui utilisent l'ID de projet, telle qu'une URL appspot.com, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.

Si vous envisagez d'explorer plusieurs architectures, tutoriels et guides de démarrage rapide, réutiliser des projets peut vous aider à ne pas dépasser les limites de quotas des projets.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Supprimer les ressources du tutoriel

1. Supprimez le service Cloud Run que vous avez déployé dans ce tutoriel :

   gcloud run services delete SERVICE_NAME

   Où SERVICE_NAME est le nom de service que vous avez choisi.

   Vous pouvez également supprimer des services Cloud Run à partir de Google Cloud Console.

2. Supprimez les configurations gcloud CLI par défaut que vous avez ajoutées lors de la configuration du tutoriel.

   Exemple :

   gcloud config unset run/region

   ou

   gcloud config unset project

3. Supprimez les autres ressources Google Cloud créées dans ce tutoriel :

   • Supprimez le déclencheur Eventarc :

     gcloud eventarc triggers delete TRIGGER_NAME
     

     Remplacez TRIGGER_NAME par le nom de votre déclencheur.

Étape suivante

• Apprenez à créer des déclencheurs Eventarc pour d'autres types d'événements.
• Gérer les fonctions