Cette page a été traduite par l'API Cloud Translation.

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. Il vous permet d'éliminer les coûts 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 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).

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 (par exemple, 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:

ProtocolePython

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()

Réponse de la montre

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 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 l'ID de l'historique de la nouvelle 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.

Par exemple, pour utiliser history.list pour identifier les modifications qui se sont produites entre votre appel initial watch 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é en tant qu'dernier ID d'historique connu pour les futurs cas d'utilisation.

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. Toute notification utilisateur supérieure à ce taux sera supprimée. 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 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 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.