Notifiche push

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Questo documento descrive come utilizzare le notifiche push che informano l'applicazione in caso di modifica di una risorsa.

Panoramica

L'API Google Calendar fornisce notifiche push che ti consentono di verificare la presenza di modifiche alle risorse. Puoi utilizzare questa funzionalità per migliorare le prestazioni dell'applicazione. Consente di eliminare la rete aggiuntiva e i costi di calcolo associati alle risorse di polling per determinare se sono stati modificati. Ogni volta che una risorsa osservata cambia, l'API Google Calendar notifica l'applicazione.

Per utilizzare le notifiche push, devi eseguire due operazioni:

  • Configura l'URL di destinazione o il callback "Webhook".

    Questo è un server HTTPS che gestisce i messaggi di notifica API che vengono attivati quando una risorsa viene modificata.

  • Configura un canale di notifica per ciascun endpoint di risorse che vuoi guardare.

    Un canale specifica le informazioni di routing per i messaggi di notifica. Durante la 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 tale URL.

Attualmente, l'API Google Calendar supporta le notifiche per le modifiche alle risorse Acl, CalendarList, Eventi e Impostazioni.

Creazione di canali di notifica

Per richiedere notifiche push, devi configurare un canale di notifica per ogni risorsa che vuoi guardare. Dopo aver configurato i canali di notifica, l'API Google Calendar informerà l'applicazione in caso di modifica di qualsiasi risorsa visualizzata.

Inviare richieste di visualizzazione

Ogni risorsa dell'API Google Calendar guardabile ha un metodo watch associato a un URI nel seguente formato:

https://www.googleapis.com/apiName/apiVersion/resourcePath/watch

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

Ogni canale di notifica è associato sia a un determinato utente sia a una specifica risorsa (o insieme di risorse). Una richiesta watch non avrà esito positivo a meno che l'utente attuale non abbia la proprietà o l'autorizzazione per accedere a questa risorsa.

Esempio

Inizia a guardare 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 fornire:

  • Una stringa della 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 una stringa univoca simile. Lunghezza massima: 64 caratteri.

    Il valore ID che imposti viene ripetuto nell'intestazione HTTP X-Goog-Channel-Id 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 rimane in ascolto e risponde alle notifiche per questo canale di notifica. Questo è l'URL di callback webhook e deve utilizzare HTTPS.

    Tieni presente che l'API Google Calendar potrà 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 oggetto non corrispondente al nome host della 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 del canale. Puoi utilizzare i token del canale di notifica per una varietà di scopi. Ad esempio, puoi utilizzare il token per verificare che ogni messaggio in entrata sia associato a un canale creato dalla tua applicazione, per assicurarti che la notifica non venga oggetto di spoofing o 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 in ogni messaggio di notifica ricevuto dall'applicazione 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 ricerca 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 ms) 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 (questa volta in formato leggibile) in ogni messaggio di notifica che la tua applicazione riceve per questo canale.

Per maggiori dettagli sulla richiesta, consulta il metodo watch per le risorse Acl, CalendarList, Eventi e Impostazioni nella documentazione di riferimento dell'API.

Controlla la risposta

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

Il corpo del messaggio della risposta allo smartwatch fornisce informazioni sul canale di notifica appena creato, come mostrato nell'esempio riportato 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 come parte della tua richiesta, le informazioni restituite includono anche resourceId e resourceUri per identificare la risorsa monitorata su questo canale di notifica.

Puoi trasmettere 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 dell'API.

Sincronizza messaggio

Dopo aver creato un nuovo canale di notifica per guardare una risorsa, l'API Google Calendar invia un messaggio sync per indicare che le notifiche sono in fase di avvio. Il valore di intestazione HTTP X-Goog-Resource-State per questi messaggi è sync. A causa di problemi di tempi di 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 di una chiamata per interrompere la ricezione delle notifiche. Puoi anche utilizzare la notifica sync per eseguire un'inizializzazione per prepararti per eventi successivi.

Il formato dei messaggi sync che l'API Google Calendar invia all'URL di destinazione è riportato di seguito.

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 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 di intestazione HTTP X-Goog-Message-Number pari a 1. Ogni notifica successiva per questo canale avrà un numero di messaggio maggiore del precedente, sebbene i numeri dei messaggi non siano sequenziali.

Rinnovo dei canali di notifica

Un canale di notifica può avere una data di scadenza, con un valore determinato dalla tua richiesta o da qualsiasi limite interno o predefinito dell'API Google Calendar (viene utilizzato il valore più restrittivo). La data di scadenza del canale, se presente, è inclusa come timestamp Unix (in ms) 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 dalla tua applicazione 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 sta per scadere, devi crearne 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 tempo in cui i due canali di notifica per la stessa risorsa sono attivi.

Ricezione notifiche

Ogni volta che la risorsa osservata viene modificata, l'applicazione riceve un messaggio di notifica che descrive la modifica. L'API Google Calendar invia questi messaggi come richieste HTTPS POST all'URL specificato come "indirizzo" per questo canale di notifica.

Informazioni sul formato dei messaggi di notifica

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

Intestazioni

I messaggi di notifica pubblicati dall'API di Google Calendar all'URL di destinazione 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 il 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 osservata. Questo ID è stabile nelle versioni 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 API per la risorsa osservata.
A volte presenti
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 dall'applicazione e che puoi utilizzare per verificare l'origine della notifica. Presente solo se definito.

I messaggi di notifica pubblicati dall'API di Google Calendar all'URL di destinazione non includono un corpo di messaggio. Questi messaggi non contengono informazioni specifiche sulle risorse aggiornate, dovrai effettuare un'altra chiamata API per visualizzare i dettagli della modifica completa.

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

Rispondere alle notifiche

Per indicare che l'operazione è riuscita, puoi restituire uno dei seguenti codici di stato: 200, 201, 202, 204 o 102.

Se il servizio utilizza la libreria client dell'API di Google e restituisce 500,502, 503 o 504, l'API di Google Calendar riprova con il backoff esponenziale. Ogni altro codice per lo stato del reso è considerato un messaggio non riuscito.

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.

Stato-risorsa-X Applicabile a Recapitato quando
sync ACL, elenchi di Calendar, eventi, impostazioni. È stato creato un nuovo canale. Dovresti iniziare a ricevere notifiche correlate.
exists ACL, elenchi di Calendar, eventi, 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.

Interruzione delle notifiche

La scadenza indica l'interruzione automatica delle notifiche. Puoi decidere di interrompere la ricezione delle notifiche per un determinato canale prima che scada chiamando il metodo stop al seguente URL:

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

Questo metodo richiede che tu fornisca almeno le proprietà id e resourceId del canale, come mostrato nell'esempio riportato di seguito. Tieni presente che anche se l'API Google Calendar ha diversi tipi di risorse con metodi watch, esiste solo un 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 hanno creato il canale potrà interromperlo.
  • Se il canale è stato creato da un account di servizio, qualsiasi utente dello stesso client può interromperlo.
POST https://www.googleapis.com/calendar/v3/channels/stop
  
Authorization: Bearer {auth_token_for_current_user}
Content-Type: application/json

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