Creare trigger dagli eventi Cloud Storage

In Cloud Run, puoi attivare i servizi da Cloud Storage utilizzando Eventarc, in risposta alle modifiche in Cloud Storage.

Quando specifichi un trigger Cloud Storage per il tuo servizio, scegli un tipo di evento e specifica un bucket Cloud Storage. A seguito di questo trigger, il tuo servizio viene chiamato ogni volta che si verifica una modifica a un oggetto (file) all'interno del bucket specificato.

Affinché il servizio venga attivato da un evento su un bucket Cloud Storage, il servizio e il bucket devono trovarsi nello stesso progetto Google Cloud .

Per istruzioni dettagliate ed esempi di codice per la creazione di trigger da eventi Cloud Storage, consulta i seguenti tutorial:

Tipi di eventi Cloud Storage supportati

Cloud Run supporta i seguenti tipi di eventi Cloud Storage:

Evento Tipo di evento Descrizione
Oggetto finalizzato
  • google.cloud.storage.object.v1.finalized (tramite Eventarc)
 Si verifica quando crei un nuovo oggetto o sovrascrivi un oggetto esistente e Cloud Storage crea una nuova generazione di quell'oggetto.
Oggetto eliminato
  • google.cloud.storage.object.v1.deleted (tramite Eventarc)
 Si verifica quando elimini definitivamente un oggetto.
Oggetto archiviato
  • google.cloud.storage.object.v1.archived (tramite Eventarc)
 Si verifica quando una versione attiva di un oggetto diventa una versione non corrente. Per saperne di più, consulta la sezione Controllo delle versioni degli oggetti.
Object metadata updated
  • google.cloud.storage.object.v1.metadataUpdated (tramite Eventarc)
 Si verifica quando modifichi i metadati di un oggetto esistente.

Il repository Google Events contiene risorse aggiuntive per lavorare con i dati sugli eventi.

Prima di iniziare

  1. Assicurati di aver configurato un nuovo progetto per Cloud Run come descritto nella pagina di configurazione.

  2. Abilita le API Artifact Registry, Cloud Build, Cloud Run Admin, Eventarc, Cloud Logging, Pub/Sub e Cloud Storage:

    Abilita le API

Impostare i ruoli richiesti

Tu o il tuo amministratore dovete concedere all'account di deployment, all'identità del trigger e, facoltativamente, al service agent Pub/Sub i seguenti ruoli IAM.

Ruoli richiesti per l'account del deployer

Per ottenere le autorizzazioni necessarie per attivare eventi Cloud Storage, 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 obbligatori per l'identità del trigger

  1. Prendi nota dell'Account di servizio predefinito di Compute Engine, in quanto 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 numero del tuo 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 contengano 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 proprietari del progetto, editor del progetto e amministratori e chiamanti di Cloud Run. Puoi controllare l'accesso in base al servizio; tuttavia, a scopo di test, concedi il ruolo Invoker di Cloud Run (run.invoker) nel progetto Google Cloud all'account di servizio Compute Engine. Questo ruolo viene concesso per tutti i servizi e i job Cloud Run in 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 unauthenticated invocations or set the proper Authorization header.
  3. Concedi il ruolo Destinatario di eventi Eventarc (roles/eventarc.eventReceiver) nel progetto al account di servizio predefinito di Compute Engine 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 obbligatorio per l'agente di servizio Pub/Sub

  • Se hai attivato l'agente di servizio Cloud Pub/Sub l'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 trigger per i servizi

Puoi specificare un trigger dopo aver eseguito il deployment di un servizio.

Fai clic sulla scheda relativa alle istruzioni per l'utilizzo dello strumento che preferisci.

Console

  1. Esegui il deployment del servizio Cloud Run utilizzando container o da origine.

  2. Nella console Google Cloud , vai a Cloud Run:

    Vai a Cloud Run

  3. Dall'elenco dei servizi, fai clic su un servizio esistente.

  4. Nella pagina Dettagli servizio, vai alla scheda Trigger.

  5. Fai clic su Aggiungi attivatore e seleziona Attivatore Cloud Storage.

  6. Nel riquadro Trigger Eventarc, modifica i dettagli del trigger come segue:

    1. Nel campo Nome trigger, inserisci un nome per il trigger oppure utilizza il nome predefinito.

    2. Seleziona un tipo di trigger dall'elenco per specificare uno dei seguenti tipi di trigger:

      • Origini Google per specificare i trigger per Pub/Sub, Cloud Storage, Firestore e altri fornitori di eventi Google.

      • Terze parti per l'integrazione con provider non Google che offrono un'origine Eventarc. Per saperne di più, vedi Eventi di terze parti in Eventarc.

    3. Seleziona Cloud Storage dall'elenco Provider di eventi per selezionare un prodotto che fornisca il tipo di evento per attivare il servizio. Per l'elenco dei fornitori di eventi, consulta Provider e destinazioni di eventi.

    4. Seleziona google.cloud.storage.object.v1.finalized dall'elenco Tipo di evento. La configurazione del trigger varia a seconda del tipo di evento supportato. Per saperne di più, vedi Tipi di eventi.

    5. Nel campo Bucket, fai clic su Sfoglia per selezionare un bucket Cloud Storage da monitorare per il trigger. Le modifiche agli oggetti all'interno di questo bucket attiveranno chiamate alla tua funzione.

    6. Se il campo Regione è attivato, seleziona una posizione per il trigger Eventarc. In generale, la località di un trigger Eventarc deve corrispondere a quella della risorsa che vuoi monitorare per gli eventi. Google Cloud Nella maggior parte degli scenari, devi anche deployare il servizio nella stessa regione. Consulta la sezione Informazioni sulle località Eventarc per ulteriori dettagli sulle località dei trigger Eventarc.

    7. Nel campo Service account, seleziona un account di servizio. I trigger Eventarc sono collegati agli account di servizio da utilizzare come identità quando richiamano il servizio. Il account di servizio del trigger Eventarc deve disporre dell'autorizzazione per richiamare il servizio. Per impostazione predefinita, Cloud Run utilizza l'account di servizio predefinito di Compute Engine.

    8. (Facoltativo) Specifica il percorso dell'URL del servizio a cui inviare la richiesta in entrata. Questo è il percorso relativo nel servizio di destinazione a cui devono essere inviati gli eventi per il trigger. Ad esempio: /, /route, route e route/subroute.

    9. Una volta compilati i campi obbligatori, fai clic su Salva attivatore.

  7. Dopo aver creato il trigger, verifica il suo stato assicurandoti che sia presente un segno di spunta nella scheda Trigger.

gcloud

  1. Esegui il deployment del servizio Cloud Run utilizzando container o da origine.

  2. Esegui questo comando per creare un trigger che filtri gli eventi:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=SERVICE  \
    --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 dell'attivatore.

    • EVENTARC_TRIGGER_LOCATION con la località del trigger Eventarc. In generale, la località di un trigger Eventarc deve corrispondere a quella della risorsa Google Cloud che vuoi monitorare per gli eventi. Nella maggior parte degli scenari, devi anche eseguire il deployment del servizio nella stessa regione. Per saperne di più, consulta Località Eventarc.

    • SERVICE con il nome del servizio che stai implementando.

    • REGION con la regione Cloud Run del servizio.

    • PROJECT_NUMBER con il numero del tuo progetto Google Cloud . I trigger Eventarc sono collegati agli account di servizio da utilizzare come identità quando richiami il servizio. Il account di servizio del trigger Eventarc deve disporre dell'autorizzazione per richiamare il servizio. Per impostazione predefinita, Cloud Run utilizza l'account di servizio Compute predefinito.

    • Il flag event-filters specifica i filtri eventi monitorati dal trigger. Un evento che corrisponde a tutti i event-filters, i filtri attiva le chiamate al tuo servizio. Ogni attivatore deve avere un tipo di evento supportato. Non puoi modificare il tipo di filtro eventi dopo la creazione. Per modificare il tipo di filtro eventi, devi creare un nuovo trigger ed eliminare quello precedente. (Facoltativo) Puoi ripetere il flag --event-filters con un filtro supportato nel formato ATTRIBUTE=VALUE per aggiungere altri filtri.

Terraform

Per creare un trigger Eventarc per un servizio Cloud Run, consulta Creare un trigger utilizzando Terraform.

Crea un trigger per le funzioni

Fai clic sulla scheda relativa alle istruzioni per l'utilizzo dello strumento che preferisci.

Console

Quando utilizzi la console Google Cloud per creare una funzione, puoi anche aggiungere un trigger alla funzione. Per creare un trigger per la tua funzione:

  1. Nella console Google Cloud , vai a Cloud Run:

    Vai a Cloud Run

  2. Fai clic su Scrivi una funzione e inserisci i dettagli della funzione. Per saperne di più sulla configurazione delle funzioni durante il deployment, consulta Eseguire il deployment delle funzioni.

  3. Nella sezione Attivatore, fai clic su Aggiungi attivatore.

  4. Seleziona Trigger di Cloud Storage.

  5. Nel riquadro Trigger Eventarc, modifica i dettagli del trigger come segue:

    1. Inserisci un nome per il trigger nel campo Nome trigger o utilizza il nome predefinito.

    2. Seleziona un tipo di trigger dall'elenco per specificare uno dei seguenti tipi di trigger:

      • Origini Google per specificare i trigger per Pub/Sub, Cloud Storage, Firestore e altri fornitori di eventi Google.

      • Terze parti per l'integrazione con provider non Google che offrono un'origine Eventarc. Per saperne di più, vedi Eventi di terze parti in Eventarc.

    3. Seleziona Cloud Storage dall'elenco Provider di eventi per selezionare un prodotto che fornisca il tipo di evento per attivare la funzione. Per l'elenco dei fornitori di eventi, consulta Provider e destinazioni di eventi.

    4. Seleziona google.cloud.storage.object.v1.finalized dall'elenco Tipo di evento. La configurazione del trigger varia a seconda del tipo di evento supportato. Per saperne di più, vedi Tipi di eventi.

    5. Nel campo Bucket, fai clic su Sfoglia per selezionare un bucket Cloud Storage da monitorare per il trigger. Le modifiche agli oggetti all'interno di questo bucket attiveranno chiamate alla tua funzione.

    6. Se il campo Regione è attivato, seleziona una posizione per il trigger Eventarc. In generale, la località di un trigger Eventarc deve corrispondere a quella della risorsa che vuoi monitorare per gli eventi. Google Cloud Nella maggior parte degli scenari, devi anche eseguire il deployment della funzione nella stessa regione. Consulta la sezione Informazioni sulle località Eventarc per ulteriori dettagli sulle località dei trigger Eventarc.

    7. Nel campo Service account, seleziona un account di servizio. I trigger Eventarc sono collegati agli account di servizio da utilizzare come identità quando viene richiamata la funzione. Il account di servizio del trigger Eventarc deve disporre dell'autorizzazione per richiamare la funzione. Per impostazione predefinita, Cloud Run utilizza l'account di servizio predefinito di Compute Engine.

    8. (Facoltativo) Specifica il percorso dell'URL del servizio a cui inviare la richiesta in entrata. Questo è il percorso relativo nel servizio di destinazione a cui devono essere inviati gli eventi per il trigger. Ad esempio: /, /route, route e route/subroute.

  6. Una volta compilati i campi obbligatori, fai clic su Salva attivatore.

gcloud

Quando crei una funzione utilizzando gcloud CLI, devi prima eseguirne il deployment e poi creare un trigger. Per creare un trigger per la tua funzione:

  1. Esegui questo comando nella directory che contiene il codice campione per eseguire il deployment della funzione:

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

    Sostituisci:

    • FUNCTION con il nome della funzione che stai eseguendo il deployment. Puoi omettere completamente questo parametro, ma ti verrà chiesto il nome se lo ometti.

    • FUNCTION_ENTRYPOINT con l'entry point della tua funzione nel codice sorgente. Questo è il codice eseguito da Cloud Run quando viene eseguita la funzione. Il valore di questo flag deve essere un nome di funzione o un nome di classe completo che esiste nel codice sorgente.

    • BASE_IMAGE_ID con l'ambiente dell'immagine di base per la tua funzione. Per maggiori dettagli sulle immagini di base e sui pacchetti inclusi in ciascuna immagine, consulta Immagini di base dei runtime.

    • REGION con la Google Cloud regione in cui vuoi eseguire il deployment della funzione. Ad esempio: europe-west1.

  2. Esegui questo comando per creare un trigger che filtri gli eventi:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=FUNCTION  \
    --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 dell'attivatore.

    • EVENTARC_TRIGGER_LOCATION con la località del trigger Eventarc. In generale, la località di un trigger Eventarc deve corrispondere a quella della risorsa Google Cloud che vuoi monitorare per gli eventi. Nella maggior parte degli scenari, devi anche eseguire il deployment della funzione nella stessa regione. Per saperne di più, consulta Località Eventarc.

    • FUNCTION con il nome della funzione che stai eseguendo il deployment.

    • REGION con la regione di Cloud Run della funzione.

    • PROJECT_NUMBER con il numero del tuo progetto Google Cloud . I trigger Eventarc sono collegati agli account di servizio da utilizzare come identità quando viene richiamata la funzione. Il account di servizio del trigger Eventarc deve disporre dell'autorizzazione per richiamare la funzione. Per impostazione predefinita, Cloud Run utilizza l'account di servizio Compute predefinito.

    • Il flag event-filters specifica i filtri eventi monitorati dal trigger. Un evento che corrisponde a tutti i event-filters, i filtri attiva le chiamate alla tua funzione. Ogni attivatore deve avere un tipo di evento supportato. Non puoi modificare il tipo di filtro eventi dopo la creazione. Per modificare il tipo di filtro eventi, devi creare un nuovo trigger ed eliminare quello precedente. (Facoltativo) Puoi ripetere il flag --event-filters con un filtro supportato nel formato ATTRIBUTE=VALUE per aggiungere altri filtri.

Terraform

Per creare un trigger Eventarc per una funzione Cloud Run, consulta Creare un trigger utilizzando Terraform.

Distribuzione di eventi

I trigger Cloud Storage vengono implementati con le notifiche Pub/Sub per Cloud Storage. Gli eventi sono soggetti alle garanzie di distribuzione delle notifiche Pub/Sub.

Un bucket Cloud Storage può avere fino a 10 configurazioni di notifica impostate per attivare un evento specifico. Il superamento dei limiti delle notifiche del bucket causerà l'esito negativo di ulteriori deployment di funzioni con un errore simile al seguente:

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

Puoi aggirare questa limitazione gestendo il tuo argomento Pub/Sub e registrandolo per le notifiche Cloud Storage del tipo a cui vuoi che la tua funzione risponda. Ad esempio, puoi configurare una singola notifica per l'evento scelto (ad esempio la creazione di oggetti) in un argomento Pub/Sub. Quindi, aggiungi tutti gli abbonati alla funzione necessari all'argomento per elaborare l'evento e distribuirlo a più destinazioni. Ad esempio:

  1. Crea il tuo argomento Pub/Sub.
  2. Crea una singola configurazione di notifica nel bucket Cloud Storage che si attiva in base a un evento specifico (ad esempio OBJECT_FINALIZE per la creazione di oggetti) e invia l'evento al tuo singolo argomento Pub/Sub.
  3. Crea una o più funzioni attivate dall'argomento Pub/Sub.

Il risultato è una configurazione di notifica di Cloud Storage, un argomento Pub/Sub e tutte le funzioni necessarie (entro i limiti di consegna molto elevati consentiti da Pub/Sub).

Consulta Quote e limiti di Cloud Storage per saperne di più sulle limitazioni di Cloud Storage.

Passaggi successivi