Notifiche Pub/Sub per Cloud Storage

Configurazione

Questa pagina fornisce una panoramica delle notifiche Pub/Sub per Cloud Storage.

Panoramica

Le notifiche Pub/Sub inviano informazioni sulle modifiche apportate agli oggetti nei bucket a Pub/Sub, dove vengono aggiunte all'argomento Pub/Sub scelto da te sotto forma di messaggi. Ad esempio, puoi monitorare gli oggetti creati ed eliminati nel bucket. Ogni notifica contiene informazioni che descrivono sia l'evento che l'ha attivata sia l'oggetto modificato.

Puoi inviare notifiche a qualsiasi argomento Pub/Sub in qualsiasi progetto per il quale hai le autorizzazioni necessarie. Una volta ricevuto dall' argomento Pub/Sub, gli abbonati all'argomento possono ricevere il messaggio associato. Per informazioni su come connettere i tuoi bucket Cloud Storage a un argomento Pub/Sub, consulta Configurare le notifiche Pub/Sub per Cloud Storage.

Altre opzioni di notifica

L'abbonamento alle notifiche Pub/Sub è un modo versatile per attivare avvisi e azioni in risposta alle modifiche apportate a un bucket. Sono disponibili anche le seguenti opzioni:

  • Cloud Run Functions: se vuoi attivare solo una funzione leggera e autonoma in risposta agli eventi e non vuoi gestire un argomento Pub/Sub, utilizza Cloud Run Functions. Cloud Run Functions ti consente di eseguire funzioni C#, Go, Java, Node.js, Python, PHP e Ruby quando un oggetto nel bucket viene modificato. Tieni presente che il bucket deve risiedere nello stesso progetto di Cloud Run Functions. Per una dimostrazione dell'utilizzo di Cloud Run Functions con Cloud Storage,consulta il tutorial associato.

Configurazioni delle notifiche

Una configurazione di notifica è una regola che associ a un bucket e che specifica:

  • L'argomento in Pub/Sub che riceve le notifiche.
  • Gli eventi che attivano l'invio di una notifica.
  • Le informazioni contenute nelle notifiche.

Puoi associare più configurazioni di notifica a un bucket. Un bucket può avere fino a 100 configurazioni di notifica totali e fino a 10 configurazioni di notifica impostate per attivare un evento specifico.

Ad esempio, se hai una configurazione di notifica che invia le notifiche di eliminazione a un argomento Pub/Sub, puoi aggiungere una seconda configurazione di notifica al bucket che invia le notifiche di eliminazione a un altro argomento. Tuttavia, se provi a creare più di 10 configurazioni di notifica che eseguono questa operazione, riceverai un errore. Oltre a queste configurazioni di notifica, puoi anche creare configurazioni di notifica che inviano notifiche per altri eventi, come la creazione di oggetti, agli argomenti Pub/Sub utilizzati dalle notifiche di eliminazione o ad argomenti diversi.

Ogni configurazione di notifica è identificata da un numero intero. Questo numero intero viene restituito:

  • Quando crei la configurazione di notifica.
  • Quando elenchi le configurazioni di notifica associate a un bucket.
  • Nell'attributo notificationConfig di ogni notifica attivata dalla configurazione di notifica.

La creazione e l'eliminazione delle configurazioni di notifica incrementano il numero di metagenerazione di un bucket.

Tipi di evento

Di seguito è riportato un elenco dei tipi di eventi supportati da Cloud Storage:

Tipo di evento Descrizione
OBJECT_FINALIZE Inviato in caso di corretta creazione di un nuovo oggetto (o di nuova generazione di un oggetto esistente) nel bucket. Sono inclusi la copia, la riscrittura o il ripristino di un oggetto esistente. È inclusa anche la finalizzazione di un oggetto in un bucket zonale. Questo evento non viene attivato da un caricamento non riuscito.
OBJECT_INITIALIZE Inviato quando inizia la creazione di un oggetto in un bucket zonale.
OBJECT_METADATA_UPDATE Inviato in caso di variazioni nei metadati di un oggetto esistente.
OBJECT_DELETE Inviato quando un oggetto è stato eliminato definitivamente. Sono inclusi gli oggetti sostituiti o eliminati nell'ambito della configurazione del ciclo di vita del bucket . Non sono inclusi gli oggetti che diventano non aggiornati (vedi OBJECT_ARCHIVE) o i caricamenti in più parti interrotti.
OBJECT_ARCHIVE Inviato solo quando è abilitato il controllo delle versioni degli oggetti nel bucket. Questo evento indica che la versione live di un oggetto è diventata una versione non aggiornata, o perché è stata resa esplicitamente non aggiornata o perché è stata sostituita dal caricamento di un oggetto con lo stesso nome.

Per altri eventi Cloud Storage, come le operazioni sui bucket o le letture degli oggetti, puoi attivare il tipo appropriato di audit log in Cloud Audit Logs e indirizzare gli audit log a Pub/Sub utilizzando un filtro.

Sostituzione degli oggetti

La sostituzione di un oggetto esistente con uno nuovo con lo stesso nome attiva due eventi separati: OBJECT_FINALIZE per la nuova versione dell'oggetto e OBJECT_ARCHIVE o OBJECT_DELETE per l'oggetto sostituito. L'evento OBJECT_FINALIZE contiene un attributo aggiuntivo overwroteGeneration, che fornisce il numero di generazione dell'oggetto sostituito. L'evento OBJECT_ARCHIVE o OBJECT_DELETE contiene un attributo aggiuntivo overwrittenByGeneration, che fornisce il numero di generazione del nuovo oggetto.

Formato delle notifiche

Le notifiche inviate all'argomento Pub/Sub sono composte da due parti:

  • Attributi: un set di coppie chiave:valore che descrivono l'evento.
  • Payload: una stringa che contiene i metadati dell'oggetto modificato.

Attributi

Gli attributi sono coppie chiave:valore contenute in tutte le notifiche inviate da Cloud Storage all'argomento Pub/Sub. Le notifiche contengono sempre il seguente set di coppie chiave:valore, indipendentemente dal payload della notifica:

Nome dell'attributo Esempio Descrizione
notificationConfig projects/_/buckets/foo/notificationConfigs/3 Un identificatore per la configurazione di notifica che ha attivato questa notifica.
eventType OBJECT_FINALIZE Il tipo di evento appena verificatosi. Per un elenco dei valori possibili, consulta Tipi di evento.
payloadFormat JSON_API_V1 Il formato del payload dell'oggetto. Per un elenco dei valori possibili, consulta Payload.
bucketId foo Il nome del bucket che contiene l'oggetto modificato.
objectId bar Il nome dell'oggetto modificato.
objectGeneration 123456 Il numero di generazione dell'oggetto modificato.
eventTime 2021-01-15T01:30:15.01Z L'ora in cui si è verificato l'evento, espressa nel formato RFC 3339.

A volte le notifiche contengono il seguente set di coppie chiave:valore, indipendentemente dal payload della notifica:

Nome dell'attributo Esempio Descrizione
overwrittenByGeneration 107458 Il numero di generazione dell'oggetto che ha sostituito l'oggetto a cui si riferisce questa notifica. Questo attributo viene visualizzato solo negli eventi OBJECT_ARCHIVE o OBJECT_DELETE in caso di sostituzione.
overwroteGeneration 352947 Il numero di generazione dell'oggetto sostituito dall'oggetto a cui si riferisce questa notifica. Questo attributo viene visualizzato solo negli eventi OBJECT_FINALIZE in caso di sostituzione.

Oltre agli attributi sopra indicati, una configurazione di notifica può contenere fino a 10 attributi personalizzati. Gli attributi personalizzati vengono definiti durante la creazione di una configurazione di notifica, utilizzando --custom-attributes in un gcloud storage comando o l'custom_attributes oggetto nel corpo di una richiesta JSON POST notificationConfigs.

Payload

Il payload è una stringa che contiene i metadati dell'oggetto modificato. Quando crei una configurazione di notifica, devi specificare un tipo di payload da includere nelle notifiche attivate da quella configurazione. Puoi specificare i seguenti tipi di payload:

Tipo payload Descrizione
NONE Nessun payload è incluso nella notifica.
JSON_API_V1 Il payload sarà una stringa UTF-8 contenente la rappresentazione della risorsa dei metadati dell'oggetto.

Per le notifiche OBJECT_DELETE, i metadati contenuti nel payload rappresentano i metadati dell'oggetto così come erano prima dell'eliminazione, insieme a una proprietà timeDeleted aggiuntiva. Per tutte le altre notifiche, i metadati inclusi nel payload rappresentano i metadati dell'oggetto dopo la modifica.

Ad esempio, supponiamo che tu abbia una configurazione di notifica che monitora gli eventi OBJECT_METADATA_UPDATE. Se un utente modifica la contentType proprietà di un oggetto da binary/octet-stream a video/mp4, viene inviata una notifica OBJECT_METADATA_UPDATE e i metadati nel payload includono "contentType":"video/mp4".

Garanzie di consegna

Quando aggiungi una configurazione di notifica, Cloud Storage potrebbe impiegare fino a 30 secondi per iniziare a inviare le notifiche associate. Una volta avviato, Cloud Storage garantisce la consegna "at least once" a Pub/Sub. Pub/Sub offre anche la consegna "at least once" al destinatario, il che significa che potresti ricevere più messaggi, con più ID, che rappresentano lo stesso evento Cloud Storage.

Non è garantito che le notifiche vengano pubblicate nell'ordine in cui le riceve Pub/Sub. Se prevedi di modificare l'oggetto Cloud Storage in base a una notifica, ti consigliamo di utilizzare i numeri di generazione e metagenerazione dell'oggetto come precondizioni nella richiesta di aggiornamento.

Se una notifica non può essere consegnata in modo coerente a un argomento Pub/Sub, Cloud Storage potrebbe eliminarla dopo 7 giorni. L'errore di consegna può verificarsi quando l'argomento Pub/Sub non esiste più, quando Cloud Storage non ha più l'autorizzazione per pubblicare nell'argomento o quando il progetto proprietario dell'argomento supera la quota di pubblicazione.

Passaggi successivi