Notifiche push

Panoramica

L'API Gmail fornisce notifiche push del server che ti permettono di controllare le modifiche alle caselle di posta Gmail. Puoi usare questa funzione per migliorare le prestazioni della tua applicazione. Consente di eliminare i costi extra di rete e calcolo associati al polling delle risorse per determinare se sono cambiate. Ogni volta che una casella di posta cambia, l'API Gmail invia una notifica all'applicazione server di backend.

Configurazione iniziale di Cloud Pub/Sub

L'API Gmail utilizza l'API Cloud Pub/Sub per la consegna di notifiche push. Ciò consente di ricevere notifiche tramite una serie di metodi, tra cui webhook e polling su un singolo endpoint di abbonamento.

Prerequisiti

Per completare il resto della configurazione, assicurati di soddisfare i prerequisiti di Cloud Pub/Sub e di configurare un client Cloud Pub/Sub.

crea un argomento

Utilizzando il client Cloud Pub/Sub, crea l'argomento a cui l'API Gmail deve inviare le notifiche. Il nome dell'argomento può essere qualsiasi nome scelto nel progetto (ad esempio projects/myproject/topics/* corrispondente, dove myproject è l'ID progetto elencato per il progetto in Google Developers Console).

Ti consigliamo di utilizzare un unico argomento per tutte le notifiche push dell'API Gmail per la tua applicazione, a causa dei limiti di Cloud Pub/Sub sul numero di argomenti.

crea una sottoscrizione

Segui la guida per gli abbonati a Cloud Pub/Sub per configurare una sottoscrizione all'argomento che hai creato. Configura il tipo di abbonamento in modo che sia push webhook (ad es. callback POST HTTP) o pull (ossia avviato dalla tua app). In questo modo la tua applicazione riceverà le notifiche per gli aggiornamenti.

Concedi i diritti di pubblicazione sull'argomento

Cloud Pub/Sub richiede la concessione dei privilegi Gmail per pubblicare notifiche sull'argomento.

A tale scopo, devi concedere i privilegi publish a gmail-api-push@system.gserviceaccount.com. A questo scopo, utilizza l'interfaccia delle autorizzazioni della console per gli sviluppatori Cloud Pub/Sub seguendo le istruzioni per il controllo dell'accesso a livello di risorsa.

Ricevere aggiornamenti alle caselle di posta di Gmail

Una volta completata la configurazione iniziale di Cloud Pub/Sub, configura gli account Gmail per l'invio di notifiche per gli aggiornamenti delle caselle di posta.

Richiesta di visualizzazione

Per configurare gli account Gmail in modo che inviino notifiche al tuo argomento Cloud Pub/Sub, utilizza semplicemente il tuo client dell'API Gmail per chiamare watch nella casella di posta dell'utente Gmail, come per qualsiasi altra chiamata API Gmail. Per farlo, fornisci il nome dell'argomento creato in precedenza e qualsiasi altra opzione nella richiesta watch, ad esempio labels in base al quale applicare il filtro. Ad esempio, per ricevere una notifica ogni volta che viene apportata una modifica alla Posta in arrivo:

Protocollo

POST "https://www.googleapis.com/gmail/v1/users/me/watch"
Content-type: application/json

{
  topicName: "projects/myproject/topics/mytopic",
  labelIds: ["INBOX"],
  labelFilterBehavior: "INCLUDE",
}

Python

request = {
  'labelIds': ['INBOX'],
  'topicName': 'projects/myproject/topics/mytopic',
  'labelFilterBehavior': 'INCLUDE'
}
gmail.users().watch(userId='me', body=request).execute()

Guarda la risposta

Se la richiesta watch ha esito positivo, riceverai una risposta come:

{
  historyId: 1234567890
  expiration: 1431990098200
}

con la casella di posta historyId corrente dell'utente. Tutte le modifiche apportate dopo questa data historyId verranno comunicate al tuo client. Se devi elaborare modifiche prima di questo historyId, consulta la guida alla sincronizzazione.

Inoltre, una chiamata watch riuscita dovrebbe causare l'invio immediato di una notifica al tuo argomento Cloud Pub/Sub.

Se ricevi un errore dalla chiamata watch, i dettagli dovrebbero spiegare l'origine del problema, che in genere è la configurazione dell'argomento e della sottoscrizione Cloud Pub/Sub. Consulta la documentazione di Cloud Pub/Sub per verificare che la configurazione sia corretta e per assistenza per il debug dei problemi relativi all'argomento e all'abbonamento.

Rinnovo smartwatch della casella di posta

Devi richiamare watch almeno ogni 7 giorni, altrimenti non riceverai più aggiornamenti per l'utente. Ti consigliamo di chiamare il numero watch una volta al giorno. La risposta watch ha anche un campo di scadenza con il timestamp relativo alla scadenza di watch.

Ricezione di notifiche

Ogni volta che si verifica un aggiornamento della casella di posta che corrisponde al tuo watch, l'applicazione riceve un messaggio di notifica che descrive la modifica.

Se hai configurato una sottoscrizione push, una notifica webhook al server sarà conforme a un PubsubMessage:

POST https://yourserver.example.com/yourUrl
Content-type: application/json

{
  message:
  {
    // This is the actual notification data, as base64url-encoded JSON.
    data: "eyJlbWFpbEFkZHJlc3MiOiAidXNlckBleGFtcGxlLmNvbSIsICJoaXN0b3J5SWQiOiAiMTIzNDU2Nzg5MCJ9",

    // This is a Cloud Pub/Sub message id, unrelated to Gmail messages.
    "messageId": "2070443601311540",

    // This is the publish time of the message.
    "publishTime": "2021-02-26T19:13:55.749Z",
  }

  subscription: "projects/myproject/subscriptions/mysubscription"
}

Il corpo del messaggio HTTP POST è in formato JSON e il payload effettivo delle notifiche di Gmail si trova nel campo message.data. Quel campo message.data è una stringa con codifica base64url che decodifica in un oggetto JSON contenente l'indirizzo email e il nuovo ID cronologia della casella di posta per l'utente:

{"emailAddress": "user@example.com", "historyId": "9876543210"}

Puoi quindi utilizzare history.list per ottenere i dettagli delle modifiche per l'utente dall'ultimoID cronologia noto, come indicato nella guida alla sincronizzazione.

Se invece hai configurato una sottoscrizione pull, fai riferimento agli esempi di codice nella Guida al pull degli abbonati a Cloud Pub/Sub per ulteriori dettagli sulla ricezione dei messaggi.

Risposta alle notifiche

Tutte le notifiche devono essere confermate. Se utilizzi l'invio push del webhook, se rispondi correttamente (ad es. HTTP 200) la notifica verrà confermata.

Se utilizzi la consegna pull (REST Pull, RPC Pull o RPC StreamingPull) devi dare seguito con una chiamata di conferma (REST o RPC). Fai riferimento agli esempi di codice nella guida al pull degli abbonati a Cloud Pub/Sub per ulteriori dettagli sul riconoscimento dei messaggi in modo asincrono o in modo sincrono utilizzando le librerie client ufficiali basate su RPC.

Se le notifiche non vengono confermate (ad esempio, il callback webhook restituisce un errore o un timeout), Cloud Pub/Sub proverà di nuovo a inviare la notifica in un secondo momento.

Interruzione degli aggiornamenti delle caselle di posta

Per non ricevere più aggiornamenti su una casella di posta, chiama il numero stop e tutte le nuove notifiche dovranno interrompersi entro pochi minuti.

Limitazioni

Frequenza massima di notifiche

Ogni utente di Gmail che stai guardando ha una frequenza massima di notifica di 1 evento al secondo. Eventuali notifiche utente al di sopra di questa frequenza verranno ignorate. Fai attenzione quando gestisci le notifiche per assicurarti di non attivare un'altra notifica e, di conseguenza, di avviare un ciclo di notifica.

Affidabilità

In genere tutte le notifiche dovrebbero essere consegnate in modo affidabile entro pochi secondi, ma in alcune situazioni estreme le notifiche potrebbero subire ritardi o essere ignorate. Assicurati di gestire questa possibilità senza problemi, in modo che l'applicazione continui a sincronizzarsi anche se non vengono ricevuti messaggi push. Ad esempio, torna a chiamare periodicamente history.list dopo un periodo senza notifiche per l'utente.

Limitazioni di Cloud Pub/Sub

L'API Cloud Pub/Sub presenta inoltre limitazioni specifiche, illustrate in dettaglio nella documentazione relativa ai pricing e alle quotas.