Questa pagina è stata tradotta dall'API Cloud Translation.

Notifiche push

Questo documento descrive come utilizzare le notifiche push per informare i tuoi quando una risorsa cambia.

Panoramica

L'API Google Calendar fornisce notifiche push che ti consentono di monitorare delle modifiche nelle risorse. Puoi usare questa funzione per migliorare le prestazioni di la tua applicazione. Consente di eliminare le risorse di rete e di calcolo aggiuntive relativi ai sondaggi per determinare se sono cambiati. Ogni volta che una risorsa controllata cambia, l'API Google Calendar ti avvisa un'applicazione.

Per utilizzare le notifiche push, devi eseguire due operazioni:

Configura l'URL di ricezione o il "webhook" ricevente di callback.
Questo è un server HTTPS che gestisce i messaggi di notifica delle API in caso di modifica di una risorsa.
Configura un (canale di notifica) per ogni endpoint delle risorse che vuoi smartwatch.
Un canale specifica le informazioni di routing per le notifiche messaggi. Come parte della configurazione del canale, devi identificare l'URL specifico in cui vuoi ricevere notifiche. Ogni volta che una risorsa del canale cambia, l'API Google Calendar invia un messaggio di notifica come POST richiesta a quell'URL.

Attualmente, l'API Google Calendar supporta le notifiche per le modifiche alle le 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 impostato i canali di notifica l'API Google Calendar informa la tua applicazione quando eventuali risorse modifiche.

Effettua richieste di orologio

A ogni risorsa dell'API Google Calendar visualizzabile è associata watch in un URI nel seguente formato:

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

Per impostare un canale di notifica per i messaggi relativi alle modifiche a una risorsa specifica, invia una richiesta POST Metodo watch per la risorsa.

Ogni canale di notifica è associato sia a un utente specifico una particolare risorsa (o un insieme di risorse). Una richiesta watch non avrà successo a meno che l'utente corrente possiede o dispone dell'autorizzazione per accedere a questa risorsa.

Esempio

Inizia a controllare le modifiche apportate 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 di tipo watch, devi fornire i seguenti campi:

Una stringa della proprietà id che identifica in modo univoco nuovo canale di notifica all'interno del tuo progetto. È consigliabile utilizzare Un identificatore univoco universale (UUID) o simile stringa univoca. Lunghezza massima: 64 caratteri.

Il valore ID impostato viene ripreso nel campo Intestazione HTTP X-Goog-Channel-Id di ogni 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. 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 è installato un certificato SSL valido sul tuo server web. I certificati non validi includono:
- Certificati autofirmati.
- Certificati firmati da una fonte non attendibile.
- Certificati revocati.
- Certificati con un oggetto che non corrisponde alla destinazione dell'host.

Proprietà facoltative

Puoi anche specificare questi campi facoltativi Richiesta di watch:

Una proprietà token che specifica una stringa arbitraria da utilizzare come token del canale. Puoi usare il canale di notifica di token per vari scopi. Ad esempio, puoi utilizzare per verificare che ogni messaggio in arrivo sia destinato a un canale dell'applicazione creata, per assicurarti che la notifica falsificato o per indirizzare il messaggio alla destinazione corretta la tua applicazione in base allo scopo di questo canale. Lunghezza massima: 256 caratteri.
Il token è incluso nel X-Goog-Channel-Token intestazione HTTP in ogni notifica che la tua applicazione riceve per il canale.

Se utilizzi i token del canale di notifica, ti consigliamo di:
- Utilizza un formato di codifica estensibile, come la query URL parametri. Esempio: forwardTo=hr&createdBy=mobile
- Non includere dati sensibili come i token OAuth.
di Gemini Advanced.
Nota: se devi inviare messaggi ad alta sensibilità assicurati che siano crittografati prima di aggiungerli di accesso.
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 interrompi l'invio di 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 ricevute dall'applicazione per questo canale.

Per maggiori dettagli sulla richiesta, fai riferimento al metodo watch per le risorse Acl, CalendarList, Events e Settings in Riferimento API.

Guarda la risposta

Se la richiesta watch crea correttamente una notifica viene restituito un codice di stato HTTP 200 OK.

Il corpo del messaggio della risposta dell'orologio 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à inviate nell'ambito della richiesta, i campi le informazioni restituite includono anche resourceId e resourceUri per identificare la risorsa guardata su questo canale di notifica.

Nota: la proprietà resourceId è un un identificatore stabile, indipendente dalla versione per la risorsa. La La proprietà resourceUri è l'URI canonico dell'elemento controllato risorsa nel contesto della versione attuale dell'API, quindi specifici della versione.

Puoi passare le informazioni restituite a un altro canale di notifica operazioni, come quando interrompi la ricezione notifiche.

Per ulteriori dettagli sulla risposta, consulta watch per le risorse Acl, CalendarList, Events e Settings in Riferimento API.

Sincronizza messaggio

Dopo aver creato un canale di notifica per osservare una risorsa, L'API Google Calendar invia un messaggio sync per indicare che le notifiche vengono avviate. HTTP X-Goog-Resource-State il valore dell'intestazione per questi messaggi è sync. A causa della rete problemi di tempo, puoi ricevere il messaggio sync anche prima di ricevere la risposta del metodo watch.

Puoi ignorare la notifica di sync, ma puoi lo usi. Ad esempio, se decidi di non voler più mantenere il canale, puoi usare X-Goog-Channel-ID e Valori di X-Goog-Resource-ID in una chiamata a interrompere la ricezione delle notifiche. Puoi utilizzare anche Notifica sync per eseguire alcune operazioni di inizializzazione per prepararsi per gli eventi successivi.

Il formato dei messaggi sync a cui l'API Google Calendar invia l'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 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 HTTP X-Goog-Message-Number valore dell'intestazione 1. Ogni notifica successiva per questo canale contiene un numero di messaggio maggiore del precedente, sebbene il messaggio i numeri non saranno sequenziali.

Rinnova canali di notifica

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

Al momento, non è possibile rinnovare automaticamente un canale di notifica. Quando un canale è prossimo alla scadenza, devi sostituirlo con uno nuovo richiamando il metodo watch. Come sempre, devi utilizzare un valore univoco per la proprietà id del nuovo canale. Tieni presente che è probabile in modo che sia una "sovrapposizione" periodo di tempo in cui i due canali di notifica sono attive le stesse risorse.

Ricezione notifiche

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

Nota: richieste HTTPS per il recapito delle notifiche specifica uno user agent di APIs-Google e rispetta il file robots.txt come descritto in API Google user agent

Interpretare il formato dei messaggi 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

Messaggi di notifica pubblicati dall'API Google Calendar per il L'URL include le seguenti intestazioni HTTP:

Intestazione	Descrizione
Presentare sempre
`X-Goog-Channel-ID`	UUID o un'altra stringa univoca che hai fornito per identificarla canale di notifica.
`X-Goog-Message-Number`	Numero intero che identifica il messaggio per questa notifica canale. Il valore per i messaggi `sync` è sempre `1`. Messaggio aumentano per ogni messaggio successivo sul canale, ma non sequenziali.
`X-Goog-Resource-ID`	Un valore opaco che identifica la risorsa controllata. Questo ID è sono stabili 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 della versione dell'API specifico per la risorsa controllata.
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 la fonte della notifica. 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 i dettagli completi della modifica, dovrai effettuare un'altra chiamata API.

Esempi

Modifica il messaggio di notifica per la raccolta di eventi modificata:

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 che l'operazione è andata a buon fine, puoi restituire uno dei seguenti codici di stato: 200, 201, 202, 204 o 102.

Se il servizio utilizza la libreria client API di Google e restituisce 500,502, 503 o 504, l'API Google Calendar nuovi tentativi con backoff esponenziale. Ogni altro codice di stato del reso è considerato un errore del messaggio.

Informazioni sugli eventi di notifica dell'API Google Calendar

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

X-Goog-Resource-State	Si applica a	Consegnato quando
`sync`	ACL, elenchi di calendario, eventi, impostazioni.	È stato creato un nuovo canale. Potrai iniziare a ricevere le relative notifiche.
`exists`	ACL, elenchi di calendario, eventi, impostazioni.	Una risorsa è stata modificata. Le possibili modifiche includono la creazione di una nuova risorsa oppure la modifica o l'eliminazione di una risorsa esistente.

Interrompi la ricezione di notifiche

La proprietà expiration stabilisce quando interrompere automaticamente le notifiche. Puoi scegliere di interrompere la ricezione delle notifiche per un determinato canale prima che questo scade chiamando il metodo stop all'indirizzo il seguente URI:

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

Questo metodo richiede che tu fornisca almeno i dati del canale id e le proprietà resourceId, come mostrato in di esempio qui sotto. Tieni presente che se l'API Google Calendar ha diversi tipi di con watch metodi, ce n'è solo uno 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 dallo stesso client (come identificato dagli ID client OAuth 2.0 della di autenticazione) che ha creato il canale può interromperlo.
Se il canale è stato creato da un account di servizio, qualsiasi utente il cliente può interrompere 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"
}

Considerazioni speciali

Quando lavori con le notifiche push, tieni presente quanto segue:

Gli eventi e gli ACL sono a livello di calendario Se vuoi ricevere notifiche su tutte le modifiche agli eventi o agli ACL per i calendari A e B, devi sottoscrivere un abbonamento separato alle raccolte di eventi/ACL per A e B.

Impostazioni ed elenchi di calendari sono per utente Le impostazioni e gli elenchi di calendari hanno una sola raccolta per utente, quindi puoi iscriverti una sola volta.

Inoltre, non riceverai notifiche quando ottieni l'accesso a una nuova raccolta (ad esempio, un nuovo calendario), ma riceverai una notifica se tale calendario viene aggiunto all'elenco di calendari (ammesso che tu sia iscritto alla raccolta dell'elenco di calendari).

Le notifiche non sono affidabili al 100%. Una piccola percentuale di messaggi verrà eliminata in condizioni di lavoro normali. Assicurati di gestire questi aspetti i messaggi non vengono inviati correttamente, in modo che l'applicazione continui a essere sincronizzata anche se non vengono ricevuti messaggi push.