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 a un argomento Pub/Sub di tua scelta sotto forma di messaggi. Ad esempio, puoi tenere traccia degli oggetti che vengono creati ed eliminati nel tuo bucket. Ogni notifica contiene informazioni che descrivono sia l'evento che l'ha attivata che l'oggetto modificato.
Puoi inviare notifiche a qualsiasi argomento Pub/Sub in qualsiasi progetto per il quale disponi di autorizzazioni sufficienti. Una volta ricevuti dall'argomento Pub/Sub, i sottoscrittori all'argomento possono ricevere il messaggio associato. Consulta la pagina Prerequisiti per informazioni sulla connessione dei bucket Cloud Storage a un argomento Pub/Sub.
Altre opzioni di notifica
L'iscrizione 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 leggera e autonoma in risposta agli eventi e non vuoi gestire un argomento Pub/Sub, utilizza Cloud Functions. Cloud Functions ti consente di eseguire funzioni C#, Go, Java, Node.js, Python, PHP e Ruby quando un oggetto nel tuo bucket cambia. Tieni presente che il 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: la notifica di modifica degli oggetti è una funzionalità separata e meno recente all'interno di Cloud Storage per la generazione di notifiche. Questa funzionalità invia messaggi HTTPS a un'applicazione client che hai configurato separatamente. Questa funzionalità in genere non è consigliata perché le notifiche Pub/Sub sono più economiche, più facili da usare e più flessibili.
Configurazioni delle notifiche
Una configurazione delle notifiche è 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 attivare un evento specifico.
Ad esempio, se hai una configurazione di notifica che invia notifiche di eliminazione a un argomento Pub/Sub, puoi aggiungere una seconda configurazione di notifica al bucket che invia notifiche di eliminazione a un altro argomento. Tuttavia, se provi a creare più di 10 configurazioni di notifica che lo fanno, ricevi 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. Viene restituito questo numero intero:
- Quando crei la configurazione delle notifiche.
- Quando elenchi le configurazioni delle notifiche collegate a un bucket.
- Nell'attributo
notificationConfig
di ogni notifica attivata dalla configurazione delle notifiche.
La creazione e l'eliminazione delle configurazioni di notifica incrementa 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 |
Inviata quando un nuovo oggetto (o una nuova generazione di un oggetto esistente) viene creato correttamente 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 nell'ambito della configurazione del ciclo di vita del bucket. Non sono inclusi gli oggetti che diventano non correnti (vedi OBJECT_ARCHIVE ) o l'interruzione di caricamenti multiparte. |
OBJECT_ARCHIVE |
Inviato solo quando un bucket ha abilitato il controllo delle versioni degli oggetti. Questo evento indica che la versione live di un oggetto è diventata una versione non corrente, perché è stata resa esplicitamente non corrente o perché è stata sostituita dal caricamento di un oggetto con lo stesso nome. |
Per altri eventi di Cloud Storage, ad esempio le operazioni del bucket o le letture di oggetti, puoi abilitare il tipo di audit log appropriato in Cloud Audit Logs e instradare gli audit log a Pub/Sub utilizzando un filtro.
Sostituzione di 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 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 set di coppie chiave-valore, indipendentemente dal payload della notifica:
Nome dell'attributo | Esempio | Descrizione |
---|---|---|
notificationConfig | projects/_/buckets/foo/notificationConfigs/3 |
Un identificatore della configurazione della notifica che ha attivato questa notifica. |
eventType | OBJECT_FINALIZE |
Il tipo di evento che si è appena verificato. Per l'elenco dei valori possibili, consulta la sezione Tipi di evento. |
payloadFormat | JSON_API_V1 |
Il formato del payload dell'oggetto. Vedi Payload per un elenco dei valori possibili. |
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 appartiene questa notifica. Questo attributo viene visualizzato negli eventi OBJECT_ARCHIVE o OBJECT_DELETE solo in caso di sostituzione. |
overwroteGeneration | 352947 |
Il numero di generazione dell'oggetto che è stato sostituito dall'oggetto a cui appartiene questa notifica. Questo attributo viene visualizzato negli eventi OBJECT_FINALIZE solo in caso di sostituzione. |
Oltre agli attributi riportati sopra, una configurazione di notifica può contenere fino a 10 attributi personalizzati. Gli attributi personalizzati vengono definiti durante la creazione di una
configurazione delle notifiche, utilizzando --custom-attributes
in un
comando gcloud storage
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 delle notifiche, specifichi un tipo di payload da includere nelle notifiche attivate da tale configurazione. Puoi specificare i seguenti tipi di payload:
Tipo di payload | Descrizione |
---|---|
NESSUNA | La notifica non include alcun payload. |
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 erano prima dell'eliminazione, insieme a un'ulteriore
proprietà timeDeleted
. 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 delle notifiche 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 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 notifiche associate. Una volta avviato, Cloud Storage garantisce la distribuzione "at-least-once" a Pub/Sub. Pub/Sub offre inoltre 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 è garantita la pubblicazione delle notifiche 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 precondizioni per la richiesta di aggiornamento.
Se una notifica non può essere recapitata costantemente a un argomento Pub/Sub, Cloud Storage potrebbe eliminarla dopo 7 giorni. Un errore di consegna 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
- Configura le notifiche Pub/Sub per Cloud Storage.
- Scopri di più su Pub/Sub.
- Iscriviti a un bucket per ricevere le notifiche inviate a Pub/Sub.
- Usa Cloud Functions per pubblicare eventi con un trigger di Cloud Storage.
- Utilizza le notifiche Pub/Sub per i trasferimenti basati su eventi tra i bucket Cloud Storage.