Présentation
L'API Gmail fournit des notifications push du serveur qui vous permettent de surveiller les modifications apportées aux boîtes aux lettres Gmail. Vous pouvez utiliser cette fonctionnalité pour améliorer les performances de votre application. Il vous permet d'éliminer 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 à votre application 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 par différentes méthodes, y compris des webhooks et l'interrogation d'un point de terminaison d'abonnement unique.
Prérequis
Pour terminer le reste de la configuration, assurez-vous de remplir 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. Vous pouvez choisir le nom de votre choix pour le sujet sous votre projet (c'est-à-dire en respectant le format projects/myproject/topics/*, où myproject correspond à l'ID du projet listé pour votre projet dans la Google Developers Console).
Créer un abonnement
Suivez le Guide pour les abonnés Cloud Pub/Sub pour configurer un abonnement au sujet que vous avez créé. Configurez le type d'abonnement sur "push" (c'est-à-dire un rappel HTTP POST) ou "pull" (c'est-à-dire initié par votre application). C'est ainsi que votre application recevra 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, vous devez accorder les droits publish à gmail-api-push@system.gserviceaccount.com. Pour ce faire, utilisez l'interface des autorisations de la console pour les développeurs Cloud Pub/Sub en suivant les instructions sur le contrôle des accès au niveau des ressources.
Recevoir des notifications concernant 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 de la boîte aux lettres.
Demande de visionnage
Pour configurer des comptes Gmail afin qu'ils envoient des notifications à votre sujet Cloud Pub/Sub, il vous suffit d'utiliser votre client API Gmail pour appeler watch sur la boîte aux lettres de l'utilisateur Gmail, comme pour tout autre appel de l'API Gmail.
Pour ce faire, indiquez le nom du sujet créé ci-dessus et toute autre option dans votre requête watch, comme labels pour filtrer. Par exemple, pour recevoir une notification 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 recevrez une réponse de ce type :
{
historyId: 1234567890
expiration: 1431990098200
}
avec la boîte aux lettres actuelle historyId de l'utilisateur. Toutes les modifications apportées après le historyId seront notifiées à votre client. Si vous devez traiter des modifications avant le historyId, consultez le guide de synchronisation.
De plus, un appel watch réussi doit entraîner l'envoi immédiat d'une notification à votre sujet Cloud Pub/Sub.
Si vous recevez une erreur de l'appel watch, les détails devraient expliquer la source du problème, qui concerne généralement la 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 rappeler watch au moins tous les sept jours, sinon vous cesserez de recevoir des informations sur l'utilisateur. Nous vous recommandons d'appeler watch une fois par jour. La réponse watch comporte également un champ d'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 sera 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 notification Gmail se trouve dans le champ message.data. Le champ message.data est une chaîne encodée en base64url qui, une fois décodée, donne un objet JSON contenant l'adresse e-mail et le nouvel ID d'historique de boîte aux lettres de l'utilisateur :
{"emailAddress": "user@example.com", "historyId": "9876543210"}
Vous pouvez ensuite utiliser history.list pour obtenir les détails des modifications apportées par l'utilisateur depuis son dernier historyId connu, conformément au guide de synchronisation.
Par exemple, pour utiliser history.list afin d'identifier les modifications qui se sont produites entre votre appel watch initial et la réception du message de notification partagé dans l'exemple précédent, transmettez 1234567890 en tant que startHistoryId à history.list.
Ensuite,9876543210 peut être conservé comme historyId connu le plus récent pour les futurs cas d'utilisation.
Si vous avez configuré un abonnement par extraction, consultez les exemples de code du Guide pour les abonnés Cloud Pub/Sub pour en savoir plus sur la réception des messages.
Répondre aux 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 diffusion 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 pour les abonnés Cloud Pub/Sub.
Si la réception des notifications n'est pas confirmée (par exemple, si le rappel de votre webhook renvoie une erreur ou expire), Cloud Pub/Sub tentera à 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 stop. Toutes les nouvelles notifications devraient s'arrêter au bout de quelques minutes.
Limites
Taux maximal de notifications
Chaque utilisateur Gmail surveillé est soumis à un taux de notification maximal d'un événement par seconde. Toutes les notifications d'utilisateur dépassant ce taux seront supprimées. Soyez prudent lorsque vous gérez les notifications pour ne pas en déclencher une autre et ainsi démarrer une boucle de notification.
Fiabilité
En règle générale, toutes les notifications doivent être distribuées de manière fiable en quelques secondes. Toutefois, dans certaines situations extrêmes, elles peuvent être retardées ou abandonnées.
Assurez-vous de gérer 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 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, détaillées dans sa documentation sur la tarification et les quotas.