Creare trigger con Cloud Storage

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

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

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

Cloud Run supporta i seguenti tipi di eventi Cloud Storage:

Evento Tipo di evento Descrizione
Oggetto completato
  • 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 ulteriori informazioni, consulta Controllo delle versioni degli oggetti.
Metadati dell'oggetto aggiornati
  • 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

Imposta i ruoli obbligatori

  1. Se sei il creator del progetto, ti viene concesso il ruolo di proprietario di base (roles/owner). Per impostazione predefinita, questo ruolo IAM include le autorizzazioni necessarie per l'accesso completo alla maggior parte delle risorse Google Cloud e puoi saltare questo passaggio.

    Se non sei il creator del progetto, le autorizzazioni richieste devono essere concesse al principale appropriato. Ad esempio, un'entità può essere un Account Google (per gli utenti finali) o un account di servizio (per le applicazioni e i carichi di lavoro di calcolo). Per ulteriori informazioni, consulta la pagina Ruoli e autorizzazioni relativa alla destinazione dell'evento.

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

    Autorizzazioni obbligatorie

    Per ottenere le autorizzazioni necessarie per configurare gli attivatori Cloud Storage, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

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

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

  2. Prendi nota dell'account di servizio predefinito di Compute Engine, poiché lo collegherai a un trigger Eventarc per rappresentare l'identità dell'trigger a fini di test. Questo account di servizio viene creato automaticamente dopo aver attivato o utilizzato 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 del progetto nella pagina Welcome della console Google Cloud o eseguendo il seguente comando:

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

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

  3. Per impostazione predefinita, i servizi Cloud Run sono richiamabili solo dai proprietari, dagli editor e dagli amministratori e dagli invocatori di progetti Cloud Run. Puoi controllare l'accesso in base al servizio. Tuttavia, per scopi di test, concedi il ruolo invocatore Cloud Run (run.invoker) nel progetto Google Cloud all'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, l'trigger viene creato correttamente ed è attivo. Tuttavia, l'attivatore 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.
  4. Concedi il ruolo Riepilogatore eventi Eventarc (roles/eventarc.eventReceiver) sul progetto all'account di servizio predefinito di Compute Engine in modo che l'attivatore Eventarc possa ricevere eventi dai fornitori di eventi. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver
  5. 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 all'agente di servizio il ruolo Creatore token account di servizio (roles/iam.serviceAccountTokenCreator). 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

Creare un attivatore per i servizi

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

Fai clic sulla scheda per le istruzioni relative allo strumento che preferisci.

Console

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

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

    Vai a Cloud Run

  3. Nell'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 Attivazione Cloud Storage.

  6. Nel riquadro Trigger Eventarc, modifica i dettagli dell'attivatore come segue:

    1. Nel campo Nome attivatore, inserisci un nome per l'attivatore o utilizza il nome predefinito.

    2. Seleziona un Tipo di attivatore dall'elenco per specificare uno dei seguenti tipi di attivatore:

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

      • Di terze parti per l'integrazione con fornitori non Google che offrono un'origine Eventarc. Per ulteriori informazioni, consulta Eventi di terze parti in Eventarc.

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

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

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

    6. Se il campo Regione è attivato, seleziona una località per l'attivatore Eventarc. In generale, la posizione di un trigger Eventarc deve corrispondere alla posizione della risorsa Google Cloud per la quale vuoi monitorare gli eventi. Nella maggior parte dei casi, devi anche eseguire il deployment del servizio nella stessa regione. Consulta la sezione Informazioni sulle località Eventarc per ulteriori dettagli sulle località dei trigger Eventarc.

    7. Nel campo Account di servizio, seleziona un account di servizio. Gli attivatori Eventarc sono collegati agli account di servizio da usare come identità quando viene invocato il servizio. L'account di servizio dell'attivatore Eventarc deve disporre dell'autorizzazione per richiamare il servizio. Per impostazione predefinita, Cloud Run utilizza l'account di servizio predefinito di Compute Engine.

    8. Se vuoi, specifica il percorso dell'URL del servizio a cui inviare la richiesta in arrivo. Si tratta del percorso relativo nel servizio di destinazione a cui devono essere inviati gli eventi per l'attivatore. Ad esempio: /, /route, route e route/subroute.

    9. Dopo aver compilato i campi obbligatori, fai clic su Salva trigger.

  7. Dopo aver creato l'attivatore, verificane l'integrità assicurandoti che sia presente un segno di spunta nella scheda Attivatori.

gcloud

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

  2. Esegui il comando seguente per creare un attivatore che filtra 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 posizione per l'trigger Eventarc. In generale, la posizione di un trigger Eventarc deve corrispondere alla posizione della risorsa Google Cloud che vuoi monitorare per rilevare gli eventi. Nella maggior parte dei casi, devi anche eseguire il deployment del servizio nella stessa regione. Per ulteriori informazioni, 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. Gli attivatori Eventarc sono collegati agli account di servizio da utilizzare come identità quando viene invocato il servizio. L'account di servizio dell'attivatore 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 dall'attivatore. Un evento che corrisponde a tutti i filtri event-filters attiva le chiamate al tuo servizio. Ogni attivatore deve avere un tipo di evento supportato. Non puoi modificare il tipo di filtro evento dopo la creazione. Per modificare il tipo di filtro evento, devi creare un nuovo attivatore ed eliminare quello precedente. Se vuoi, puoi ripetere il flag --event-filters con un filtro supportato nel formato ATTRIBUTE=VALUE per aggiungere altri filtri.

Creare un trigger per le funzioni

Fai clic sulla scheda per le istruzioni relative allo strumento che preferisci.

Console

Quando utilizzi la console Google Cloud per creare una funzione, puoi anche aggiungere un trigger. Per creare un attivatore per la 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 ulteriori informazioni sulla configurazione delle funzioni durante il deployment, consulta Eseguire il deployment delle funzioni.

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

  4. Seleziona Trigger di Cloud Storage.

  5. Nel riquadro Trigger Eventarc, modifica i dettagli dell'attivatore come segue:

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

    2. Seleziona un Tipo di attivatore dall'elenco per specificare uno dei seguenti tipi di attivatore:

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

      • Di terze parti per l'integrazione con fornitori non Google che offrono un'origine Eventarc. Per ulteriori informazioni, consulta 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 Fornitori e destinazioni di eventi.

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

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

    6. Se il campo Regione è attivato, seleziona una località per l'attivatore Eventarc. In generale, la posizione di un trigger Eventarc deve corrispondere alla posizione della risorsa Google Cloud per la quale vuoi monitorare gli eventi. 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 Account di servizio, seleziona un account di servizio. Gli attivatori Eventarc sono collegati agli account di servizio da usare come identità quando viene invocata la funzione. L'account di servizio dell'attivatore Eventarc deve disporre dell'autorizzazione per richiamare la funzione. Per impostazione predefinita, Cloud Run utilizza l'account di servizio predefinito di Compute Engine.

    8. Se vuoi, specifica il percorso dell'URL del servizio a cui inviare la richiesta in arrivo. Si tratta del percorso relativo nel servizio di destinazione a cui devono essere inviati gli eventi per l'attivatore. Ad esempio: /, /route, route e route/subroute.

  6. Dopo aver compilato i campi obbligatori, fai clic su Salva trigger.

gcloud

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

  1. Esegui il seguente comando nella directory contenente il codice campione per eseguire il deployment della funzione:

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

    Sostituisci:

    • FUNCTION con il nome della funzione di cui stai eseguendo il deployment. Puoi omettere del tutto questo parametro, ma se lo fai ti verrà chiesto il nome.

    • FUNCTION_ENTRYPOINT con il punto di ingresso della funzione nel codice sorgente. Questo è il codice che Cloud Run esegue quando viene eseguita la funzione. Il valore di questo flag deve essere un nome di funzione o un nome di classe completamente qualificato esistente nel codice sorgente.

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

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

  2. Esegui il comando seguente per creare un attivatore che filtra 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 posizione per l'trigger Eventarc. In generale, la posizione di un trigger Eventarc deve corrispondere alla posizione 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 ulteriori informazioni, consulta Località Eventarc.

    • FUNCTION con il nome della funzione di cui stai eseguendo il deployment.

    • REGION con la regione Cloud Run della funzione.

    • PROJECT_NUMBER con il numero del tuo progetto Google Cloud. Gli attivatori Eventarc sono collegati agli account di servizio da utilizzare come identità quando viene invocata la funzione. L'account di servizio dell'attivatore 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 dall'attivatore. Un evento che corrisponde a tutti i filtri event-filters attiva le chiamate alla funzione. Ogni attivatore deve avere un tipo di evento supportato. Non puoi modificare il tipo di filtro evento dopo la creazione. Per modificare il tipo di filtro evento, devi creare un nuovo attivatore ed eliminare quello precedente. Se vuoi, puoi ripetere il flag --event-filters con un filtro supportato nel formato ATTRIBUTE=VALUE per aggiungere altri filtri.

Importazione di eventi

Gli attivatori Cloud Storage vengono implementati con le notifiche Pub/Sub per Cloud Storage. Gli eventi sono soggetti alle garanzie di invio 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 di notifiche del bucket fará in modo che gli ulteriori implementazioni delle funzioni non vadano a buon fine con un errore simile al seguente:

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

Per saperne di più, consulta Quote e limiti di Cloud Storage.

Passaggi successivi