Notifiche Pub/Sub per Cloud Storage

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Vai agli esempi

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

Panoramica

Le notifiche Pub/Sub inviano informazioni sulle modifiche agli oggetti nei tuoi bucket a Pub/Sub, dove le informazioni vengono aggiunte a un argomento Pub/Sub a tua scelta sotto forma di messaggi. Ad esempio, puoi monitorare gli oggetti creati ed eliminati nel tuo bucket. Ogni notifica contiene informazioni che descrivono sia l'evento che lo ha attivato sia l'oggetto che è stato modificato.

Puoi inviare notifiche a qualsiasi argomento Pub/Sub in qualsiasi progetto per il quale disponi di autorizzazioni sufficienti. Dopo aver ricevuto l'argomento Pub/Sub, i iscritti all'argomento possono ricevere il messaggio associato. Consulta i prerequisiti per informazioni sulla connessione dei bucket Cloud Storage a un argomento Pub/Sub.

Altre opzioni di notifica

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

  • Cloud Functions: se vuoi attivare solo una funzione autonoma e leggera, in risposta agli eventi e non vuoi gestire un argomento Pub/Sub, utilizza Cloud Functions. Cloud Functions ti consente di eseguire le funzioni JavaScript, Python e Go quando un oggetto nel tuo bucket cambia. Tieni presente che il tuo bucket deve trovarsi nello stesso progetto di Cloud Functions. Guarda il tutorial associato per una dimostrazione dell'utilizzo di Cloud Functions con Cloud Storage.

  • Notifica di modifica degli oggetti: è una funzionalità separata e meno recente all'interno di Cloud Storage, che consente di generare notifiche. Questa funzione invia messaggi HTTPS a un'applicazione client che hai configurato separatamente. In genere questa funzionalità non è consigliata perché le notifiche Pub/Sub sono più economiche, facili da utilizzare e più flessibili.

Configurazioni delle notifiche

Una configurazione della notifica è una regola che colleghi a un bucket 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 collegare 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 essere attivate per un evento specifico.

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

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

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

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

Tipi di evento

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

Tipo di evento Descrizione
OBJECT_FINALIZE Inviato quando un nuovo oggetto (o una nuova generazione di un oggetto esistente) viene creato nel bucket. Sono considerate creazioni anche la copia o la riscrittura di un oggetto esistente. Questo evento non viene attivato da un caricamento non riuscito.
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 che vengono sostituiti o eliminati come parte della configurazione del ciclo di vita del bucket. Non include gli oggetti che diventano non aggiornati (vedi OBJECT_ARCHIVE) o vengono interrotti i caricamenti multiparte.
OBJECT_ARCHIVE Inviato solo quando è attivo il controllo delle versioni degli oggetti in un bucket. Questo evento indica che la versione live di un oggetto è diventata una versione non corrente, perché è stata esplicitamente resa non corrente o perché è stata sostituita dal caricamento di un oggetto con lo stesso nome.

Sostituzione di oggetti in corso...

La sostituzione di un oggetto esistente con un nuovo nome 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 che è stato 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 contenente 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 insieme di coppie chiave-valore, indipendentemente dal payload di notifica:

Nome dell'attributo Esempio Descrizione
notificationConfig projects/_/buckets/foo/notificationConfigs/3 Un identificatore della configurazione di notifica che ha attivato questa notifica.
eventType OBJECT_FINALIZE Il tipo di evento che si è appena verificato. Consulta la sezione Tipi di eventi per un elenco dei possibili valori.
payloadFormat JSON_API_V1 Il formato del payload dell'oggetto. Consulta la sezione Carico di lavoro per un elenco dei possibili valori.
bucketId foo Il nome del bucket che contiene l'oggetto modificato.
objectId (ID oggetto) bar Il nome dell'oggetto modificato.
object Generation 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.

Le notifiche contengono talvolta il seguente insieme di coppie chiave-valore, indipendentemente dal payload della notifica:

Nome dell'attributo Esempio Descrizione
con sovrascrittura 107458 Il numero di generazione dell'oggetto che ha sostituito l'oggetto a cui fa riferimento questa notifica. Questo attributo viene visualizzato solo negli eventi OBJECT_ARCHIVE o OBJECT_DELETE in caso di sostituzione.
generazione eccessiva 352947 Il numero di generazione dell'oggetto sostituito dall'oggetto a cui fa riferimento la notifica. Questo attributo viene visualizzato solo in OBJECT_FINALIZE eventi in caso di sostituzione.

La seguente coppia chiave-valore è obsoleta. Non verrà visualizzato per i nuovi abbonamenti e non apparirà in nessun abbonamento dopo il 1° giugno 2018:

Nome dell'attributo Esempio Descrizione
resource projects/_/buckets/foo/objects/bar#123456 Percorso dell'oggetto Cloud Storage modificato.

Oltre agli attributi sopra riportati, una configurazione di notifica può contenere fino a 10 attributi personalizzati. Gli attributi personalizzati sono definiti durante la creazione di una configurazione della notifica, utilizzando il flag -m in un comando gsutil notification o l'oggetto custom_attributes 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 tale configurazione. Puoi specificare i seguenti tipi di payload:

Tipo di payload Descrizione
NESSUNA Nessun payload incluso nella notifica.
JSON_API_V1 Il payload sarà una stringa UTF-8 contenente la rappresentazione delle risorse dei metadati dell'oggetto.

Per le notifiche OBJECT_DELETE, i metadati contenuti nel payload rappresentano i metadati dell'oggetto come prima dell'eliminazione, insieme a un'ulteriore proprietà timeDeleted. Per tutte le altre notifiche, i metadati inclusi nel carico dell'oggetto rappresentano i metadati dell'oggetto dopo il cambiamento.

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

Garanzie di consegna

Quando aggiungi una configurazione delle notifiche, Cloud Storage può impiegare fino a 30 secondi per iniziare a inviare le notifiche associate. Una volta avviato, Cloud Storage garantisce la consegna "almeno una volta" a Pub/Sub. Pub/Sub offre anche la consegna "almeno una volta" al destinatario, il che significa che puoi ricevere più messaggi con più ID che rappresentano lo stesso evento Cloud Storage.

Non è garantito che le notifiche vengano pubblicate nell'ordine in cui Pub/Sub le riceve. 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 condizioni preliminari nella richiesta di aggiornamento.

Se una notifica non può essere recapitata a un argomento Pub/Sub, Cloud Storage può eliminarla dopo 7 giorni. Il mancato caricamento può verificarsi quando l'argomento Pub/Sub non esiste più, quando Cloud Storage non dispone più dell'autorizzazione per pubblicare nell'argomento o quando il progetto proprietario dell'argomento supera la quota di pubblicazione.

Passaggi successivi