Ce document explique comment gérer les notifications push dans l'API Gmail.
L'API Gmail fournit des notifications push du serveur qui vous permettent de surveiller les modifications apportées aux boîtes aux lettres Gmail. Utilisez cette fonctionnalité pour améliorer les performances de votre application. Il élimine les coûts de réseau et de calcul supplémentaires liés à l'interrogation des ressources pour déterminer si elles ont changé. Chaque fois qu'une boîte aux lettres est modifiée, l'API Gmail envoie une notification à l'application de votre serveur backend.
Configuration initiale de Cloud Pub/Sub
L'API Gmail utilise l'API Cloud Pub/Sub pour envoyer des notifications push. Cela permet d'envoyer des notifications à l'aide de différentes méthodes, y compris des webhooks et l'interrogation d'un point de terminaison d'abonnement unique.
Prérequis
Pour effectuer cette configuration, remplissez les conditions préalables de Cloud Pub/Sub, puis configurez un client Cloud Pub/Sub.
Créer un sujet
À l'aide de votre client Cloud Pub/Sub, créez le sujet auquel l'API Gmail doit envoyer les notifications. Le nom du sujet peut être n'importe quel nom de votre choix dans votre projet (par exemple, projects/myproject/topics/*, où myproject est l'ID de projet indiqué pour votre projet dans la console Google Cloud).
Créer un abonnement
Pour configurer un abonnement au sujet que vous avez créé, suivez le guide Types d'abonnement Cloud Pub/Sub. Configurez le type d'abonnement sur "push webhook" (c'est-à-dire un rappel HTTP POST) ou "pull" (c'est-à-dire initié par votre application). C'est ainsi que votre application reçoit les notifications de mise à jour.
Accorder des droits de publication sur votre sujet
Cloud Pub/Sub nécessite que vous accordiez des droits Gmail pour publier des notifications dans votre sujet.
Pour ce faire, accordez les droits publish à gmail-api-push@system.gserviceaccount.com. Pour ce faire, vous pouvez utiliser la console des autorisations Cloud Pub/Sub dans la console Google Cloud en suivant ces instructions sur le contrôle des accès.
La configuration de partage restreint au domaine de votre organisation peut vous empêcher d'accorder des autorisations de publication. Pour résoudre ce problème, vous pouvez configurer une exception pour ce compte de service.
Recevoir des informations sur votre boîte aux lettres Gmail
Une fois la configuration initiale de Cloud Pub/Sub terminée, configurez les comptes Gmail pour qu'ils envoient des notifications concernant les mises à jour des boîtes aux lettres.
Demande de visionnage
Pour configurer des comptes Gmail afin d'envoyer des notifications à votre sujet Cloud Pub/Sub, utilisez votre client de l'API Gmail pour appeler la méthode watch sur la boîte aux lettres de l'utilisateur Gmail. Cela ressemble à n'importe quel autre appel d'API Gmail. Indiquez le nom du sujet que vous avez créé et toute autre option dans votre requête watch, comme labels pour filtrer. Par exemple, utilisez la requête suivante pour être averti chaque fois qu'une modification est apportée à la boîte de réception :
Protocole
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()
Regarder la réponse
Si la requête watch aboutit, vous recevez une réponse semblable à celle-ci :
{ historyId: 1234567890 expiration: 1431990098200 }
La réponse contient le historyId actuel de la boîte aux lettres de l'utilisateur. Votre client reçoit des notifications pour toutes les modifications apportées après le historyId. Si vous devez traiter les modifications avant cette date, consultez la section Synchroniser les clients avec l'API Gmail.historyId
De plus, un appel watch réussi entraîne l'envoi immédiat d'une notification à votre sujet Cloud Pub/Sub.
Si vous recevez une erreur lors de l'appel watch, les détails devraient expliquer la source du problème. Il s'agit généralement d'un problème de configuration du sujet et de l'abonnement Cloud Pub/Sub. Consultez la documentation Cloud Pub/Sub pour vérifier que la configuration est correcte et obtenir de l'aide pour résoudre les problèmes liés aux sujets et aux abonnements.
Renouveler la surveillance de la boîte aux lettres
Vous devez appeler watch au moins une fois tous les sept jours, sinon vous ne recevrez plus de mises à jour pour l'utilisateur. Nous vous recommandons d'appeler watch une fois par jour. La réponse de la méthode watch comporte également un champ expiration avec le code temporel de l'expiration watch.
Recevoir des notifications
Chaque fois qu'une mise à jour de boîte aux lettres correspondant à votre watch se produit, votre application reçoit un message de notification décrivant la modification.
Si vous avez configuré un abonnement push, une notification de webhook envoyée à votre serveur est conforme à 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"
}
Le corps HTTP POST est au format JSON et la charge utile de la notification Gmail se trouve dans le champ message.data. Le champ message.data est une chaîne encodée au format Base64URL qui, une fois décodée, donne un objet JSON contenant l'adresse e-mail et le nouvel ID de l'historique de la boîte aux lettres de l'utilisateur :
{"emailAddress": "user@example.com", "historyId": "9876543210"}
Vous pouvez ensuite utiliser la méthode history.list pour obtenir les détails des modifications apportées à l'utilisateur depuis sa dernière mise à jour
historyId, comme décrit dans Synchroniser les clients avec l'API Gmail.
Par exemple, utilisez la méthode history.list pour identifier les modifications qui se sont produites entre votre requête watch initiale et la réception du message de notification partagé dans l'exemple précédent. Transmettez 1234567890 en tant que startHistoryId à history.list. Vous pouvez ensuite conserver 9876543210 comme dernière valeur connue historyId pour les futurs cas d'utilisation.
Si vous avez configuré un abonnement par extraction, consultez les exemples de code du guide Abonnements par extraction de Cloud Pub/Sub pour en savoir plus sur la réception des messages.
Répondre à des notifications
Toutes les notifications doivent être confirmées. Si vous utilisez la diffusion push de webhook, une réponse positive (par exemple, HTTP 200) confirme la réception de la notification.
Si vous utilisez la récupération par extraction (REST Pull, RPC Pull ou RPC StreamingPull), vous devez effectuer un appel d'accusé de réception (REST ou RPC). Pour en savoir plus sur l'accusé de réception des messages de manière asynchrone ou synchrone à l'aide des bibliothèques clientes officielles basées sur RPC, consultez les exemples de code du guide sur les abonnements pull de Cloud Pub/Sub.
Si vous ne confirmez pas la réception des notifications (par exemple, si le rappel de votre webhook renvoie une erreur ou expire), Cloud Pub/Sub tente à nouveau d'envoyer la notification ultérieurement.
Arrêter les mises à jour de la boîte aux lettres
Pour ne plus recevoir de notifications concernant une boîte aux lettres, appelez la méthode stop. Toutes les nouvelles notifications devraient s'arrêter en quelques minutes.
Limites
Voici les limites liées à l'utilisation des notifications push du serveur :
Taux maximal de notifications
Chaque utilisateur Gmail surveillé est soumis à une fréquence de notification maximale d'un événement par seconde. Toutes les notifications utilisateur dépassant ce taux sont supprimées. Lorsque vous gérez des notifications, veillez à ne pas en déclencher une autre, ce qui pourrait entraîner une boucle de notifications.
Fiabilité
En règle générale, toutes les notifications sont distribuées de manière fiable en quelques secondes. Toutefois, dans certaines situations extrêmes, elles peuvent être retardées ou abandonnées.
Gérez cette possibilité de manière fluide afin que l'application se synchronise même si aucun message push n'est reçu. Par exemple, revenez à l'appel périodique de la méthode history.list après une période sans notifications pour un utilisateur.
Limites de Cloud Pub/Sub
L'API Cloud Pub/Sub possède également ses propres limites, qui sont détaillées dans sa documentation sur la tarification et les quotas.