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 tramite il quale un messaggio di notifica viene inviato a un'applicazione che controlla un bucket. Al momento è supportato un solo tipo di canale di notifica, ovvero un webhook.

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 tabella seguente 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. Questo è l'indirizzo a cui verranno inviate le notifiche. Tieni presente che deve essere un URL HTTPS. Non sono consentiti URL HTTP.
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 di risorse Un identificatore opaco per la risorsa osservata. L'identificatore della risorsa è necessario 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. A questo scopo, imposta un token client personalizzato con la tua richiesta di smartwatch. I messaggi di notifica contengono questo token per verificare che siano autentici.

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

Durante la visualizzazione di un bucket, il canale di notifica creato viene associato con il 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 installata o un'applicazione web tramite un flusso OAuth2, un canale di notifica creato dall'applicazione verrà associato al progetto dell'applicazione, non a quello contenente il bucket controllato.

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, effettua una stop richiesta. Questa operazione interrompe tutti gli eventi di notifica per la risorsa specificata identificatore di canale (resourceId) e identificatore del canale (id) . Non sono interessati canali attivi aggiuntivi per la stessa risorsa. 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.

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

Quando viene creato un nuovo canale di notifica dopo aver inviato una richiesta di visualizzazione, viene inviato un evento di notifica. 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 alcun 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 aggiunte e aggiornamenti degli oggetti.
  • not_exists - per le eliminazioni di oggetti.

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

Distribuzione affidabile

La notifica di modifica degli oggetti tenterà di consegnare le 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 Tentativi di consegna aggiuntivi sono determinati dall'evento l'algoritmo di backoff esponenziale che inizia con riprova 30 secondi dopo l'errore iniziale. I caricamenti successivi vengono tentati a intervalli crescenti, fino a un intervallo massimo di 90 minuti. Gli intervalli di ripetizione successivi vengono leggermente randomizzati, in modo che non si verifichino con 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 la tua applicazione non può essere raggiunta dopo 20 secondi o se l'applicazione risponde con uno dei seguenti codici di risposta HTTP, il tentativo di consegna della notifica viene considerato un errore e viene riprovato:
    • 500 Errore interno del server
    • 502 Bad Gateway
    • 503 Servizio non disponibile
    • 504 Timeout del gateway
  • 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
  • Tutti gli altri codici di risposta HTTP restituiti dall'applicazione vengono trattati come permanenti errori e non ne verrà riprovato.

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 la notifica è stata ricevuta. Puoi sostituire questo codice con la logica di elaborazione effettiva. Se non hanno ancora dimestichezza con lo sviluppo di applicazioni App Engine, il deployment di un'app di esempio o seguendo un tutorial prima di continua.

  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 della tua 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 osservare le modifiche agli oggetti nel bucket.
    Crea un canale di notifica per la tua applicazione osservando il bucket utilizzando un watchAll richiesta con il address dell'URL per il tuo App Engine dell'applicazione, ad esempio https://ApplicationId.appspot.com/.
  5. Test dell'Applicazione.
    Per verificare se l'applicazione funziona come previsto, segui questi passaggi:
    1. Per assicurarti che il deployment dell'applicazione sia stato eseguito e che funzioni correttamente, esegui questo comando curl: 
      curl -X Post https://APPLICATION_ID.appspot.com
       Se hai utilizzato il tuo nome di dominio per eseguire il deployment dell'applicazione, usalo invece di appspot.com nel comando precedente.
    2. Vai alla pagina Logging del progetto. Aggiorna il 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 il dei messaggi registrati e trova il messaggio relativo alla copia dell'oggetto.
  6. Rimuovi il canale di notifica
    Rimuovi il canale di notifica specificando il canale e gli identificatori di risorsa quando hai inviato il comando di notifica per osservare il bucket.