Questo documento descrive come utilizzare le notifiche push che informano la tua applicazione quando una risorsa viene modificata.
Panoramica
L'API Google Calendar fornisce notifiche push che consentono di monitorare le modifiche alle risorse. Puoi utilizzare questa funzionalità per migliorare le prestazioni della tua applicazione. Consente di eliminare i costi aggiuntivi di rete e calcolo associati alle risorse di polling per determinare se sono cambiate. Ogni volta che una risorsa controllata cambia, l'API Google Calendar invia una notifica all'applicazione.
Per utilizzare le notifiche push, devi eseguire due operazioni:
Imposta l'URL di ricezione o il ricevitore di callback "webhook".
Questo è un server HTTPS che gestisce i messaggi di notifica dell'API che vengono attivati quando una risorsa viene modificata.
Configura un canale di notifica per ogni endpoint delle risorse che vuoi guardare.
Un canale specifica le informazioni di routing per i messaggi di notifica. Nell'ambito della configurazione del canale, devi identificare l'URL specifico a cui vuoi ricevere le notifiche. Ogni volta che la risorsa di un canale viene modificata, l'API Google Calendar invia un messaggio di notifica come richiesta
POST
a quell'URL.
Attualmente, l'API Google Calendar supporta le notifiche per le modifiche alle risorse Acl, CalendarList, Eventi e Impostazioni.
Crea canali di notifica
Per richiedere notifiche push, devi configurare un canale di notifica per ogni risorsa che vuoi monitorare. Dopo aver configurato i canali di notifica, l'API Google Calendar informa la tua applicazione quando cambia una risorsa visualizzata.
Effettua richieste di visualizzazione
A ogni risorsa dell'API Google Calendar guardabile è associato un metodo watch
in un URI nel 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 a una determinata risorsa, invia una richiesta POST
al metodo watch
per la risorsa.
Ogni canale di notifica è associato a un determinato utente e a una particolare risorsa (o insieme di risorse). Una richiesta watch
non avrà esito positivo, a meno che l'utente corrente non possieda o disponga dell'autorizzazione per accedere a questa risorsa.
Esempio
Inizia a controllare le modifiche a una raccolta di eventi in un determinato calendario:
POST https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events/watch Authorization: Bearer auth_token_for_current_user 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-myCalendarChannelDest", // (Optional) Your channel token. "expiration": 1426325213000 // (Optional) Your requested channel expiration time. }
Proprietà obbligatorie
Per ogni richiesta watch
devi compilare i seguenti campi:
-
Una stringa della proprietà
id
che identifica in modo univoco questo nuovo canale di notifica all'interno del tuo progetto. Ti consigliamo di utilizzare un identificatore univoco universale (UUID) o una stringa univoca simile. Lunghezza massima: 64 caratteri.Il valore ID impostato viene riportato nell'intestazione HTTP
X-Goog-Channel-Id
di ogni messaggio di notifica che ricevi per il canale. -
Una stringa della proprietà
type
impostata sul valoreweb_hook
. -
Una stringa della proprietà
address
impostata sull'URL che ascolta e risponde alle notifiche per questo canale di notifica. Questo è l'URL di callback del webhook e deve utilizzare HTTPS.Tieni presente che l'API Google Calendar è in grado di inviare notifiche a questo indirizzo HTTPS solo se sul 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 stringa arbitrario da utilizzare come token di 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 assicurarti che la notifica non sia oggetto di spoofing, oppure per instradare il messaggio alla destinazione corretta all'interno della tua applicazione in base allo scopo di questo canale. Lunghezza massima: 256 caratteri.Il token è incluso nell'intestazione HTTP
X-Goog-Channel-Token
di ogni messaggio di notifica ricevuto dall'applicazione per il 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.
-
Una stringa della proprietà
expiration
impostata su un timestamp unix (in millisecondi) della data e dell'ora in cui vuoi che l'API Google Calendar interrompa l'invio di messaggi per questo canale di notifica.Se un canale ha una data di scadenza, viene incluso come valore dell'intestazione HTTP
X-Goog-Channel-Expiration
(in formato leggibile) in ogni messaggio di notifica ricevuto dall'applicazione per il canale.
Per maggiori dettagli sulla richiesta, consulta il metodo watch
per le risorse Acl, CalendarList, Eventi e Impostazioni nella documentazione di 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 dell'orologio fornisce informazioni sul canale di notifica che hai appena creato, come mostrato nell'esempio di seguito.
{ "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/calendar/v3/calendars/my_calendar@gmail.com/events", // Version-specific ID of the watched resource. "token": "target=myApp-myCalendarChannelDest", // Present only if one was provided. "expiration": 1426325213000, // Actual expiration time as Unix timestamp (in ms), if applicable. }
Oltre alle proprietà che hai inviato nell'ambito della tua richiesta, le informazioni restituite includono anche resourceId
e resourceUri
per identificare la risorsa guardata su questo canale di notifica.
Puoi passare le informazioni restituite ad altre operazioni del canale di notifica, ad esempio quando vuoi interrompere la ricezione delle notifiche.
Per maggiori dettagli sulla risposta, consulta il metodo watch
per le risorse Acl, CalendarList, Eventi e Impostazioni nella documentazione di riferimento API.
Sincronizza messaggio
Dopo aver creato un canale di notifica per guardare una risorsa, l'API Google Calendar invia un messaggio sync
per indicare che
le notifiche vengono avviate. 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 usarla. Ad esempio, se decidi di non voler mantenere il canale, puoi utilizzare i valori X-Goog-Channel-ID
e X-Goog-Resource-ID
in una chiamata per interrompere la ricezione delle notifiche. Puoi anche utilizzare la notifica sync
per eseguire alcune inizializzazioni e prepararti per eventi successivi.
Di seguito è mostrato il formato dei messaggi sync
che l'API Google Calendar 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
pari a 1
. Ogni notifica successiva per questo canale ha un numero di messaggio maggiore della precedente, anche se i numeri dei messaggi non saranno sequenziali.
Rinnova canali di notifica
Un canale di notifica può avere una data di scadenza, con un valore determinato dalla tua richiesta oppure da eventuali limiti o valori predefiniti dell'API Google Calendar (viene utilizzato il valore più restrittivo). La scadenza del canale, se presente, viene inclusa sotto forma di timestamp Unix (in millisecondi) nelle informazioni restituite dal metodo watch
. Inoltre, la data e l'ora di scadenza sono incluse (in formato leggibile) in ogni messaggio di notifica ricevuto dall'applicazione per questo canale nell'intestazione HTTP X-Goog-Channel-Expiration
.
Al momento non è possibile rinnovare automaticamente un canale di notifica. Quando un canale sta per scadere, 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" in cui i due canali di notifica per la stessa risorsa sono attivi.
Ricezione notifiche
Ogni volta che una risorsa controllata cambia, l'applicazione riceve un messaggio di notifica che descrive la modifica. L'API Google Calendar invia questi
messaggi come richieste POST
HTTPS all'URL specificato come
proprietà address
per questo canale
di notifica.
Interpretare 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 corpo del messaggio.
Intestazioni
I messaggi di notifica pubblicati dall'API Google Calendar nell'URL di destinazione includono le seguenti intestazioni HTTP:
Titolo | Descrizione |
---|---|
Sempre presente | |
|
UUID o altra stringa univoca che hai fornito per identificare questo canale di notifica. |
|
Numero intero che identifica il messaggio per questo canale
di notifica. Il valore è sempre 1 per i messaggi sync . Il numero di messaggi aumenta per ogni messaggio successivo sul canale, ma non è sequenziale. |
|
Un valore opaco che identifica la risorsa controllata. Questo ID è stabile tra le versioni API. |
|
Il nuovo stato della risorsa che ha attivato la notifica.
Valori possibili:
sync , exists o
not_exists .
|
|
Un identificatore specifico della versione dell'API per la risorsa controllata. |
A volte presente | |
|
Data e ora di scadenza del canale di notifica, espresse in formato leggibile. Presente solo se definito. |
|
Token del canale di notifica impostato dall'applicazione e che puoi utilizzare per verificare l'origine delle notifiche. Presente solo se definito. |
I messaggi di notifica pubblicati dall'API Google Calendar nell'URL di destinazione non includono il corpo del messaggio. Questi messaggi non contengono informazioni specifiche sulle risorse aggiornate. Per visualizzare tutti i dettagli delle modifiche, dovrai effettuare un'altra chiamata API.
Esempi
Modifica il messaggio di notifica per la raccolta modificata di eventi:
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/calendar/v3/calendars/my_calendar@gmail.com/events X-Goog-Resource-State: exists X-Goog-Message-Number: 10
Risposta alle notifiche
Per indicare l'esito positivo, 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 Calendar
esegue un nuovo tentativo con un backoff esponenziale.
Ogni altro codice di stato restituito è considerato un errore di messaggio.
Informazioni sugli eventi di notifica dell'API Google Calendar
Questa sezione fornisce dettagli sui messaggi di notifica che puoi ricevere quando utilizzi le notifiche push con l'API Google Calendar.
Consegnato il giorno | ||
---|---|---|
sync |
ACL, elenchi di calendari, eventi e impostazioni. | È stato creato un nuovo canale. Dovresti iniziare a ricevere notifiche in merito. |
exists |
ACL, elenchi di calendari, eventi e impostazioni. | È stata apportata una modifica a una risorsa. Le possibili modifiche includono la creazione di una nuova risorsa o la modifica o l'eliminazione di una risorsa esistente. |
Notifiche di arresto
La proprietà expiration
stabilisce quando interrompere automaticamente le notifiche. Puoi scegliere di non ricevere più le notifiche per un determinato canale prima che scada chiamando il metodo stop
al seguente URI:
https://www.googleapis.com/calendar/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 Calendar dispone di diversi tipi di risorse con metodi watch
, può esistere 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 normale account utente, solo lo stesso utente dello stesso client (identificato dagli ID client OAuth 2.0 dei token di autenticazione) che ha creato il canale può arrestare il canale.
- Se il canale è stato creato da un account di servizio, qualsiasi utente dello stesso client può arrestare il canale.
Il seguente esempio di codice mostra come interrompere la ricezione delle notifiche:
POST https://www.googleapis.com/calendar/v3/channels/stop Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66", "resourceId": "ret08u3rv24htgh289g" }