Questo documento spiega come gestire le notifiche push con l'API Gmail.
L'API Gmail fornisce notifiche push del server che consentono di controllare le modifiche alle caselle di posta di Gmail. Utilizza questa funzionalità per migliorare le prestazioni della tua applicazione. Elimina i costi aggiuntivi di rete e di calcolo del 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 inviare notifiche push. In questo modo puoi ricevere notifiche utilizzando vari metodi, tra cui webhook e polling su un singolo endpoint di sottoscrizione.
Prerequisiti
Per completare questa configurazione, soddisfa i prerequisiti di Cloud Pub/Sub e poi configura 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
tu scelga nel tuo progetto (ad esempio, corrispondenza
projects/myproject/topics/*, dove myproject è l'ID progetto elencato per
il tuo progetto nella console Google Cloud).
Creare una sottoscrizione
Per configurare un abbonamento all'argomento che hai creato, segui la guida Tipo di abbonamento Cloud Pub/Sub. Configura il tipo di sottoscrizione in modo che sia un push webhook (ovvero un callback HTTP POST) o un pull (ovvero avviato dalla tua app). In questo modo, la tua applicazione riceve le notifiche per gli aggiornamenti.
Concedere i diritti di pubblicazione sull'argomento
Cloud Pub/Sub richiede che tu conceda a Gmail i privilegi per pubblicare notifiche nel tuo argomento.
Per farlo, concedi i privilegi publish a
gmail-api-push@system.gserviceaccount.com. Puoi farlo utilizzando la console
delle autorizzazioni
Cloud Pub/Sub nella
console Google Cloud
seguendo queste istruzioni
per il controllo dell'accesso.
La configurazione della condivisione con limitazioni del dominio della tua organizzazione potrebbe impedirti di concedere le autorizzazioni di pubblicazione. Per risolvere il problema, puoi configurare un'eccezione per questo service account.
Ricevere aggiornamenti della casella di posta Gmail
Dopo aver completato la configurazione iniziale di Cloud Pub/Sub, configura gli account Gmail per inviare notifiche per gli aggiornamenti delle caselle postali.
Richiesta di visualizzazione
Per configurare gli account Gmail in modo che inviino notifiche all'argomento Cloud Pub/Sub, utilizza il client API Gmail per chiamare il metodo watch nella casella di posta dell'utente Gmail. È simile a qualsiasi altra
chiamata API Gmail. Fornisci il nome dell'argomento che hai creato e qualsiasi altra opzione nella richiesta watch, ad esempio labels per filtrare. Ad esempio, utilizza
la seguente richiesta per ricevere una notifica ogni volta che si verifica una modifica nella 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 la seguente:
{
"historyId": "1234567890",
"expiration": "1431990098200"
}
La risposta contiene l'historyId della casella di posta attuale dell'utente. Il tuo cliente
riceve notifiche per tutte le modifiche successive al giorno historyId. Se devi
elaborare le modifiche prima di questa data historyId, consulta
Sincronizzare i client con Gmail.
Inoltre, una chiamata watch riuscita invia immediatamente una notifica all'argomento Cloud Pub/Sub.
Se ricevi un errore dalla chiamata watch, i dettagli dovrebbero spiegare l'origine del problema. In genere, si tratta di un problema di configurazione dell'argomento e dell'abbonamento Cloud Pub/Sub. Consulta la documentazione di Cloud Pub/Sub per verificare che la configurazione sia corretta e per ricevere assistenza per il debug dei problemi relativi ad argomenti e abbonamenti.
Rinnova la casella di posta
Devi chiamare il metodo watch
almeno una volta ogni 7 giorni, altrimenti smetterai di ricevere aggiornamenti per l'utente.
Ti consigliamo di chiamare watch una volta al giorno. La risposta del metodo watch include anche un campo
expiration con il timestamp della scadenza di watch.
Ricevere notifiche
Ogni volta che si verifica un aggiornamento della casella di posta che corrisponde al tuo watch, la tua applicazione
riceve un messaggio di notifica che descrive la modifica.
Se hai configurato una sottoscrizione push, una notifica webhook al tuo server
è 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 della richiesta HTTP POST è JSON e il payload di notifica di Gmail
effettivo si trova nel campo message.data. Il campo message.data è una stringa con codifica Base64URL che viene decodificata in un oggetto JSON contenente l'indirizzo email e il nuovo ID cronologia della casella di posta dell'utente:
{"emailAddress": "user@example.com", "historyId": "9876543210"}
Puoi quindi utilizzare il metodo
history.list
per ottenere i dettagli delle modifiche apportate all'utente dal suo ultimo
historyId, come descritto in
Sincronizzare i client con Gmail.
Ad esempio, utilizza il metodo
history.list
per identificare le modifiche apportate tra la richiesta
watch iniziale e la
ricezione del messaggio di notifica condiviso nell'esempio precedente. Passa
1234567890 come startHistoryId a history.list. Successivamente, puoi
memorizzare 9876543210 come ultimo historyId per i casi d'uso futuri.
Se hai configurato una sottoscrizione pull, consulta gli esempi di codice nella guida alle sottoscrizioni pull di Cloud Pub/Sub per ulteriori dettagli sulla ricezione dei messaggi.
Risposta alle notifiche
Devi confermare tutte le notifiche. Se utilizzi la consegna push webhook, la risposta positiva (ad esempio HTTP 200) conferma la notifica.
Se utilizzi il recupero pull (pull REST, pull RPC o pull RPC in streaming), devi confermare la ricezione dei messaggi utilizzando il metodo di conferma REST o RPC. Per ulteriori dettagli sul riconoscimento dei messaggi in modo asincrono o sincrono utilizzando le librerie client ufficiali basate su RPC, consulta gli esempi di codice nella guida alle sottoscrizioni pull di Cloud Pub/Sub.
Se non confermi la ricezione delle notifiche (ad esempio, se il callback del webhook restituisce un errore o scade il timeout), Cloud Pub/Sub riprova a inviare la notifica in un secondo momento.
Interrompere gli aggiornamenti della casella di posta
Per interrompere la ricezione di aggiornamenti su una casella di posta, chiama il
metodo stop. Tutte le nuove
notifiche dovrebbero interrompersi entro pochi minuti.
Limitazioni
Di seguito sono riportate le limitazioni relative all'utilizzo delle notifiche push del server:
Frequenza massima delle notifiche
Ogni utente Gmail monitorato ha una frequenza massima di notifiche di un evento al secondo. Il servizio elimina le notifiche utente che superano questa velocità. Quando gestisci le notifiche, fai attenzione a non attivarne un'altra, che può avviare un ciclo di notifiche.
Affidabilità
In genere, Cloud Pub/Sub invia le notifiche entro pochi secondi. Tuttavia,
in rare situazioni, le notifiche potrebbero subire ritardi o non essere inviate. Gestisci questa
possibilità in modo appropriato in modo che l'applicazione venga comunque sincronizzata anche se non riceve messaggi push. Ad esempio, esegui il fallback alla chiamata periodica del metodo
history.list
dopo un periodo senza notifiche per un utente.
Limitazioni di Cloud Pub/Sub
Anche l'API Cloud Pub/Sub ha le sue limitazioni, descritte in dettaglio nella documentazione relativa a prezzi e quote.