Trigger di Cloud Storage

In Cloud Functions, un trigger di Cloud Storage consente di chiamare una funzione in risposta alle modifiche in Cloud Storage. Quando specifichi un trigger di 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 a un oggetto (file) all'interno del bucket specificato.

Sono supportati i seguenti tipi di eventi Cloud Storage:

Evento Tipo di evento Descrizione
Oggetto finalizzato
  • 2ª generazione: google.cloud.storage.object.v1.finalized (tramite Eventarc)
  • 1ª generazione.: google.storage.object.finalize
 Si verifica quando viene creato un nuovo oggetto o un oggetto esistente viene sovrascritto e ne viene creata una nuova generazione.
Oggetto eliminato
  • 2ª generazione: google.cloud.storage.object.v1.deleted (tramite Eventarc)
  • 1ª generazione.: google.storage.object.delete
 Si verifica quando un oggetto viene eliminato definitivamente.
Oggetto archiviato
  • 2ª generazione: google.cloud.storage.object.v1.archived (tramite Eventarc)
  • 1ª generazione.: google.storage.object.archive
 Si verifica quando una versione live di un oggetto diventa una versione non corrente. Per ulteriori informazioni, consulta Controllo delle versioni degli oggetti.
Metadati degli oggetti aggiornati
  • 2ª generazione: google.cloud.storage.object.v1.metadataUpdated (tramite Eventarc)
  • 1ª generazione.: google.storage.object.metadataUpdate
 Si verifica quando i metadati di un oggetto esistente cambiano.

Affinché una funzione possa utilizzare un trigger di Cloud Storage, deve essere implementata come funzione basata su eventi:

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 (2nd gen), l'agente di servizio Cloud Storage deve disporre del ruolo IAM Publisher Pub/Sub (roles/pubsub.publisher) nel progetto. Questo requisito non si applica a Cloud Functions (1ª generazione).

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 consulta quanto segue per ulteriori informazioni specifiche sulla configurazione dei trigger di Cloud Storage durante il deployment.

gcloud

Se esegui il deployment con 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 verrà monitorato dal trigger. 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 tentate automaticamente di nuovo. Per ulteriori informazioni, consulta Riprovare le funzioni basate su eventi.

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

  • Per Cloud Functions (2nd gen):

    gcloud functions deploy YOUR_FUNCTION_NAME \
--gen2 \
--trigger-event-filters="type=EVENT_TYPE" \
--trigger-event-filters="bucket=YOUR_STORAGE_BUCKET" \
...

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

  • Per Cloud Functions (1ª generazione.):

    gcloud functions deploy YOUR_FUNCTION_NAME \
--trigger-event=EVENT_TYPE \
--trigger-resource=YOUR_STORAGE_BUCKET \
...

Eventi Cloud Storage legacy

Le funzioni legacy in Cloud Functions (1ª generazione) utilizzano le notifiche di modifica degli oggetti legacy per i trigger di Cloud Storage:

gcloud functions deploy YOUR_FUNCTION_NAME \
--trigger-event=providers/cloud.storage/eventTypes/object.change \
--trigger-resource=YOUR_STORAGE_BUCKET \
...

Questo tipo di evento è supportato per le funzioni legacy che utilizzano già questi eventi. Tuttavia, sconsigliamo di utilizzare questo tipo di evento perché potrebbe essere rimosso in futuro.

Console

Se stai eseguendo il deployment utilizzando la console Google Cloud, puoi configurare un trigger di Cloud Storage nella sezione Trigger.

  • Per Cloud Functions (2nd gen):

    1. Nel campo Tipo di attivatore, 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 del trigger per un trigger Eventarc.

    3. Nel campo Bucket, fai clic su Sfoglia per selezionare un bucket Cloud Storage da monitorare con il 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 ulteriori informazioni, consulta Riprovare le funzioni basate su eventi.

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

      • Nel campo Tipo di attivatore, specifica una delle seguenti opzioni: Origini Google, Personalizzato o Terze parti:

        • Con le origini Google puoi specificare trigger per Pub/Sub, Cloud Storage, Firestore e altri provider di eventi Google.Nel riquadro Trigger Eventarc, utilizza il campo Provider di eventi per selezionare il prodotto che fornisce il tipo di evento che vuoi attivare per la funzione. Nel campo Evento, seleziona l'evento che vuoi utilizzare come attivatore.

        • L'opzione Personalizzato 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 fornire 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 consente l'integrazione con provider non Google che offrono un'origine Eventarc. Per i 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à del trigger Eventarc. Per ulteriori informazioni, consulta Identità attivatore.

    6. Fai clic su Salva attivatore.

  • Per Cloud Functions (1ª generazione.):

    1. Nel campo Tipo di attivatore, seleziona Cloud Storage.
    2. Nel campo Tipo di evento, seleziona un tipo di evento.
    3. Nel campo Bucket, fai clic su Sfoglia per selezionare un bucket Cloud Storage da monitorare con il 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 stabilire se ripetere automaticamente le chiamate di funzione non riuscite. Per ulteriori informazioni, consulta Riprovare le funzioni basate su eventi.

Distribuzione eventi

I trigger di Cloud Storage vengono implementati con le notifiche Pub/Sub per Cloud Storage. Gli eventi sono soggetti alle garanzia di recapito 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 causa un errore di deployment delle funzioni come il seguente:

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

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

Passaggi successivi