Questo documento spiega come gestire le notifiche push nell'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. Ciò consente di utilizzare le notifiche con vari metodi, tra cui webhook e polling su un singolo endpoint di abbonamento.
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 questo problema, puoi configurare un'eccezione per questo service account.
Ricevere aggiornamenti della casella Gmail
Una volta completata 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 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 la seguente:
{ historyId: 1234567890 expiration: 1431990098200 }
La risposta contiene l'historyId della casella di posta corrente 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 la sezione Sincronizzare i client
con l'API Gmail.
Inoltre, una chiamata watch riuscita fa sì che una notifica venga inviata immediatamente
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 della sottoscrizione 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 watch
almeno una volta ogni 7 giorni, altrimenti non riceverai più 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 un abbonamento 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 postale 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
l'API 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. Trasferisci
1234567890 come startHistoryId a history.list. Successivamente, puoi
conservare 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
Tutte le notifiche devono essere confermate. Se utilizzi la consegna push webhook, la risposta positiva (ad esempio HTTP 200) conferma la notifica.
Se utilizzi il recupero pull (REST Pull, RPC Pull, o RPC StreamingPull), devi eseguire un'operazione di riconoscimento (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 postale
Per interrompere la ricezione di aggiornamenti su una casella postale, 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. Le notifiche utente che superano questa frequenza vengono eliminate. Quando gestisci le notifiche, fai attenzione a non attivarne un'altra, che può avviare un ciclo di notifiche.
Affidabilità
In genere, tutte le notifiche vengono inviate in modo affidabile entro pochi secondi;
tuttavia, in alcune situazioni estreme, le notifiche potrebbero subire ritardi o non essere inviate.
Gestisci questa possibilità in modo appropriato in modo che l'applicazione si sincronizzi anche se
non vengono ricevuti messaggi push. Ad esempio, ripristina la 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.