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. Consente di eliminare i costi aggiuntivi di rete e di 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 inviare notifiche push. Ciò consente la notifica 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 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 es. projects/myproject/topics/*, dove myproject è l'ID progetto elencato per il tuo progetto in Google Developers Console).

Creare una sottoscrizione

Segui la guida per gli abbonati a Cloud Pub/Sub per configurare un abbonamento all'argomento che hai creato. Configura il tipo di sottoscrizione in modo che sia un push webhook (ovvero un callback POST HTTP) o un pull (ovvero avviato dalla tua app). In questo modo, la tua applicazione riceverà 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, devi concedere i privilegi publish a [email protected]. 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 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 visione

Per configurare gli account Gmail in modo che inviino notifiche all'argomento Cloud Pub/Sub, utilizza semplicemente il client API Gmail per chiamare watch nella casella di posta dell'utente Gmail in modo simile a qualsiasi altra chiamata API Gmail. A questo scopo, fornisci il nome dell'argomento creato sopra e qualsiasi altra opzione nella tua richiesta watch, ad esempio labels per filtrare. Ad esempio, per ricevere una notifica ogni volta che viene apportata una modifica alla Posta in arrivo:

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

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

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

Risposta dello smartwatch

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

{
  historyId: 1234567890
  expiration: 1431990098200
}

con la casella historyId attuale dell'utente. Tutte le modifiche successive a historyId verranno comunicate al tuo cliente. Se devi elaborare le modifiche prima di questa data historyId, consulta la guida alla sincronizzazione.

Inoltre, una chiamata watch riuscita 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 con il debug dei problemi relativi ad argomenti e abbonamenti.

Rinnovo della spia della cassetta postale

Devi richiamare watch almeno ogni 7 giorni, altrimenti smetterai di ricevere aggiornamenti per l'utente. Ti consigliamo di chiamare watch una volta al giorno. La risposta watch include anche un campo di scadenza con il timestamp della scadenza di watch.

Ricezione di notifiche.

Ogni volta che si verifica un aggiornamento della casella di posta che corrisponde 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 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 per l'utente:

{"emailAddress": "[email protected]", "historyId": "9876543210"}

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

Ad esempio, per utilizzare history.list per identificare le modifiche apportate tra la chiamata watch iniziale e la ricezione del messaggio di notifica condiviso nell'esempio precedente, passa 1234567890 come startHistoryId a history.list. Successivamente,9876543210 può essere mantenuto come historyId ultima nota per i casi d'uso futuri.

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

Rispondere alle notifiche

Tutte le notifiche devono essere confermate. Se utilizzi la consegna push webhook, la risposta corretta (ad es. HTTP 200) confermerà la notifica.

Se utilizzi la distribuzione pull (REST Pull, RPC Pull o RPC StreamingPull), devi eseguire un follow-up con una chiamata di conferma (REST o RPC). Per maggiori 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 al pull di Cloud Pub/Sub Subscriber.

Se le notifiche non vengono riconosciute (ad es. il callback webhook restituisce un errore o scade), Cloud Pub/Sub riprova a inviare la notifica in un secondo momento.

Interruzione degli aggiornamenti della casella postale

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

Limitazioni

Frequenza massima delle notifiche

Ogni utente Gmail monitorato ha una frequenza di notifica massima di 1 evento/secondo. Le notifiche utente al di sopra di questa frequenza verranno eliminate. Fai attenzione quando gestisci le notifiche per evitare di attivarne un'altra e quindi 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. Assicurati di gestire questa possibilità in modo appropriato, in modo che l'applicazione continui a sincronizzarsi anche se non vengono ricevuti messaggi push. Ad esempio, ripristina le chiamate periodiche 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.