Attivare funzioni da Cloud Storage utilizzando Eventarc

Questo tutorial mostra come eseguire il deployment di una funzione basata su eventi in Cloud Run e utilizzare Eventarc per attivare la funzione in risposta agli eventi Cloud Storage utilizzando Google Cloud CLI.

Specificando i filtri per un trigger Eventarc, puoi configurare il routing degli eventi, inclusi l'origine e il target degli eventi. Per l'esempio in questo tutorial, un aggiornamento a un bucket Cloud Storage attiva l'evento e viene inviata una richiesta alla tua funzione sotto forma di richiesta HTTP.

Obiettivi

In questo tutorial, imparerai a:

  1. Crea un bucket Cloud Storage come origine evento.
  2. Esegui il deployment di una funzione basata su eventi.
  3. Crea un trigger Eventarc.
  4. Attiva la funzione caricando un file in Cloud Storage.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi.

I nuovi utenti di Google Cloud potrebbero avere diritto a una prova senza costi.

Prima di iniziare

I vincoli di sicurezza definiti dalla tua organizzazione potrebbero impedirti di completare i passaggi seguenti. Per informazioni sulla risoluzione dei problemi, vedi Sviluppare applicazioni in un ambiente Google Cloud vincolato.

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

  2. Installa Google Cloud CLI.

  3. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  4. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init

  5. Crea o seleziona un progetto Google Cloud .

    Ruoli richiesti per selezionare o creare un progetto

    • Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per cui ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

    • Crea un progetto Google Cloud :

      gcloud projects create PROJECT_ID

      Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.

    • Seleziona il progetto Google Cloud che hai creato:

      gcloud config set project PROJECT_ID

      Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

  6. Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

  7. Installa Google Cloud CLI.

  8. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  9. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init

  10. Crea o seleziona un progetto Google Cloud .

    Ruoli richiesti per selezionare o creare un progetto

    • Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per cui ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

    • Crea un progetto Google Cloud :

      gcloud projects create PROJECT_ID

      Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.

    • Seleziona il progetto Google Cloud che hai creato:

      gcloud config set project PROJECT_ID

      Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

  11. Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

  12. Se non utilizzi Cloud Shell, aggiorna i componenti di Google Cloud CLI e accedi utilizzando il tuo account: 
    gcloud components update
gcloud auth login
  13. Abilita le API: 
    gcloud services enable artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    eventarc.googleapis.com \
    run.googleapis.com \
    storage.googleapis.com
  14. Imposta le variabili di configurazione da utilizzare in questo tutorial: 
    export REGION=us-central1
gcloud config set run/region ${REGION}
gcloud config set run/platform managed
gcloud config set eventarc/location ${REGION}

  15. Se il tuo progetto è soggetto a una policy dell'organizzazione con limitazione del dominio che limita le chiamate non autenticate, dovrai accedere al servizio di cui hai eseguito il deployment come descritto in Test dei servizi privati.

Imposta i ruoli richiesti

Tu o l'amministratore dovete concedere all'account deployer, all'identità del trigger e, facoltativamente, all'agente di servizio Pub/Sub e all'agente di servizio Cloud Storage i seguenti ruoli IAM.

Ruoli obbligatori per l'account deployer

  1. Se sei l'autore del progetto, ti viene concesso il ruolo di base Proprietario (roles/owner). Per impostazione predefinita, questo ruolo IAM (Identity and Access Management) include le autorizzazioni necessarie per l'accesso completo alla maggior parte delle risorse Google Cloude puoi saltare questo passaggio.

    Se non sei il Project Creator, devi concedere le autorizzazioni richieste sul progetto all'entità appropriata. Ad esempio, un'entità può essere un Account Google (per gli utenti finali) o un account di servizio (per le applicazioni e i workload di computing). Per saperne di più, consulta la pagina Ruoli e autorizzazioni per la destinazione degli eventi.

    Per ottenere le autorizzazioni necessarie per completare questo tutorial, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

    Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

    Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

    Tieni presente che, per impostazione predefinita, le autorizzazioni di Cloud Build includono le autorizzazioni per caricare e scaricare gli artefatti di Artifact Registry.

Ruoli richiesti per l'identità del trigger

  1. Prendi nota del service account predefinito di Compute Engine, perché lo collegherai a un trigger Eventarc per rappresentare l'identità del trigger a scopo di test. Questo account di servizio viene creato automaticamente dopo l'attivazione o l'utilizzo di un servizio Google Cloud che utilizza Compute Engine e con il seguente formato email:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Sostituisci PROJECT_NUMBER con il tuo numero di progetto Google Cloud. Puoi trovare il numero di progetto nella pagina Benvenuto della console Google Cloud o eseguendo questo comando:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

    Per gli ambienti di produzione, ti consigliamo vivamente di creare un nuovo service account e di concedergli uno o più ruoli IAM che contengono le autorizzazioni minime richieste e di seguire il principio del privilegio minimo.

  2. Per impostazione predefinita, i servizi Cloud Run possono essere chiamati solo da Project Owner, Project Editor e Cloud Run Admin e Invoker. Puoi controllare l'accesso in base al servizio; tuttavia, per scopi di test, concedi il ruolo Cloud Run Invoker (run.invoker) nel progetto Google Cloud al account di servizio Compute Engine. In questo modo, il ruolo viene concesso a tutti i servizi e i job Cloud Run di un progetto. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker

    Tieni presente che se crei un trigger per un servizio Cloud Run autenticato senza concedere il ruolo Invoker di Cloud Run, il trigger viene creato correttamente ed è attivo. Tuttavia, il trigger non funzionerà come previsto e nei log verrà visualizzato un messaggio simile al seguente:

    The request was not authenticated. Either allow public access or set the proper Authorization header.
  3. Concedi il ruolo Eventarc Event Receiver (roles/eventarc.eventReceiver) nel progetto al account di servizio Compute Engine predefinito in modo che il trigger Eventarc possa ricevere eventi dai provider di eventi. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver

Ruolo facoltativo per l'agente di servizio Cloud Storage

  • Prima di creare un trigger per gli eventi diretti da Cloud Storage, concedi il ruolo Publisher Pub/Sub (roles/pubsub.publisher) all'agente di servizio 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'

Ruolo facoltativo per l'agente di servizio Pub/Sub

  • Se hai attivato l'agente di servizio Cloud Pub/Sub il giorno 8 aprile 2021 o in una data precedente, per supportare le richieste push Pub/Sub autenticate, concedi il ruolo Creatore token account di servizio (roles/iam.serviceAccountTokenCreator) all'agente di servizio. In caso contrario, questo ruolo viene concesso per impostazione predefinita: 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

Crea un bucket Cloud Storage

Crea un bucket Cloud Storage da utilizzare come origine evento:

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

Scrivi una funzione basata sugli eventi

Per scrivere una funzione basata sugli eventi, segui questi passaggi:

Node.js

  1. Crea una nuova directory denominata helloGCS e accedi alla directory:

       mkdir helloGCS
   cd helloGCS

  2. Crea un file package.json nella directory helloGCS per specificare le dipendenze 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": ">=20.0.0"
  },
  "scripts": {
    "test": "c8 mocha -p -j 2 test/*.test.js --timeout=60000"
  },
  "dependencies": {
    "@google-cloud/functions-framework": "^5.0.0"
  },
  "devDependencies": {
    "c8": "^12.0.0",
    "mocha": "^10.0.0",
    "sinon": "^18.0.0",
    "supertest": "^7.0.0"
  }
}

  3. Crea un file index.js nella directory helloGCS con il seguente esempio Node.js:

    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. Crea una nuova directory denominata helloGCS e accedi alla directory:

       mkdir helloGCS
   cd helloGCS

  2. Crea un file requirements.txt nella directory helloGCS per specificare le dipendenze Python:

    functions-framework==3.9.2
cloudevents==1.11.0

    In questo modo vengono aggiunti i pacchetti necessari per l'esempio.

  3. Crea un file main.py nella directory helloGCS con il seguente esempio di Python:

    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

Esegui il deployment di una funzione basata su eventi

Esegui il deployment della funzione denominata helloworld-events eseguendo questo comando nella directory che contiene il codice campione:

Node.js 

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

Sostituisci BASE_IMAGE con l'ambiente dell'immagine di base della tua funzione, ad esempio nodejs24. Per maggiori dettagli sulle immagini di base e sui pacchetti inclusi in ogni immagine, consulta Runtime dei linguaggi e immagini di base supportati.

Python 

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

Sostituisci BASE_IMAGE con l'ambiente dell'immagine di base della tua funzione, ad esempio python314. Per maggiori dettagli sulle immagini di base e sui pacchetti inclusi in ogni immagine, consulta Runtime dei linguaggi e immagini di base supportati.

Al termine del deployment, Google Cloud CLI visualizza un URL in cui è in esecuzione il servizio.

Crea un trigger Eventarc

Il trigger Eventarc invia gli eventi dal bucket Cloud Storage al tuo servizio Cloud Run helloworld-events.

  1. Crea un trigger che filtra gli eventi 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

    Sostituisci:

    • TRIGGER_NAME con il nome del trigger.
    • PROJECT_ID con l'ID progetto Google Cloud .
    • PROJECT_NUMBER con il numero di progetto Google Cloud .

    Tieni presente che quando crei un trigger Eventarc per la prima volta in un progetto Google Cloud , potrebbe verificarsi un ritardo nel provisioning del service agent Eventarc. Questo problema di solito può essere risolto provando a creare nuovamente il trigger. Per saperne di più, consulta Errori di autorizzazione negata.

  2. Verifica che il trigger sia stato creato correttamente. Tieni presente che, sebbene il trigger venga creato immediatamente, possono essere necessari fino a due minuti prima che sia completamente funzionale.

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

    L'output dovrebbe essere simile al seguente:

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

Genera e visualizza un evento

Carica un file di testo nel bucket Cloud Storage per generare un evento che viene indirizzato alla funzione. La funzione Cloud Run registra l'evento nei log del servizio.

  1. Carica un file di testo in Cloud Storage per generare un evento:

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

    Il caricamento genera un evento e la funzione Cloud Run registra il messaggio dell'evento.

  2. Per visualizzare la voce di log:

    1. Filtra le voci di log e restituisci l'output in formato JSON:

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

    2. Cerca una voce di log simile alla seguente:

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

      La visualizzazione dei log potrebbe richiedere qualche istante. Se non li vedi subito, ricontrolla dopo un minuto.

La visualizzazione della voce di log conferma che hai eseguito correttamente il deployment di una funzione basata su eventi attivata quando un file di testo è stato caricato su Cloud Storage.

Esegui la pulizia

Se hai creato un nuovo progetto per questo tutorial, eliminalo. Se hai utilizzato un progetto esistente e vuoi conservarlo senza le modifiche aggiunte in questo tutorial, elimina le risorse create per il tutorial.

Elimina il progetto

Il modo più semplice per eliminare la fatturazione è eliminare il progetto creato per il tutorial.

Per eliminare il progetto:

  1. Nella console Google Cloud , vai alla pagina Gestisci risorse.

    Vai a Gestisci risorse

  2. Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
  3. Nella finestra di dialogo, digita l'ID progetto, quindi fai clic su Chiudi per eliminare il progetto.

Elimina le risorse del tutorial

  1. Elimina il servizio Cloud Run di cui hai eseguito il deployment in questo tutorial:

    gcloud run services delete SERVICE_NAME

    Dove SERVICE_NAME è il nome del servizio scelto.

    Puoi eliminare i servizi Cloud Run anche dalla consoleGoogle Cloud .

  2. Rimuovi le configurazioni predefinite di gcloud CLI che hai aggiunto durante la configurazione del tutorial.

    Ad esempio:

    gcloud config unset run/region

    o

    gcloud config unset project

  3. Elimina le altre risorse Google Cloud create in questo tutorial:

    • Elimina il trigger Eventarc: 
      gcloud eventarc triggers delete TRIGGER_NAME
      Sostituisci TRIGGER_NAME con il nome del trigger.

Passaggi successivi