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.