Configurare le notifiche push nell'API Gmail

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 il rendimento della tua applicazione. Elimina i costi di rete e di calcolo aggiuntivi delle risorse di polling per determinare se sono state modificate. Ogni volta che una casella di posta viene modificata, 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 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, corrispondente a projects/myproject/topics/*, dove myproject è l'ID progetto elencato per il tuo progetto nella console Google Cloud).

Crea una sottoscrizione

Per configurare una sottoscrizione all'argomento che hai creato, segui la guida al tipo di sottoscrizione 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 notifiche per gli aggiornamenti.

Concedi i diritti di pubblicazione sull'argomento

Cloud Pub/Sub richiede che tu conceda a Gmail i privilegi per pubblicare le 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 di condivisione con limitazioni di dominio della tua organizzazione potrebbe impedirti di concedere le autorizzazioni di pubblicazione. Per risolvere il problema, puoi configurare un' eccezione per questo account di servizio.

Ricevi gli aggiornamenti della casella di posta di Gmail

Una volta completata la configurazione iniziale di Cloud Pub/Sub, configura gli account Gmail in modo che inviino notifiche per gli aggiornamenti della casella di posta.

Richiesta di monitoraggio

Per configurare gli account Gmail in modo che inviino notifiche all'argomento Cloud Pub/Sub, utilizza il client API Gmail per chiamare il watch metodo 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:

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 di monitoraggio

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

{ historyId: 1234567890 expiration: 1431990098200 }

La risposta contiene l'historyId della casella di posta corrente dell'utente. Il client riceve notifiche per tutte le modifiche successive a questo historyId. Se devi elaborare le modifiche precedenti a questo historyId, consulta 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 sottoscrizioni.

Rinnova il monitoraggio della 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 ha anche un expiration campo con il timestamp della scadenza di watch.

Ricevere notifiche

Ogni volta che si verifica un aggiornamento della casella di posta che corrisponde a 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 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 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 history.list metodo per ottenere i dettagli delle modifiche apportate dall'utente dall'ultimo conosciuto historyId, come descritto in Sincronizzare i client con l'API Gmail.

Ad esempio, utilizza il history.list metodo per identificare le modifiche apportate tra la richiesta watch iniziale e la ricezione del messaggio di notifica condiviso nell'esempio precedente. Trasmetti 1234567890 come startHistoryId a history.list. Dopodiché, puoi conservare 9876543210 come historyId più recente conosciuto 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 riconosciute. Se utilizzi la consegna push webhook, la risposta riuscita (ad esempio, HTTP 200) riconosce la notifica.

Se utilizzi la consegna pull (REST Pull, RPC Pull, o RPC StreamingPull), devi seguire una chiamata di riconoscimento (REST o RPC). Consulta gli esempi di codice nella guida alle sottoscrizioni pull di Cloud Pub/Sub per ulteriori dettagli sul riconoscimento dei messaggi in modo asincrono o sincrono utilizzando le librerie client ufficiali basate su RPC.

Se non riconosci le notifiche (ad esempio, se il callback webhook restituisce un errore o si verifica un timeout), Cloud Pub/Sub riprova a inviare la notifica in un secondo momento.

Interrompi gli aggiornamenti della casella di posta

Per interrompere la ricezione degli aggiornamenti di una casella di posta, chiama il stop metodo. Tutte le nuove notifiche dovrebbero essere interrotte 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 notifica di un evento al secondo. Le notifiche utente che superano questa frequenza vengono eliminate. Quando gestisci le notifiche, fai attenzione a non attivare un'altra notifica, che può avviare un loop 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 essere eliminate. Gestisci questa possibilità in modo che l'applicazione si sincronizzi anche se non vengono ricevuti messaggi push. Ad esempio, torna a chiamare periodicamente il history.list metodo 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.