Trigger di Cloud Storage (2ª generazione)

In Cloud Functions, un trigger di Cloud Storage consente di chiamare una funzione in risposta alle modifiche in Cloud Storage. Quando specifichi un trigger Cloud Storage per una funzione, scegli un tipo di evento e specifica un bucket Cloud Storage. La tua funzione verrà chiamata ogni volta che si verifica una modifica su un oggetto (file) all'interno del bucket specificato.

Sono supportati i seguenti tipi di eventi di Cloud Storage:

Evento Tipo di evento Descrizione
Oggetto finalizzato
  • google.cloud.storage.object.v1.finalized (tramite Eventarc)
 Si verifica quando viene creato un nuovo oggetto oppure un oggetto esistente viene sovrascritto e viene creata una nuova generazione di quell'oggetto.
Oggetto eliminato
  • google.cloud.storage.object.v1.deleted (tramite Eventarc)
 Si verifica quando un oggetto viene eliminato definitivamente.
Oggetto archiviato
  • google.cloud.storage.object.v1.archived (tramite Eventarc)
 Si verifica quando una versione live 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 i metadati di un oggetto esistente vengono modificati.

Un trigger di Cloud Storage viene implementato come funzione CloudEvent, con cui i dati degli eventi Cloud Storage vengono passati alla tua funzione nel formato CloudEvents e il payload dei dati CloudEvent è di tipo StorageObjectData.

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

Autorizzazioni

Per utilizzare i trigger di Cloud Storage in Cloud Functions, l'agente di servizio Cloud Storage deve avere il ruolo IAM Publisher Pub/Sub (roles/pubsub.publisher) nel progetto.

Deployment

Puoi specificare un trigger di Cloud Storage quando esegui il deployment di una funzione. Consulta Eseguire il deployment di una funzione Cloud Functions per istruzioni generali su come eseguire il deployment di una funzione e di seguito per ulteriori informazioni specifiche sulla configurazione dei trigger di Cloud Storage durante il deployment.

gcloud

Se stai eseguendo il deployment utilizzando gcloud CLI, puoi utilizzare il tipo di evento Oggetto finalizzato di Cloud Storage con i seguenti flag:

gcloud functions deploy YOUR_FUNCTION_NAME \
--trigger-bucket=YOUR_STORAGE_BUCKET \
[--retry] \
...
  • Il flag --trigger-bucket specifica il bucket Cloud Storage che il trigger monitorerà. Gli eventi oggetto finalizzato all'interno di questo bucket attiveranno le chiamate alla tua funzione.
  • Il flag --retry controlla se le chiamate di funzione non riuscite vengono ritentate automaticamente. Per ulteriori informazioni, consulta Ripetere le funzioni basate su eventi.

Per utilizzare tipi di eventi diversi da Oggetto finalizzato, usa i seguenti flag:

  gcloud functions deploy YOUR_FUNCTION_NAME 

  --gen2 

  --trigger-event-filters="type=EVENT_TYPE" 

  --trigger-event-filters="bucket=YOUR_STORAGE_BUCKET" 

  ...

Quando esegui il deployment delle funzioni, specifica solo il nome del bucket senza il carattere gs:// iniziale, ad esempio --trigger-event-filters="bucket=my-bucket".

Console

Se esegui il deployment utilizzando la console Google Cloud, puoi configurare un trigger di Cloud Storage nella sezione Trigger:

  1. Nel campo Tipo di trigger, scegli Cloud Storage.

  2. Nel campo Tipo di evento, scegli un evento di attivazione. Il valore predefinito è google.cloud.storage.object.v1.finalized.

    Per un evento Cloud Storage che utilizza Cloud Audit Logs, fai riferimento alle istruzioni di configurazione del trigger per un trigger Eventarc.

  3. 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 tua funzione.

  4. Seleziona o deseleziona la casella di controllo Riprova in caso di errore per controllare se Cloud Functions ritenta automaticamente una chiamata di funzione non riuscita. Per saperne di più, consulta Ripetere le funzioni basate su eventi.

  5. Fai clic su Altre opzioni per eseguire un'ulteriore configurazione sul trigger:

    • Nel campo Tipo di attivatore, specifica una tra Origini Google, Personalizzato o Di terze parti:

      • Le origini Google consentono di specificare trigger per Pub/Sub, Cloud Storage, Firestore e altri provider di eventi Google.Nel riquadro Trigger Eventarc, utilizza il campo Provider eventi per selezionare il prodotto che fornisce il tipo di evento che desideri attivare la funzione. Quindi, nel campo Evento, seleziona l'evento da utilizzare come trigger.

      • L'opzione Personalizzato consente di produrre e utilizzare eventi dal codice della tua applicazione. Segui le istruzioni nel riquadro Trigger Eventarc per creare un canale. Un canale è una risorsa utilizzata come pipeline per distribuire eventi personalizzati dai producer ai consumer. Gli eventi personalizzati vengono pubblicati su un canale e un trigger Eventarc si abbona a questi eventi.

      • L'opzione Di terze parti consente l'integrazione con provider non Google che offrono un'origine Eventarc. Per maggiori dettagli, consulta gli eventi di terze parti in Eventarc.

    • Nel campo Evento, seleziona un evento di attivazione. Il valore predefinito è google.cloud.storage.object.v1.finalized.

    • Facoltativamente, nel campo Account di servizio, seleziona un account di servizio da utilizzare come identità del trigger Eventarc. Per ulteriori informazioni, consulta Identità trigger.

  6. Fai clic su Salva trigger.

Consegna di eventi

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

In un bucket Cloud Storage possono essere impostate fino a 10 configurazioni di notifica che si attivano per un evento specifico. Il superamento dei limiti di notifiche del bucket comporterà l'esito negativo di ulteriori deployment delle funzioni e genererà un errore come il seguente:

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

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

Passaggi successivi