Ricevi notifiche push

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

Panoramica

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

Per utilizzare le notifiche push, devi fare due cose:

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

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

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

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

Al momento, l'API Google Calendar supporta le notifiche per le modifiche alle risorse ACL, CalendarList, Events e Settings.

Creare canali di notifica

Per richiedere le 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 una risorsa monitorata cambia.

Effettuare richieste di monitoraggio

Ogni risorsa dell'API Google Calendar monitorabile ha un metodo watch associato a 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 risorsa specifica, invia una POST richiesta al watch metodo per la risorsa.

Ogni canale di notifica è associato a un utente e a una risorsa (o a un insieme di risorse) specifici. Una richiesta watch non andrà a buon fine a meno che l'utente attuale non sia il proprietario della risorsa o non abbia l'autorizzazione per accedervi.

Esempio

Inizia a monitorare 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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

Nel corpo della richiesta, fornisci l'id del canale, il type come web_hook e l'URL di ricezione in address. In via facoltativa, puoi anche fornire:

  • Un token da utilizzare come token del canale.
  • Un tempo di expiration in millisecondi per la scadenza del canale richiesta.

Proprietà obbligatorie

Con ogni richiesta watch, devi fornire questi 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 dell'ID che hai impostato viene riprodotto nell' X-Goog-Channel-Id intestazione HTTP di ogni messaggio di notifica che ricevi per questo canale.

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

  • Una stringa della proprietà address impostata sull'URL che ascolta e risponde alle notifiche per questo canale di notifica. Si tratta dell'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 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 tua watch richiesta:

  • Una proprietà token che specifica un valore stringa arbitrario da utilizzare come token del canale. Puoi utilizzare i token dei canali di notifica per vari scopi. Ad esempio, puoi utilizzare il token per verificare che ogni messaggio in arrivo sia per un canale creato dalla tua applicazione, per assicurarti che la notifica non sia oggetto di spoofing o per indirizzare 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' X-Goog-Channel-Token intestazione HTTP in ogni messaggio di notifica che la tua applicazione riceve per questo canale.

    Se utilizzi i token dei canali di notifica, ti consigliamo di:

    • Utilizzare un formato di codifica estensibile, ad esempio i parametri di query URL parametri. 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 smetta di inviare messaggi per questo canale di notifica.

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

Per ulteriori dettagli sulla richiesta, consulta il metodo watch per le risorse ACL, CalendarList, Events e Settings nella documentazione di riferimento dell'API.

Risposta di monitoraggio

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

Il corpo del messaggio della risposta di monitoraggio fornisce informazioni sul canale di notifica appena creato, come mostrato nell'esempio riportato di seguito.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events",
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

Il corpo della risposta fornisce dettagli sul canale, ad esempio:

  • kind: identifica questa risorsa come risorsa del canale API.
  • id: l'ID che hai specificato per questo canale.
  • resourceId: l'ID della risorsa monitorata.
  • resourceUri: l'ID specifico della versione della risorsa monitorata.
  • token: il token fornito nel corpo della richiesta.
  • expiration: l'ora di scadenza del canale come timestamp Unix in millisecondi.

Oltre alle proprietà inviate come parte della richiesta, le informazioni restituite includono anche resourceId e resourceUri per identificare la risorsa monitorata 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 ulteriori dettagli sulla risposta, consulta il watch metodo per le risorse ACL, CalendarList, Events, e Settings nella documentazione di riferimento dell'API.

Messaggio di sincronizzazione

Dopo aver creato un canale di notifica per monitorare una risorsa, l' API Google Calendar invia un messaggio sync per indicare che le notifiche stanno per iniziare. 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 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 sync notifica per eseguire alcune inizializzazioni in preparazione per gli eventi successivi.

Di seguito è riportato il formato dei messaggi sync che l'API Google Calendar invia a all'URL di ricezione.

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 di quello precedente, anche se i numeri dei messaggi non saranno sequenziali.

Rinnovare i canali di notifica

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

Al momento non esiste un modo automatico per rinnovare un canale di notifica. Quando un canale è in scadenza, devi sostituirlo con uno nuovo chiamando il watch metodo. Come sempre, devi utilizzare un valore univoco per la id proprietà 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.

Ricevere notifiche

Ogni volta che una risorsa monitorata cambia, la tua 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 la address proprietà per questo canale di notifica.

Interpretare il formato del messaggio di notifica

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

Intestazioni

I messaggi di notifica pubblicati dall'API Google Calendar all'URL di ricezione includono le seguenti intestazioni HTTP:

Intestazione Descrizione
Sempre presente
X-Goog-Channel-ID UUID o altra stringa univoca fornita per identificare questo canale di notifica.
X-Goog-Message-Number Numero intero che identifica questo 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 monitorata. Questo ID è stabile tra le versioni dell'API.
X-Goog-Resource-State Il nuovo stato della risorsa che ha attivato la notifica. Valori possibili: sync, exists o not_exists.
X-Goog-Resource-URI Un identificatore specifico della versione dell'API per la risorsa monitorata.
A volte presente
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 pubblicati dall'API Calendar all'URL di ricezione non includono un corpo del messaggio. Questi messaggi non contengono informazioni specifiche sulle risorse aggiornate; devi effettuare un'altra chiamata API per visualizzare i dettagli completi delle modifiche.

Esempio

Messaggio di notifica di modifica per la raccolta di eventi modificata:

POST https://mydomain.com/notifications
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

Rispondere 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 delle API di Google e restituisce 500, 502, 503 o 504, l'API Google Calendar riprova con un backoff esponenziale. Tutti gli altri codici di stato restituiti sono considerati errori di messaggio.

Comprendere gli 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.

X-Goog-Resource-State Applicabile a Inviato quando
sync ACL, elenchi di calendari, eventi, impostazioni. Un nuovo canale è stato creato correttamente. Ora è possibile ricevere le notifiche.
exists ACL, elenchi di calendari, eventi, impostazioni. Una risorsa è stata modificata. Le modifiche possibili includono la creazione di una nuova risorsa o la modifica o l'eliminazione di una risorsa esistente.

Interrompere la ricezione di notifiche

La proprietà expiration controlla quando le notifiche vengono interrotte automaticamente. Puoi scegliere di interrompere la ricezione delle notifiche per un determinato canale prima della scadenza chiamando il metodo stop all' URI seguente:

https://www.googleapis.com/workspace/calendar/api/v3/reference/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 ha diversi tipi di risorse con metodi watch, esiste un solo stop metodo.

Solo gli utenti con l'autorizzazione corretta 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 service account, qualsiasi utente dello stesso client può interromperlo.

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

POST https://www.googleapis.com/workspace/calendar/api/v3/reference/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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