Notifiche push

Panoramica

L'API Gmail fornisce notifiche push del server che consentono di controllare le modifiche alle caselle di posta di Gmail. Puoi utilizzare questa funzionalità per migliorare il rendimento della tua applicazione. Ti consente di eliminare i costi aggiuntivi di calcolo e rete 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 del 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 inviare notifiche tramite una serie di metodi, tra cui webhook e polling su un singolo endpoint di sottoscrizione.

Prerequisiti

Per completare il resto della configurazione, assicurati di soddisfare 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 scelto nel progetto (ovvero corrispondente a projects/myproject/topics/*, 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 sottoscrizione in modo che sia un push webhook (ad es. callback POST HTTP) o pull (ovvero avviato dalla tua app). In questo modo, la tua applicazione riceverà notifiche per gli aggiornamenti.

Concedere i diritti di pubblicazione per l'argomento

Cloud Pub/Sub richiede che tu conceda a Gmail i privilegi per pubblicare notifiche nel tuo argomento.

Per farlo, devi concedere i privilegi publish a gmail-api-push@system.gserviceaccount.com. Puoi farlo utilizzando l'interfaccia delle autorizzazioni della console per sviluppatori Cloud Pub/Sub seguendo le istruzioni per il controllo dell'accesso a livello di risorsa.

Ricevere aggiornamenti della casella di posta di Gmail

Al termine della configurazione iniziale di Cloud Pub/Sub, configura gli account Gmail per inviare notifiche per gli aggiornamenti della cassetta di posta.

Richiesta di visualizzazione

Per configurare gli account Gmail in modo che inviino notifiche al tuo argomento Cloud Pub/Sub, basta utilizzare il client dell'API Gmail per chiamare watch nella casella di posta dell'utente di Gmail, come per qualsiasi altra chiamata all'API Gmail. A questo scopo, fornisci il nome dell'argomento creato sopra e eventuali altre opzioni nella richiesta watch, ad esempio labels per applicare un 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()

Guardare la risposta

Se la richiesta watch ha esito positivo, riceverai una risposta simile alla seguente:

{
  historyId: 1234567890
  expiration: 1431990098200
}

con la casella di posta historyId corrente per l'utente. Tutte le modifiche apportate dopo il giorno historyId verranno comunicate al tuo cliente. Se devi elaborare modifiche precedenti a questa data historyId, consulta la guida alla sincronizzazione.

Inoltre, una chiamata watch andata a buon fine dovrebbe causare l'invio immediato di una notifica all'argomento Cloud Pub/Sub.

Se ricevi un errore dalla chiamata watch, i dettagli dovrebbero spiegare l'origine del problema, che in genere riguarda 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 ricevere assistenza per il debug dei problemi relativi agli argomenti e agli abbonamenti.

Rinnovo della sorveglianza della cassetta delle lettere

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

Ricezione di notifiche.

Ogni volta che si verifica un aggiornamento della casella di posta corrispondente al tuo watch, la tua applicazione riceverà un messaggio di notifica che descrive la modifica.

Se hai configurato un abbonamento push, una notifica webhook al tuo 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 della richiesta POST HTTP è JSON e il payload effettivo della notifica di Gmail si trova nel campomessage.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 della cronologia della posta per l'utente:

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

Puoi quindi utilizzare history.list per ottenere i dettagli delle modifiche per l'utente dal suo ultimo valore noto di historyId, come indicato nella guida alla sincronizzazione.

Se invece hai configurato un abbonamento pull, consulta gli esempi di codice nella guida per gli abbonati pull di Cloud Pub/Sub per maggiori dettagli sulla ricezione dei messaggi.

Rispondere alle notifiche

Tutte le notifiche devono essere confermate. Se utilizzi il webhook per la pubblicazione push, la notifica verrà confermata se rispondi correttamente (ad es. HTTP 200).

Se utilizzi l'importazione pull (REST Pull, RPC Pull o RPC StreamingPull), devi seguire con una chiamata di conferma (REST o RPC). Fai riferimento agli esempi di codice nella guida al pull degli abbonati Cloud Pub/Sub per maggiori dettagli sull'accreditamento dei messaggi in modo asincrono o in modo sincrono utilizzando le librerie client ufficiali basate su RPC.

Se le notifiche non vengono confermate (ad es. il callback dell'webhook restituisce un errore o scade il tempo di attesa), Cloud Pub/Sub riproverà a inviare la notifica in un secondo momento.

Interrompere gli aggiornamenti della casella di posta

Per interrompere la ricezione di aggiornamenti su una cassetta postale, chiama stop e tutte le nuove notifiche dovrebbero interrompersi entro pochi minuti.

Limitazioni

Frequenza massima delle notifiche

Ogni utente di Gmail monitorato ha una frequenza di notifica massima di 1 evento/sec. Eventuali notifiche utente superiori a questa frequenza verranno ignorate. Fai attenzione quando gestisci le notifiche per non attivarne un'altra e avviare un ciclo di notifiche.

Affidabilità

In genere, tutte le notifiche dovrebbero essere inviate in modo affidabile entro pochi secondi. Tuttavia, in alcune situazioni estreme le notifiche potrebbero subire ritardi o essere perse. Assicurati di gestire questa possibilità in modo corretto, in modo che l'applicazione si sincronizzi anche se non vengono ricevuti messaggi push. Ad esempio, puoi ricorrere alla chiamata periodica di history.list dopo un periodo di tempo senza notifiche per un utente.

Limitazioni di Cloud Pub/Sub

Anche l'API Cloud Pub/Sub ha le sue limitazioni, descritte in modo specifico nella documentazione relativa a prezzi e quote.