Notifications push

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. Cela vous permet d'éliminer les coûts de réseau et de calcul supplémentaires liés à l'interrogation des ressources afin de déterminer si elles ont changé. Chaque fois qu'une boîte aux lettres est modifiée, l'API Gmail en notifie votre application de serveur backend.

Configuration initiale de Cloud Pub/Sub

L'API Gmail utilise l'API Cloud Pub/Sub pour diffuser les notifications push. Cela permet d'envoyer des notifications via diverses méthodes, y compris des webhooks et des interrogations sur un seul point de terminaison d'abonnement.

Conditions préalables

Pour terminer la configuration, assurez-vous de remplir les conditions préalables liées à 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 correspondre à n'importe quel nom de votre projet (par exemple, projects/myproject/topics/*, où myproject est l'ID de votre projet dans la Google Play Console).

En raison des limites de Cloud Pub/Sub concernant le nombre de sujets, nous vous recommandons d'utiliser un seul sujet pour toutes les notifications push de l'API Gmail de votre application.

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" (rappel HTTP POST) ou "Pull" (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 d'autorisations de la console développeur Cloud Pub/Sub en suivant les instructions de contrôle des accès au niveau des ressources.

Recevoir des mises à jour de la 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 boîtes aux lettres.

Demande de visionnage

Pour configurer les comptes Gmail afin qu'ils envoient des notifications à votre sujet Cloud Pub/Sub, utilisez simplement votre client de l'API Gmail pour appeler watch sur la boîte aux lettres utilisateur Gmail, comme pour n'importe quel autre appel d'API Gmail. Pour ce faire, fournissez le nom du sujet créé ci-dessus et toutes les autres options de votre requête watch, telles que labels, sur lesquelles vous souhaitez filtrer les résultats. 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 recevez une réponse semblable à celle-ci:

{
  historyId: 1234567890
  expiration: 1431990098200
}

avec la boîte aux lettres actuelle historyId de l'utilisateur. Toutes les modifications apportées par la suite historyId seront notifiées à votre client. Si vous devez traiter des modifications antérieures à 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 lors de l'appel watch, les détails doivent expliquer la source du problème, qui concerne généralement la configuration du sujet et de l'abonnement Cloud Pub/Sub. Reportez-vous à la documentation Cloud Pub/Sub pour vérifier que la configuration est correcte et obtenir de l'aide pour déboguer les problèmes de sujet et d'abonnement.

Renouvellement de la montre avec boîte aux lettres...

Vous devez rappeler watch au moins tous les sept jours, sinon vous ne recevrez plus de notifications pour l'utilisateur. Nous vous recommandons d'appeler watch une fois par jour. La réponse watch comporte également un champ d'expiration avec l'horodatage correspondant à la date d'expiration watch.

Recevoir des notifications

Chaque fois qu'une mise à jour de boîte aux lettres correspondant à votre watch est effectuée, 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 HTTP POST est au format JSON et la charge utile réelle de la notification Gmail se trouve dans le champ message.data. Ce champ message.data est une chaîne encodée en base64url qui est décode en 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 history.list pour obtenir les détails des modifications de l'utilisateur en fonction de son dernier identifiant d'historique, conformément au guide de synchronisation.

Si vous avez configuré un abonnement pull, reportez-vous aux exemples de code du Guide d'extraction 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 distribution push d'un webhook, toute réponse réussie (par exemple, HTTP 200) accuse réception de la notification.

Si vous utilisez la distribution pull (REST Pull, RPC Pull ou RPC StreamingPull), vous devez effectuer un suivi avec un appel de confirmation (REST ou RPC). Reportez-vous aux exemples de code du guide d'extraction des abonnés Cloud Pub/Sub pour découvrir comment confirmer les messages de manière asynchrone ou synchrone à l'aide des bibliothèques clientes officielles basées sur RPC.

Si les notifications ne sont pas confirmées (par exemple, votre rappel de webhook renvoie une erreur ou expire), Cloud Pub/Sub relance la notification ultérieurement.

Arrêt des mises à jour de la boîte aux lettres

Pour ne plus recevoir de notifications sur une boîte aux lettres, appelez stop. Toutes les nouvelles notifications doivent s'arrêter au bout de quelques minutes.

Limites

Taux de notification maximal

Chaque utilisateur Gmail surveillé a un taux de notification maximal d'un événement/s. Les notifications utilisateur dépassant cette fréquence seront ignorées. Lorsque vous gérez des notifications, veillez à ne pas déclencher d'autre notification, et donc à démarrer une boucle de notifications.

Fiabilité

En règle générale, toutes les notifications doivent être transmises de manière fiable en quelques secondes. Toutefois, dans certaines situations extrêmes, les notifications peuvent être retardées ou abandonnées. Veillez à gérer cette éventualité de manière optimale, afin que l'application se synchronise toujours, 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 notification pour un utilisateur.

Limites de Cloud Pub/Sub

L'API Cloud Pub/Sub présente également ses propres limites, qui sont détaillées dans sa documentation sur les pricing et les quotas.