Notifica di modifica degli oggetti

La notifica di modifica degli oggetti può essere utilizzata per notificare a un'applicazione quando un oggetto viene aggiornato o aggiunto a un bucket.

Dovresti utilizzare la notifica di modifica degli oggetti?

In genere, non dovresti utilizzare la notifica di modifica degli oggetti. Lo strumento consigliato per generare notifiche che monitorano le modifiche agli oggetti nei bucket Cloud Storage è Notifiche Pub/Sub per Cloud Storage, perché è più rapido, più flessibile, più facile da configurare e più conveniente. Per una guida passo passo alla configurazione delle notifiche Pub/Sub per Cloud Storage, consulta Configurazione delle notifiche Pub/Sub per Cloud Storage.

Come funziona la notifica di modifica degli oggetti

Un'applicazione client può inviare una richiesta per monitorare le modifiche agli oggetti in un determinato bucket.

Il completamento di una richiesta di visualizzazione crea un nuovo canale di notifica. Un canale di notifica è il mezzo con cui un messaggio di notifica viene inviato a un'applicazione che monitora un bucket. Al momento è supportato un solo tipo di canale di notifica, un web hook.

Dopo l'avvio di un canale di notifica, Cloud Storage invia una notifica all'applicazione ogni volta che un oggetto viene aggiunto, aggiornato o rimosso dal bucket. Ad esempio, quando aggiungi una nuova immagine a un bucket, un'applicazione potrebbe ricevere una notifica per creare una miniatura.

Dettagli della notifica di modifica degli oggetti

Terminologia

La seguente tabella contiene una descrizione di diversi termini utilizzati nella documentazione relativa alla notifica di modifica degli oggetti:

Termine Descrizione
URL applicazione L'URL della tua applicazione. Si tratta dell'indirizzo a cui verranno inviate le notifiche. Tieni presente che deve essere un URL HTTPS; gli URL HTTP non sono consentiti.
Identificatore canale L'identificatore di un canale di notifica. Deve essere univoco all'interno di un determinato bucket, ovvero se sono presenti più canali di notifica per un singolo bucket, ogni canale di notifica deve avere un identificatore distinto. Questo identificatore verrà inviato alla tua applicazione insieme a ogni messaggio di notifica.
Identificatore della risorsa Un identificatore opaco della risorsa guardata. L'identificatore della risorsa è obbligatorio per interrompere un canale di notifica. Puoi recuperare questo identificatore dalla risposta a una richiesta di visualizzazione o dall'intestazione X-Goog-Resource-Id dei messaggi di evento di notifica.
Token client (Facoltativo) I token client possono essere utilizzati per convalidare gli eventi di notifica. Per farlo, imposta un token client personalizzato con la richiesta di visualizzazione. I messaggi di notifica conterranno questo token per consentirti di verificare la loro autenticità.

Controllo di un bucket

Per iniziare a monitorare un bucket per gli eventi di notifica delle modifiche, devi effettuare una richiesta watchAll. Viene creato un canale di notifica che invia eventi di notifica al address specificato per il bucket specificato. Il canale di notifica include un token client personalizzato e un identificatore del canale, se specificato.

Un esempio di richiesta POST per monitorare un bucket:

POST /storage/v1/b/BucketName/o/watch?alt=json HTTP/1.1
Host: storage.googleapis.com
Content-Length: 200
User-Agent: google-api-python-client/1.0
Content-Type: application/json
Authorization: Bearer oauth2_token

{
  "token": "ClientToken",
  "type": "web_hook",
  "id": "ChannelId",
  "address": "ApplicationUrl"
}

Autorizzazione di notifica

Quando monitori un bucket, il canale di notifica creato verrà associato al progetto della console Google Cloud dell'applicazione che avvia la richiesta API. Ciò significa, ad esempio, che se un utente concede l'accesso a un'applicazione o un'applicazione web installata tramite un flusso OAuth2, un canale di notifica creato dall'applicazione verrà associato al progetto dell'applicazione, non al progetto contenente il bucket monitorato.

Poiché un account di servizio è associato a un progetto, se utilizzi un account di servizio per monitorare un bucket, verrà creato un canale di notifica nel progetto dell'account di servizio.

Rimozione di un canale di notifica

Per interrompere un canale di notifica, invia una richiesta stop. In questo modo vengono interrotti tutti gli eventi di notifica per la coppia di identificatori di risorsa (resourceId) e canale (id) specificata. Gli altri canali attivi per la stessa risorsa non sono interessati. Gli identificatori della risorsa e del canale sono disponibili nella risposta di una richiesta di orologio o nel corpo dei messaggi degli eventi di notifica.

Un esempio di richiesta POST per l'interruzione di un canale:

POST /storage/v1/channels/stop HTTP/1.1
Host: storage.googleapis.com
Content-Length: 200
User-Agent: google-api-python-client/1.0
Content-Type: application/json
Authorization: Bearer oauth2_token

{
  "resourceId": "ResourceId",
  "id": "ChannelId"
}

Tipi di messaggi di evento di notifica

Sincronizza

Un evento di notifica viene inviato quando viene creato un nuovo canale di notifica dopo l'invio di una richiesta di visualizzazione. Dopo aver ricevuto l'evento di sincronizzazione, tutte le modifiche successive al bucket verranno inviate all'URL dell'applicazione configurato per il canale.

La notifica verrà inviata come richiesta POST all'URL dell'applicazione configurato. La richiesta non contiene un corpo. I metadati della notifica di sincronizzazione sono contenuti nelle intestazioni della richiesta. Di seguito è riportato un esempio di richiesta di notifica sync:

POST /ApplicationUrlPath
Accept: */*
Content-Type: application/json; charset="utf-8"
Content_Length: 0
Host: ApplicationUrlHost
X-Goog-Channel-Id: ChannelId
X-Goog-Channel-Token: ClientToken
X-Goog-Resource-Id: ResourceId
X-Goog-Resource-State: sync
X-Goog-Resource-Uri: https://storage.googleapis.com/storage/v1/b/BucketName/o?alt=json

Aggiunta, aggiornamento o eliminazione di oggetti

Un evento di notifica viene inviato quando un nuovo oggetto viene aggiunto a un bucket, i contenuti o i metadati di un oggetto esistente sono stati modificati o un oggetto viene eliminato da un bucket.

La notifica verrà inviata come richiesta POST all'URL dell'applicazione configurato. Il corpo della richiesta contiene un messaggio codificato in JSON, come mostrato nella seguente richiesta di notifica: 

POST /ApplicationUrlPath
Accept: */*
Content-Length: 1097
Content-Type: application/json; charset="utf-8"
Host: ApplicationUrlHost
X-Goog-Channel-Id: ChannelId
X-Goog-Channel-Token: ClientToken
X-Goog-Resource-Id: ResourceId
X-Goog-Resource-State: ResourceState
X-Goog-Resource-Uri: https://storage.googleapis.com/storage/v1/b/BucketName/o?alt=json

{
 "kind": "storage#object",
 "id": "BucketName/ObjectName",
 "selfLink": "https://www.googleapis.com/storage/v1/b/BucketName/o/ObjectName",
 "name": "ObjectName",
 "bucket": "BucketName",
 "generation": "1367014943964000",
 "metageneration": "1",
 "contentType": "application/octet-stream",
 "updated": "2013-04-26T22:22:23.832Z",
 "size": "10",
 "md5Hash": "xHZY0QLVuYng2gnOQD90Yw==",
 "mediaLink": "https://content-storage.googleapis.com/storage/v1/b/BucketName/o/ObjectName?generation=1367014943964000&alt=media",
 "owner": {
  "entity": "user-jane@gmail.com"
 },
 "crc32c": "C7+82w==",
 "etag": "COD2jMGv6bYCEAE="
}
 dove ResourceState è:
  • exists: per l'aggiunta e l'aggiornamento degli oggetti.
  • not_exists - per le eliminazioni di oggetti.

e i contenuti del messaggio JSON contengono la rappresentazione corrente dell'oggetto come descritto in Descrizione della risorsa oggetto.

Caricamento affidabile

La notifica di modifica degli oggetti tenterà di inviare notifiche alla tua applicazione in modo affidabile. Tuttavia, tieni presente che le notifiche possono essere ritardate a tempo indeterminato e la tempestività non è garantita. Poiché la tua applicazione potrebbe non essere sempre disponibile, quando vengono inviate le notifiche vengono seguite le seguenti regole:

  • Se un tentativo di invio di una notifica non va a buon fine, verranno effettuati ulteriori tentativi. L'intervallo tra i tentativi di caricamento aggiuntivi è determinato da un algoritmo di backoff esponenziale che inizia con un nuovo tentativo 30 secondi dopo l'errore iniziale. I caricamenti successivi vengono tentati a intervalli crescenti, fino a un intervallo massimo di 90 minuti. Tieni presente che gli intervalli di ripetizione successivi sono leggermente casuali, quindi non si verificano a valori esponenziali esatti. Una volta raggiunto l'intervallo di ripetizione massimo di 90 minuti, i tentativi successivi continuano ogni 90 minuti per 7 giorni. Se la notifica non può essere inviata entro questo periodo di tempo, viene eliminata.
  • Se l'applicazione non è raggiungibile dopo 20 secondi o se risponde con uno dei seguenti codici di risposta HTTP, il tentativo di invio della notifica viene considerato un errore e viene riprovato:
    • 500 - Errore interno del server
    • 502 Bad Gateway
    • 503 Servizio non disponibile
    • Timeout del gateway (504)
  • Se la tua applicazione risponde con uno dei seguenti codici di risposta HTTP, la notifica viene considerata inviata correttamente:
    • 102 Elaborazione
    • 200 OK
    • 201 Creato
    • 202 Accettato
    • 204 Nessun contenuto
  • Eventuali altri codici di risposta HTTP restituiti dall'applicazione vengono trattati come errori permanenti e non viene eseguito alcun nuovo tentativo.

Esempio di applicazione client

Questa sezione spiega come creare un'applicazione client App Engine che elabora gli eventi di notifica delle modifiche.

L'applicazione di esempio contiene una classe denominata MainPage. Quando l'utente aggiorna o aggiunge un oggetto al bucket, la classe MainPage elabora l'evento di notifica. Per semplicità, il metodo post che esegue l'elaborazione effettiva registra solo un messaggio con l'ora di ricezione della notifica. Puoi sostituire questo codice con la logica di elaborazione effettiva. Se non hai ancora dimestichezza con lo sviluppo di applicazioni App Engine, prova a eseguire il deployment di un'app di esempio o segui un tutorial prima di procedere.

  1. Configurare l'applicazione.
    Crea il file di configurazione app.yaml per specificare l'applicazione client che gestisce gli eventi di notifica delle modifiche del bucket. 
    application: APPLICATION
version: 1
runtime: python38
api_version: 1
threadsafe: true

handlers:
- url: /.*
  script: change_notification_client.app
  2. Creazione dell'applicazione.
    L'esempio seguente implementa un'applicazione client per la gestione degli eventi di notifica delle modifiche di un bucket. Assegna il nome change_notification_client.py, quindi esegui il deployment dell'app: 
    """Notification handling for Google Cloud Storage."""

import json
import logging

import webapp2


class MainPage(webapp2.RequestHandler):
  """Process notification events."""
  def get(self):
    logging.info("Get request to notification page.")
    self.response.write("Welcome to the notification app.")

  def post(self):  # pylint: disable-msg=C6409
    """Process the notification event.

    This method is invoked when the notification channel is first created with
    a sync event, and then subsequently every time an object is added to the
    bucket, updated (both content and metadata) or removed. It records the
    notification message in the log.
    """

    logging.debug(
        '%s\n\n%s',
        '\n'.join(['%s: %s' % x for x in self.request.headers.iteritems()]),
        self.request.body)

    # The following code is for demonstration. Replace
    # it with your own notification processing code.

    if 'X-Goog-Resource-State' in self.request.headers:
      resource_state = self.request.headers['X-Goog-Resource-State']
      if resource_state == 'sync':
        logging.info('Sync message received.')
      else:
        an_object = json.loads(self.request.body)
        bucket = an_object['bucket']
        object_name = an_object['name']
        logging.info('%s/%s %s', bucket, object_name, resource_state)
    else:
      logging.info("Other post.")

logging.getLogger().setLevel(logging.DEBUG)
app = webapp2.WSGIApplication([('/', MainPage)], debug=True)
  3. Assegnazione dell'autorizzazione di accesso dell'applicazione al bucket.
    Se il bucket è di proprietà di un account di servizio diverso da quello della tua app App Engine, concedi all'PROPRIETARIO dell'applicazione l'accesso al bucket.
  4. Inizia a monitorare il bucket per rilevare le modifiche agli oggetti.
    Crea un canale di notifica per la tua applicazione monitorando il bucket utilizzando una richiesta watchAll con il address dell'URL per la tua applicazione App Engine, ad esempio https://ApplicationId.appspot.com/.
  5. Testare l'applicazione.
    Per verificare se l'applicazione funziona come previsto, segui questi passaggi:
    1. Per assicurarti che l'applicazione sia stata dispiata e funzioni correttamente, esegui il seguente comando curl: 
      curl -X Post https://APPLICATION_ID.appspot.com
       Se hai utilizzato il tuo nome di dominio per eseguire il deployment dell'applicazione, utilizzalo al posto di appspot.com nel comando precedente.
    2. Vai alla pagina Logging del progetto. Aggiorna l'elenco dei messaggi registrati, se necessario. Verifica che il messaggio di log emesso dall'applicazione sia registrato.
    3. Aggiungi un oggetto al bucket. Cloud Storage invia una notifica all'applicazione, che registra un messaggio.
    4. Vai alla pagina Logging del progetto. Aggiorna l'elenco dei messaggi registrati e trova il messaggio relativo alla copia dell'oggetto.
  6. Rimuovi il canale di notifica
    Rimuovi il canale di notifica specificando gli identificatori del canale e della risorsa restituiti quando hai emesso il comando di notifica per monitorare il bucket.