Trigger di Cloud Storage

Nelle funzioni Cloud Run, un attivatore 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 specifichi un bucket Cloud Storage. La funzione verrà chiamata ogni volta che si verifica una modifica in un oggetto (file) all'interno del bucket specificato.

Sono supportati 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 viene creato un nuovo oggetto o viene sovrascritto un oggetto esistente 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 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 i metadati di un oggetto esistente cambiano.

Un attivatore Cloud Storage viene implementato come funzione CloudEvent, in cui i dati dell'evento Cloud Storage vengono passati alla funzione nel formato CloudEvents e il payload dei dati CloudEvent è di tipo StorageObjectData.

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

Autorizzazioni

Per utilizzare gli attivatori Cloud Storage nelle funzioni Cloud Run, l'agente di servizio Cloud Storage deve disporre del ruolo IAM Publisher Pub/Sub (roles/pubsub.publisher) nel tuo progetto.

Deployment

Puoi specificare un trigger Cloud Storage quando esegui il deployment di una funzione. Consulta Eseguire il deployment di una funzione Cloud Run per istruzioni generali su come eseguire il deployment di una funzione e consulta quanto segue per informazioni aggiuntive specifiche sulla configurazione degli attivatori Cloud Storage durante il deployment.

gcloud

Se esegui il deployment utilizzando l'interfaccia a riga di comando gcloud, puoi utilizzare il tipo di evento Object finalized (Oggetto completato) 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 verrà monitorato dall'attivatore. Gli eventi Object finalized all'interno di questo bucket attiveranno le chiamate alla funzione.
  • Il --retry flag controlla se le chiamate di funzione non riuscite vengono tentate automaticamente di nuovo. Per ulteriori informazioni, consulta Riprovare le funzioni basate su eventi.

Per utilizzare tipi di eventi diversi da Object finalized (Oggetto completato), utilizza 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 iniziale gs://, ad esempio --trigger-event-filters="bucket=my-bucket".

Console

Se esegui il deployment utilizzando la console Google Cloud, puoi configurare un attivatore Cloud Storage nella sezione Attivati:

  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, consulta le istruzioni di configurazione dell'trigger Eventarc.

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

  4. Seleziona o deseleziona la casella di controllo Riprova in caso di errore per controllare se le funzioni Cloud Run tentano automaticamente di nuovo un richiamo di funzione non riuscito. Per ulteriori informazioni, consulta la sezione Riprovare le funzioni basate su eventi.

  5. Fai clic su Altre opzioni per eseguire una configurazione aggiuntiva sull'attivatore:

    • Nel campo Tipo di trigger, specifica una delle opzioni Origini Google, Personalizzato o Di terze parti:

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

      • L'opzione Personalizzato ti consente di produrre e utilizzare eventi dal codice dell'applicazione. Segui le istruzioni nel riquadro Trigger Eventarc per creare un canale. Un canale è una risorsa utilizzata come pipeline per pubblicare eventi personalizzati dai produttori ai consumatori. Gli eventi personalizzati vengono pubblicati in un canale e un trigger Eventarc si iscrive a questi eventi.

      • L'opzione Di terze parti ti consente di eseguire l'integrazione con provider non Google che offrono un'origine Eventarc. Per maggiori dettagli, consulta 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à dell'attivatore Eventarc. Per ulteriori informazioni, consulta Identità trigger.

  6. Fai clic su Salva trigger.

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