Notifiche per le modifiche alle risorse

Questo documento descrive come utilizzare le notifiche push che informano la tua applicazione quando una risorsa cambia.

Panoramica

L'API Google Drive fornisce notifiche push che ti consentono di monitorare le modifiche nelle risorse. Puoi utilizzare questa funzionalità per migliorare il rendimento della tua applicazione. Ti consente di eliminare i costi aggiuntivi di rete e di calcolo associati al polling delle risorse per determinare se sono cambiate. Ogni volta che una risorsa monitorata cambia, l'API Google Drive invia una notifica alla tua applicazione.

Per utilizzare le notifiche push, devi fare due cose:

• Configura l'URL di ricezione o il ricevitore del callback "webhook".

  Si tratta di un server HTTPS che gestisce i messaggi di notifica dell'API attivati quando una risorsa cambia.

• Configura un canale di notifica per ogni endpoint della risorsa che vuoi monitorare.

  Un canale specifica le informazioni di instradamento per i messaggi di notifica. Nell'ambito della configurazione del canale, devi identificare l'URL specifico su cui vuoi ricevere le notifiche. Ogni volta che la risorsa di un canale cambia, l'API Google Drive invia un messaggio di notifica come richiesta POST a quell'URL.

Nota: la parola "canale", così come utilizzata in questo documento, si riferisce specificamente a un canale di notifica e non ad altri tipi di canali utilizzati in questa API o in questo servizio. È possibile attivare più canali di notifica contemporaneamente per la stessa risorsa.

Attualmente, l'API Google Drive supporta le notifiche per le modifiche ai metodi files e changes.

Creare canali di notifica

Per richiedere notifiche push, devi configurare un canale di notifica per ogni risorsa da monitorare. Una volta configurati i canali di notifica, l'API Google Drive informa la tua applicazione quando una risorsa monitorata cambia.

Inviare richieste per gli smartwatch

A ogni risorsa dell'API Google Drive visibile è associato un metodo watch in un URI del seguente formato:

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

Per configurare un canale di notifica per i messaggi relativi alle modifiche apportate a una determinata risorsa, invia una richiesta POST al metodo watch della risorsa.

Ogni canale di notifica è associato sia a un determinato utente sia a una determinata risorsa (o insieme di risorse). Una richiesta watch non andrà a buon fine a meno che l'utente corrente o l'account di servizio non sia proprietario di questa risorsa o non disponga dell'autorizzazione per accedervi.

Esempi

Il seguente esempio di codice mostra come utilizzare una risorsa channels per iniziare a rilevare le modifiche a una singola risorsa files utilizzando il metodo files.watch:

POST https://www.googleapis.com/drive/v3/files/fileId/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your files channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time.
}

Il seguente esempio di codice mostra come utilizzare una risorsa channels per iniziare a monitorare tutti gli eventi changes utilizzando il metodo changes.watch:

POST https://www.googleapis.com/drive/v3/changes/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a77", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myChangesChannelDest", // (Optional) Your changes channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time.
}

Proprietà obbligatorie

Con ogni richiesta watch, devi fornire i seguenti campi:

• Una stringa di proprietà id che identifica in modo univoco questo nuovo canale di notifica all'interno del progetto. Ti consigliamo di utilizzare un identificatore univoco universale (UUID) o qualsiasi stringa univoca simile. Lunghezza massima: 64 caratteri.

  Il valore ID impostato viene riportato nell'X-Goog-Channel-Id intestazione HTTP di ogni messaggio di notifica che ricevi per questo canale.

• Una stringa di proprietà type impostata sul valore web_hook.

• Una stringa di proprietà address impostata sull'URL che ascolta e risponde alle notifiche per questo canale di notifica. Si tratta del tuo URL di callback webhook e deve utilizzare HTTPS.

  Tieni presente che l'API Google Drive è in grado di inviare notifiche a questo indirizzo HTTPS solo se sul tuo server web è installato un certificato SSL valido. I certificati non validi includono:

  • Certificati autofirmati.
  • Certificati firmati da una fonte non attendibile.
  • Certificati revocati.
  • Certificati con un oggetto che non corrisponde al nome host di destinazione.

Proprietà facoltative

Puoi anche specificare questi campi facoltativi con la richiesta watch:

• Una proprietà token che specifica un valore di stringa arbitrario da utilizzare come token del canale. Puoi utilizzare i token del canale di notifica per vari scopi. Ad esempio, puoi utilizzare il token per verificare che ogni messaggio in arrivo sia per un canale creato dall'applicazione (per garantire che la notifica non sia oggetto di spoofing) o per indirizzare il messaggio alla destinazione corretta all'interno dell'applicazione in base allo scopo di questo canale. Lunghezza massima: 256 caratteri.

  Il token è incluso nell'X-Goog-Channel-Token intestazione HTTP di ogni messaggio di notifica che la tua applicazione riceve per questo canale.

  Se utilizzi i token del canale di notifica, ti consigliamo di:

  • Utilizza un formato di codifica estensibile, ad esempio i parametri di query dell'URL. Esempio: forwardTo=hr&createdBy=mobile

  • Non includere dati sensibili come i token OAuth.

  Nota: se devi inviare dati altamente sensibili, assicurati che siano criptati prima di aggiungerli al token.

• Una stringa della proprietà expiration impostata su un timestamp Unix (in millisecondi) della data e dell'ora in cui vuoi che l'API Google Drive interrompa l'invio dei messaggi per questo canale di notifica.

  Se un canale ha una scadenza, questa viene inclusa come valore dell'intestazione HTTP X-Goog-Channel-Expiration (in formato leggibile) in ogni messaggio di notifica che l'applicazione riceve per questo canale.

Nota: per l'API Google Drive, il tempo di scadenza massimo è di 86400 secondi (1 giorno) dopo l'ora corrente per la risorsa files e di 604800 secondi (1 settimana) per changes. Se non imposti la proprietà expiration nella richiesta, il valore predefinito per la data e l'ora di scadenza è 3600 secondi dopo l'ora corrente.

Per ulteriori dettagli sulla richiesta, consulta il metodo watch per i metodi files e changes in Riferimento API.

Guarda la risposta

Se la richiesta watch crea correttamente un canale di notifica, restituisce un codice di stato HTTP 200 OK.

Il corpo del messaggio della risposta dello smartwatch fornisce informazioni sul canale di notifica che hai appena creato, come mostrato nell'esempio seguente.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://www.googleapis.com/drive/v3/files/o3hgv1538sdjfh", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1426325213000, // Actual expiration date and time as UNIX timestamp (in milliseconds), if applicable.
}

Oltre alle proprietà inviate nell'ambito della richiesta, le informazioni restituite includono anche resourceId e resourceUri per identificare la risorsa guardata su questo canale di notifica.

Nota: la proprietà resourceId è un identificatore stabile, indipendente dalla versione per la risorsa. La proprietà resourceUri è l'URI canonico della risorsa guardata nel contesto della versione corrente dell'API, pertanto è specifica della versione.

Puoi passare le informazioni restituite ad altre operazioni del canale di notifica, ad esempio quando vuoi interrompere la ricezione delle notifiche.

Per ulteriori dettagli sulla risposta, consulta il metodo watch per i metodi files e changes in Riferimento API.

Sincronizza messaggio

Dopo aver creato un canale di notifica per monitorare una risorsa, l'API Google Drive invia un messaggio sync per indicare che le notifiche stanno iniziando. Il valore dell'intestazione HTTP X-Goog-Resource-State per questi messaggi è sync. A causa di problemi di temporizzazione della rete, è possibile ricevere il messaggio sync anche prima di ricevere la risposta del metodo watch.

Puoi ignorare la notifica sync, ma puoi anche utilizzarla. Ad esempio, se decidi di non mantenere il canale, puoi utilizzare i valori X-Goog-Channel-ID e X-Goog-Resource-ID in una chiamata per smettere di ricevere notifiche. Puoi anche utilizzare la sync notifica per eseguire alcune operazioni di inizializzazione in preparazione agli eventi successivi.

Di seguito è mostrato il formato dei messaggi sync che l'API Google Drive invia all'URL di destinazione.

POST https://mydomain.com/notifications // Your receiving URL.
X-Goog-Channel-ID: channel-ID-value
X-Goog-Channel-Token: channel-token-value
X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires.
X-Goog-Resource-ID: identifier-for-the-watched-resource
X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource
X-Goog-Resource-State: sync
X-Goog-Message-Number: 1

I messaggi di sincronizzazione hanno sempre un valore dell'intestazione HTTP X-Goog-Message-Number uguale a 1. Ogni notifica successiva per questo canale ha un numero di messaggio maggiore di quello precedente, anche se i numeri dei messaggi non saranno sequenziali.

Rinnova i canali di notifica

Un canale di notifica può avere una data e un'ora di scadenza, con un valore determinato dalla tua richiesta o da eventuali limiti o valori predefiniti interni dell'API Google Drive (viene utilizzato il valore più restrittivo). La data e l'ora di scadenza del canale, se esistenti, sono incluse come timestamp Unix (in millisecondi) nelle informazioni restituite dal metodo watch. Inoltre, la data e l'ora di scadenza sono incluse (in un formato leggibile) in ogni messaggio di notifica che la tua applicazione riceve per questo canale nell'intestazione HTTP X-Goog-Channel-Expiration.

Al momento non esiste un modo automatico per rinnovare un canale di notifica. Quando un canale è prossimo alla scadenza, devi sostituirlo con uno nuovo chiamando il metodo watch. Come sempre, devi utilizzare un valore univoco per la proprietà id del nuovo canale. Tieni presente che è probabile che si verifichi un periodo di "sovrapposizione" quando i due canali di notifica per la stessa risorsa sono attivi.

Ricevere notifiche

Ogni volta che una risorsa controllata cambia, l'applicazione riceve un messaggio di notifica che descrive la modifica. L'API Google Drive invia questi messaggi come richieste POST HTTPS all'URL specificato come proprietà address per questo canale di notifica.

Nota: le richieste HTTPS di invio delle notifiche devono specificare uno user agent APIs-Google e rispettare le istruzioni del file robots.txt, come descritto in User agent di API Google.

Interpreta il formato del messaggio di notifica

Tutti i messaggi di notifica includono un insieme di intestazioni HTTP con prefissi X-Goog-. Alcuni tipi di notifiche possono includere anche un testo.

Intestazioni

I messaggi di notifica pubblicati dall'API Google Drive nell'URL di destinazione includono le seguenti intestazioni HTTP:

Intestazione	Descrizione
Presentare sempre
X-Goog-Channel-ID	UUID o altra stringa univoca che hai fornito per identificare questo canale di notifica.
X-Goog-Message-Number	Numero intero che identifica il messaggio per questo canale di notifica. Il valore è sempre 1 per i messaggi sync. I numeri dei messaggi aumentano per ogni messaggio successivo sul canale, ma non sono sequenziali.
X-Goog-Resource-ID	Un valore opaco che identifica la risorsa controllata. Questo ID è stabile nelle varie versioni dell'API.
X-Goog-Resource-State	Il nuovo stato della risorsa che ha attivato la notifica. Valori possibili: sync, add, remove, update, trash, untrash o change .
X-Goog-Resource-URI	Un identificatore della versione dell'API specifico per la risorsa controllata.
A volte presente
X-Goog-Changed	Ulteriori dettagli sulle modifiche. Valori possibili: content, parents, children o permissions . Non fornito con i messaggi sync.
X-Goog-Channel-Expiration	Data e ora di scadenza del canale di notifica, espresse in formato leggibile. Presente solo se definito.
X-Goog-Channel-Token	Token del canale di notifica impostato dalla tua applicazione e che puoi utilizzare per verificare l'origine della notifica. Presente solo se definito.

I messaggi di notifica per files e changes sono vuoti.

Esempi

Messaggio di notifica della modifica per le risorse files, che non include un corpo della richiesta:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/files/ret08u3rv24htgh289g
X-Goog-Resource-State:  update
X-Goog-Changed: content,properties
X-Goog-Message-Number: 10

Messaggio di notifica della modifica per le risorse changes, che include un corpo della richiesta:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 118
X-Goog-Channel-ID: 8bd90be9-3a58-3122-ab43-9823188a5b43
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret987df98743md8g
X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/changes
X-Goog-Resource-State:  changed
X-Goog-Message-Number: 23

{
  "kind": "drive#changes"
}

Risposta alle notifiche

Per indicare il successo, puoi restituire uno dei seguenti codici di stato: 200, 201, 202, 204 o 102.

Se il tuo servizio utilizza la libreria client dell'API di Google e restituisce 500,502, 503 o 504, l'API Google Drive riprova con il backoff esponenziale. Tutti gli altri codici di stato di ritorno sono considerati errori di messaggio.

Informazioni sugli eventi di notifica dell'API Google Drive

Questa sezione fornisce dettagli sui messaggi di notifica che puoi ricevere quando utilizzi le notifiche push con l'API Google Drive.

X-Goog-Resource-State	Si applica a	Pubblicato il
sync	files, changes	Un canale è stato creato correttamente. Dovresti iniziare a ricevere notifiche al riguardo.
add	files	È stata creata o condivisa una risorsa.
remove	files	Una risorsa esistente è stata eliminata o non è più condivisa.
update	files	Una o più proprietà (metadati) di una risorsa sono state aggiornate.
trash	files	Una risorsa è stata spostata nel cestino.
untrash	files	Una risorsa è stata rimossa dal cestino.
change	changes	Sono stati aggiunti uno o più elementi del log delle modifiche.

Nel tempo, a questo elenco potrebbero essere aggiunti altri eventi relativi allo stato delle risorse. Potresti ricevere tipi di eventi imprevisti. I tuoi gestori di eventi dovrebbero ignorarli.

Per gli eventi update, potrebbe essere fornita l'intestazione HTTP X-Goog-Changed. L'intestazione contiene un elenco separato da virgole che descrive i tipi di modifiche che si sono verificate.

Tipo di modifica	Indica
content	I contenuti della risorsa sono stati aggiornati.
properties	Una o più proprietà della risorsa sono state aggiornate.
parents	Sono stati aggiunti o rimossi uno o più elementi principali della risorsa.
children	Uno o più elementi figlio delle risorse sono stati aggiunti o rimossi.
permissions	Le autorizzazioni delle risorse sono state aggiornate.

Esempio con intestazione X-Goog-Changed:

X-Goog-Resource-State: update
X-Goog-Changed: content, permissions

Interrompi la ricezione di notifiche

La proprietà expiration controlla quando le notifiche si interrompono automaticamente. Puoi scegliere di interrompere la ricezione delle notifiche per un determinato canale prima che scada chiamando il metodo stop al seguente URI:

https://www.googleapis.com/drive/v3/channels/stop

Questo metodo richiede di fornire almeno le proprietà id e resourceId del canale, come mostrato nell'esempio riportato di seguito. Tieni presente che se l'API Google Drive ha diversi tipi di risorse con metodi watch, esiste un solo metodo stop.

Solo gli utenti che dispongono dell'autorizzazione appropriata possono interrompere un canale. In particolare:

• Se il canale è stato creato da un account utente normale, solo lo stesso utente dello stesso client (identificato dagli ID client OAuth 2.0 dei token di autenticazione) che ha creato il canale può interromperlo.
• Se il canale è stato creato da un account di servizio, qualsiasi utente dello stesso client può interromperlo.

Il seguente esempio di codice mostra come interrompere la ricezione di notifiche:

POST https://www.googleapis.com/drive/v3/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}