Notifiche Pub/Sub per Cloud Storage

Configurazione

Questa pagina fornisce una panoramica delle notifiche Pub/Sub per di archiviazione ideale in Cloud Storage.

Panoramica

Le notifiche Pub/Sub inviano informazioni sulle modifiche a oggetti nei tuoi bucket in Pub/Sub, dove vengono aggiunte le informazioni in 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 ha attivato e dell'oggetto che è stato modificato.

Puoi inviare notifiche a qualsiasi argomento Pub/Sub in qualsiasi progetto per per i quali disponi di autorizzazioni sufficienti. Una volta ricevuto dal all'argomento Pub/Sub, i sottoscrittori all'argomento possono ricevere messaggio associato. Per informazioni su come connettere il tuo smartphone, consulta la sezione Prerequisiti 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. Le seguenti sono disponibili anche le seguenti opzioni:

  • Funzioni Cloud Run: se vuoi attivare solo una funzione autonoma e leggera in risposta agli eventi e non vuoi gestire un argomento Pub/Sub, utilizza le funzioni Cloud Run. Le funzioni di Cloud Run consentono di eseguire C#, Go, Java, Node.js, Python, Le funzioni PHP e Ruby quando un oggetto nel tuo bucket cambia. Tieni presente che il bucket deve trovarsi nello stesso progetto delle funzioni Cloud Run. Consulta il tutorial associato per una dimostrazione dell'utilizzo delle funzioni Cloud Run con Cloud Storage.

  • Notifica di modifica degli oggetti: si tratta di una funzionalità precedente e separata di Cloud Storage per la generazione di notifiche. Questa funzionalità invia messaggi HTTPS a un'applicazione client configurata separatamente. Generalmente questa funzione è sconsigliata perché Le notifiche Pub/Sub sono più economiche, più facili da usare più flessibile.

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 in tutto 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 al bucket una seconda configurazione di notifica che invii notifiche di eliminazione a un altro argomento. Tuttavia, se tenti di creare più di 10 configurazioni di notifiche che eseguono questa operazione, viene visualizzato un errore. Oltre a questi configurazioni delle notifiche, puoi anche creare configurazioni che inviano notifiche per altri eventi, come la creazione di oggetti, a gli argomenti Pub/Sub utilizzati dalle notifiche di eliminazione oppure per argomenti diversi.

Ogni configurazione di notifica è identificata da un 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 dal 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 Inviato quando un nuovo oggetto (o una nuova generazione di un oggetto esistente) viene creato correttamente nel bucket. Ciò include la copia, la riscrittura o il ripristino 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 i caricamenti suddivisi in più parti interrotti.
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 Cloud Storage, come operazioni sui bucket o letture di oggetti, puoi attivare il tipo di log di controllo appropriato in Cloud Audit Logs e indirizzare 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 sostituito. La L'evento OBJECT_ARCHIVE o OBJECT_DELETE contiene un attributo aggiuntivo overwrittenByGeneration, che fornisce il numero di generazione del nuovo .

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 al tuo argomento Pub/Sub. Notifiche sempre contengono il seguente set di coppie chiave:valore, indipendentemente dallo stato della notifica payload:

Nome 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. Consulta Payload per un elenco dei possibili valori.
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 insieme di coppie chiave:valore, a prescindere dal payload della notifica:

Nome 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 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 precedenti, una configurazione di notifica può contenere fino a 10 attributi personalizzati. Gli attributi personalizzati vengono definiti quando 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 includi nelle notifiche attivate da quella configurazione. Puoi specificare i seguenti tipi di payload:

Tipo di payload Descrizione
NONE 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 così come erano prima dell'eliminazione, insieme a un'altra proprietà OBJECT_DELETE. Per tutte le altre notifiche, i metadati inclusi nei rappresenta i metadati dell'oggetto dopo un cambiamento.

Ad esempio, supponiamo che tu abbia una configurazione delle notifiche monitora eventi di 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 occupare a 30 secondi per iniziare a inviare notifiche associate. Una volta iniziato, Cloud Storage garantisce la consegna "at-least-once" ai in Pub/Sub. Pub/Sub offre anche la consegna almeno una volta 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 vengono ricevute da Pub/Sub. Se prevedi di modificare il file di Cloud Storage in base a una notifica, è consigliabile utilizzare il metodo numeri di generazione e metagenerazione come precondizioni per la richiesta di aggiornamento.

Se una notifica non può essere recapitata costantemente a un Pub/Sub , Cloud Storage potrebbe eliminare la notifica dopo 7 giorni. Consegna a domicilio l'errore può verificarsi quando l'argomento Pub/Sub non esiste più, 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