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 réseau et de calcul supplémentaires associés à l'interrogation des ressources pour déterminer si elles ont changé. Chaque fois qu'une boîte aux lettres change, l'API Gmail en informe votre application de 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 via différentes méthodes, y compris des webhooks et des requêtes par sondage sur un seul point de terminaison d'abonnement.
Prérequis
Pour terminer cette configuration, assurez-vous de remplir les conditions préalables à 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 des notifications. Le nom du sujet peut être celui que vous choisissez dans votre projet (c'est-à-dire correspondant à projects/myproject/topics/*, où myproject est l'ID de projet indiqué pour votre projet dans la Google Developers Console).
Nous vous recommandons d'utiliser un seul sujet pour toutes les notifications push de l'API Gmail de votre application, en raison des limites Cloud Pub/Sub sur le nombre de sujets.
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 un push webhook (c'est-à-dire un rappel POST HTTP) ou un pull (c'est-à-dire initié par votre application). Votre application recevra ainsi des notifications de mises à 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 des droits publish à gmail-api-push@system.gserviceaccount.com. Pour ce faire, utilisez l'interface d'autorisations de la console de développement Cloud Pub/Sub en suivant les instructions de contrôle des accès au niveau des ressources.
Recevoir des notifications de boîte aux lettres Gmail
Une fois la configuration initiale de Cloud Pub/Sub terminée, configurez les comptes Gmail pour envoyer des notifications de mise à jour de la boîte aux lettres.
Demande de visionnage
Pour configurer des comptes Gmail afin d'envoyer des notifications à votre sujet Cloud Pub/Sub, utilisez simplement 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 toutes les autres options dans votre requête watch, telles que labels à filtrer. Par exemple, 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 recevrez une réponse semblable à la suivante:
{
historyId: 1234567890
expiration: 1431990098200
}
avec la boîte aux lettres historyId actuelle de l'utilisateur. Toutes les modifications apportées après ce historyId seront communiquées à votre client. Si vous devez traiter des modifications avant cette 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 doivent expliquer la source du problème, qui est généralement liée à 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 déboguer 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 ne recevrez plus de mises à jour pour 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 la 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 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 de la requête POST HTTP est au format JSON, et la charge utile de notification Gmail se trouve dans le champ message.data. Ce champ message.data est une chaîne encodée en base64url qui se décode en objet JSON contenant l'adresse e-mail et le nouvel ID d'historique de boîte de réception de l'utilisateur:
{"emailAddress": "user@example.com", "historyId": "9876543210"}
Vous pouvez ensuite utiliser history.list pour obtenir les détails des modifications apportées à l'utilisateur depuis son dernier ID d'historique connu, conformément au guide de synchronisation.
Si vous avez configuré un abonnement pull à la place, consultez les exemples de code du Guide de pull pour les abonnés Cloud Pub/Sub pour en savoir plus sur la réception de messages.
Répondre aux notifications
Toutes les notifications doivent être confirmées. Si vous utilisez la diffusion push par webhook, une réponse réussie (par exemple, HTTP 200) confirmera la notification.
Si vous utilisez la méthode de diffusion pull (REST Pull, RPC Pull ou RPC StreamingPull), vous devez envoyer un appel d'acquittement (REST ou RPC). Pour en savoir plus sur la confirmation 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 de pull pour les abonnés Cloud Pub/Sub.
Si les notifications ne sont pas confirmées (par exemple, si votre rappel de webhook renvoie une erreur ou expire), Cloud Pub/Sub réessaiera de les envoyer ultérieurement.
Arrêter les mises à jour des boîtes aux lettres
Pour ne plus recevoir de notifications sur une boîte de réception, appelez stop. Toutes les nouvelles notifications devraient cesser dans quelques minutes.
Limites
Fréquence maximale des notifications
Chaque utilisateur Gmail surveillé a un taux de notification maximal de 1 événement/s. Toutes les notifications utilisateur dépassant ce taux seront supprimées. Faites attention lorsque vous gérez les notifications pour vous assurer de ne pas déclencher une autre notification et de ne pas démarrer une boucle de notification.
Fiabilité
En général, 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 appropriée, afin que l'application se synchronise toujours, même si aucun message push n'est reçu. Par exemple, utilisez l'appel périodique de history.list après une période sans notification pour un utilisateur.
Limites de Cloud Pub/Sub
L'API Cloud Pub/Sub présente également ses propres limites, détaillées dans la documentation sur les tarifs et les quotas.