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

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 à des é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. Pour 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.

Définir les rôles requis

Vous ou votre administrateur devez attribuer les rôles IAM suivants au compte déployeur, à l'identité du déclencheur et, éventuellement, à l'agent de service Pub/Sub et à l'agent de service Cloud Storage.

Rôles requis pour le compte déployeur

  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.

    Pour obtenir les autorisations nécessaires pour suivre ce tutoriel, 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 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.

Rôles requis pour l'identité du déclencheur

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

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

Rôle facultatif pour l'agent de service Cloud Storage

  • 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'

Rôle facultatif pour l'agent de service Pub/Sub

  • 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

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/

É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.9.2
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 run deploy helloworld-events \
      --source . \
      --function helloGCS \
      --base-image BASE_IMAGE \
      --region us-central1

Remplacez BASE_IMAGE par l'environnement d'image de base de votre fonction, par exemple nodejs22. Pour en savoir plus sur les images de base et les packages inclus dans chaque image, consultez Environnements d'exécution de langage et images de base compatibles.

Python 

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

Remplacez BASE_IMAGE par l'environnement d'image de base de votre fonction, par exemple python313. Pour en savoir plus sur les images de base et les packages inclus dans chaque image, consultez Environnements d'exécution de langage et images de base compatibles.

Une fois le déploiement terminé, la Google Cloud CLI affiche une URL sur laquelle votre service 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=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    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",
     .....
  }
]

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

Une fois l'entrée de journal affichée, vous avez la confirmation que vous avez bien déployé une fonction basée sur des événements qui a été déclenchée lorsqu'un fichier texte a été importé dans Cloud Storage.