Recevoir des notifications push

Ce document explique comment utiliser les notifications push pour informer votre application lorsqu'une ressource change.

Présentation

L'API Google Calendar fournit des notifications push qui vous permettent de surveiller les modifications apportées aux ressources. Vous pouvez utiliser cette fonctionnalité pour améliorer les performances de votre application. Elle vous permet d'éliminer les coûts supplémentaires de réseau et de calcul liés à l'interrogation des ressources pour déterminer si elles ont changé. Chaque fois qu'une ressource surveillée change, l'API Google Calendar envoie une notification à votre application.

Pour utiliser les notifications push, vous devez effectuer deux opérations :

  • Configurer votre URL de réception ou votre récepteur de rappel "webhook".

    Il s'agit d'un serveur HTTPS qui gère les messages de notification de l'API déclenchés lorsqu'une ressource change.

  • Configurer un canal de notification pour chaque point de terminaison de ressource que vous souhaitez surveiller.

    Un canal spécifie les informations de routage des messages de notification messages. Lors de la configuration du canal, vous devez identifier l'URL spécifique à laquelle vous souhaitez recevoir des notifications. Chaque fois que la ressource d'un canal change, l'API Google Calendar envoie un message de notification sous forme de POST requête à cette URL.

Actuellement, l'API Google Calendar est compatible avec les notifications de modification des ressources ACL, CalendarList, Events et Settings.

Créer des canaux de notification

Pour demander des notifications push, vous devez configurer un canal de notification pour chaque ressource que vous souhaitez surveiller. Une fois vos canaux de notification configurés, l'API Google Calendar informe votre application lorsque l'une des ressources surveillées change.

Envoyer des requêtes de surveillance

Chaque ressource de l'API Google Calendar pouvant être surveillée est associée à une watch méthode à un URI au format suivant :

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

Pour configurer un canal de notification pour les messages concernant les modifications apportées à une ressource particulière, envoyez une POST requête à la méthode watch de la ressource.

Chaque canal de notification est associé à un utilisateur et à une ressource (ou un ensemble de ressources) spécifiques. Une requête watch n'aboutira pas si l'utilisateur actuel n'est pas propriétaire de cette ressource ou n'est pas autorisé à y accéder.

Exemple

Commencez à surveiller les modifications apportées à une collection d'événements dans un agenda donné :

POST https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events/watch
Authorization: Bearer auth_token_for_current_user
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

Dans le corps de la requête, indiquez l'id de votre canal, le type en tant que web_hook et votre URL de réception dans address. Vous pouvez également fournir les éléments suivants (facultatif) :

  • Un token à utiliser comme jeton de canal.
  • Un délai expiration en millisecondes pour le délai d'expiration de votre canal demandé.

Propriétés obligatoires

Pour chaque requête watch, vous devez fournir les champs suivants :

  • Une chaîne de propriété id qui identifie de manière unique ce nouveau canal de notification dans votre projet. Nous vous recommandons d'utiliser un identifiant unique universel (UUID) ou toute autre chaîne unique similaire. Longueur maximale : 64 caractères.

    La valeur d'ID que vous définissez est renvoyée dans l' X-Goog-Channel-Id HTTP de chaque message de notification que vous recevez pour ce canal.

  • Une chaîne de propriété type définie sur la valeur web_hook.

  • Une chaîne de propriété address définie sur l'URL qui écoute et répond aux notifications de ce canal de notification. Il s'agit de l'URL de rappel de votre webhook, qui doit utiliser le protocole HTTPS.

    Notez que l'API Google Calendar ne peut envoyer des notifications à cette adresse HTTPS que si un certificat SSL valide est installé sur votre serveur Web. Les certificats non valides sont :

    • les certificats auto-signés ;
    • Certificats signés par une source non fiable
    • Certificats révoqués
    • Certificats dont le sujet ne correspond pas au nom d'hôte cible

Propriétés facultatives

Vous pouvez également spécifier les champs facultatifs suivants avec votre watch requête :

  • Une propriété token qui spécifie une valeur de chaîne arbitraire à utiliser comme jeton de canal. Vous pouvez utiliser des jetons de canal de notification à différentes fins. Par exemple, vous pouvez utiliser le jeton pour vérifier que chaque message entrant est destiné à un canal créé par votre application (pour vous assurer que la notification n'est pas usurpée) ou pour acheminer le message vers la bonne destination dans votre application en fonction de l'objectif de ce canal. Longueur maximale : 256 caractères.

    Le jeton est inclus dans le X-Goog-Channel-Token en-tête HTTP de chaque message de notification que votre application reçoit pour ce canal.

    Si vous utilisez des jetons de canal de notification, nous vous recommandons de :

    • Utiliser un format d'encodage extensible, tel que des paramètres de requête d'URL. Exemple : forwardTo=hr&createdBy=mobile

    • Ne pas inclure de données sensibles, telles que des jetons OAuth.

  • Une chaîne de propriété expiration définie sur un horodatage Unix (en millisecondes) de la date et de l'heure auxquelles vous souhaitez que l'API Google Calendar cesse d'envoyer des messages pour ce canal de notification.

    Si un canal a un délai d'expiration, il est inclus en tant que valeur de l'en-tête HTTP X-Goog-Channel-Expiration (au format lisible ) dans chaque message de notification que votre application reçoit pour ce canal.

Pour en savoir plus sur la requête, consultez la méthode watch pour les ressources ACL, CalendarList, Events et Settings dans la documentation de référence de l'API.

Réponse de surveillance

Si la watch requête crée un canal de notification, elle renvoie un code d'état HTTP 200 OK.

Le corps du message de la réponse de surveillance fournit des informations sur le canal de notification que vous venez de créer, comme illustré dans l'exemple ci-dessous.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events",
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

Le corps de la réponse fournit des détails sur le canal, tels que :

  • kind : identifie cette ressource comme un canal d'API.
  • id : ID que vous avez spécifié pour ce canal.
  • resourceId : ID de la ressource surveillée.
  • resourceUri : ID spécifique à la version de la ressource surveillée.
  • token : jeton fourni dans le corps de la requête.
  • expiration : délai d'expiration du canal sous forme d'horodatage Unix en millisecondes.

En plus des propriétés que vous avez envoyées dans votre requête, les informations renvoyées incluent également resourceId et resourceUri pour identifier la ressource surveillée sur ce canal de notification.

Vous pouvez transmettre les informations renvoyées à d'autres opérations de canal de notification, par exemple lorsque vous souhaitez cesser de recevoir des notifications.

Pour en savoir plus sur la réponse, consultez la watch méthode pour les ressources ACL, CalendarList, Events et Settings dans la documentation de référence de l'API.

Message de synchronisation

Après avoir créé un canal de notification pour surveiller une ressource, l' API Google Calendar envoie un message sync pour indiquer que les notifications commencent. La valeur de l'en-tête HTTP X-Goog-Resource-State pour ces messages est sync. En raison de problèmes de synchronisation du réseau, il est possible de recevoir le message sync avant même de recevoir la réponse de la méthode watch.

Vous pouvez ignorer la notification sync, mais vous pouvez également l'utiliser. Par exemple, si vous décidez de ne pas conserver le canal, vous pouvez utiliser les valeurs X-Goog-Channel-ID et X-Goog-Resource-ID dans un appel pour cesser de recevoir des notifications. Vous pouvez également utiliser la sync notification pour effectuer une initialisation afin de vous préparer à des événements ultérieurs.

Le format des messages sync que l'API Google Calendar envoie à votre URL de réception est présenté ci-dessous.

POST https://mydomain.com/notifications // Your receiving URL.
X-Goog-Channel-ID: channel-ID-value
X-Goog-Channel-Token: channel-token-value
X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires.
X-Goog-Resource-ID: identifier-for-the-watched-resource
X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource
X-Goog-Resource-State: sync
X-Goog-Message-Number: 1

Les messages de synchronisation ont toujours une valeur d'en-tête HTTP X-Goog-Message-Number de 1. Chaque notification suivante pour ce canal a un numéro de message supérieur au précédent, mais les numéros de message ne sont pas séquentiels.

Renouveler les canaux de notification

Un canal de notification peut avoir un délai d'expiration, avec une valeur déterminée par votre requête ou par les limites ou valeurs par défaut internes de l'API Google Calendar ou par défaut (la valeur la plus restrictive est utilisée). Le délai d'expiration du canal, s'il en a un, est inclus en tant qu'horodatage Unix (en millisecondes) dans les informations renvoyées par la watch méthode. De plus, la date et l'heure d'expiration sont incluses (au format lisible) dans chaque message de notification que votre application reçoit pour ce canal dans l' X-Goog-Channel-Expiration en-tête HTTP.

Actuellement, il n'existe aucun moyen automatique de renouveler un canal de notification. Lorsqu' un canal est sur le point d'expirer, vous devez le remplacer par un nouveau en appelant la méthode watch. Comme toujours, vous devez utiliser une valeur unique pour la propriété id du nouveau canal. Notez qu'il est probable qu'il y ait une période de « chevauchement » pendant laquelle les deux canaux de notification pour la même ressource sont actifs.

Recevoir des notifications

Chaque fois qu'une ressource surveillée change, votre application reçoit un message de notification décrivant la modification. L'API Google Calendar envoie ces messages sous forme de requêtes POST HTTPS à l'URL que vous avez spécifiée comme address propriété pour ce canal de notification.

Interpréter le format du message de notification

Tous les messages de notification incluent un ensemble d'en-têtes HTTP avec des X-Goog- préfixes. Certains types de notifications peuvent également inclure un corps du message.

En-têtes

Les messages de notification publiés par l'API Google Calendar sur votre URL de réception incluent les en-têtes HTTP suivants :

En-tête Description
Toujours présent
X-Goog-Channel-ID UUID ou autre chaîne unique que vous avez fournie pour identifier ce canal de notification.
X-Goog-Message-Number Entier qui identifie ce message pour ce canal de notification La valeur est toujours 1 pour les messages sync. Les numéros de message augmentent pour chaque message suivant sur le canal, mais ils ne sont pas séquentiels.
X-Goog-Resource-ID Valeur opaque identifiant la ressource surveillée. Cet ID est stable dans toutes les versions de l'API.
X-Goog-Resource-State Le nouvel état de la ressource qui a déclenché la notification. Valeurs possibles : sync, exists ou not_exists.
X-Goog-Resource-URI Identifiant spécifique à la version de l'API pour la ressource surveillée.
Parfois présent
X-Goog-Channel-Expiration Date et heure d'expiration du canal de notification, exprimées au format lisible. N'est présent que s'il est défini.
X-Goog-Channel-Token Jeton de canal de notification défini par votre application et que vous pouvez utiliser pour vérifier la source de la notification. N'est présent que s'il est défini.

Les messages de notification publiés par l'API Calendar sur votre URL de réception n'incluent pas de corps de message. Ces messages ne contiennent pas d'informations spécifiques sur les ressources mises à jour. Vous devez effectuer un autre appel d'API pour afficher tous les détails de la modification.

Exemple

Message de notification de modification pour une collection d'événements modifiée :

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events
X-Goog-Resource-State:  exists
X-Goog-Message-Number: 10

Répondre à des notifications

Pour indiquer que l'opération a réussi, vous pouvez renvoyer l'un des codes d'état suivants : 200, 201, 202, 204, ou 102.

Si votre service utilise la bibliothèque cliente de l'API Google et renvoie 500,502, 503, ou 504, l'API Google Calendar effectue une nouvelle tentative avec un intervalle exponentiel. Tout autre code d'état renvoyé est considéré comme un échec de message.

Comprendre les événements de notification de l'API Google Calendar

Cette section fournit des informations sur les messages de notification que vous pouvez recevoir lorsque vous utilisez des notifications push avec l'API Google Calendar.

X-Goog-Resource-State Applicable à Livré lorsque
sync ACL, listes d'agendas, événements, paramètres. Un canal a bien été créé. Les notifications peuvent désormais être reçues.
exists ACL, listes d'agendas, événements, paramètres. Une ressource a changé. Les modifications possibles incluent la création d'une ressource, ou la modification ou la suppression d'une ressource existante.

Arrêter les notifications

La propriété expiration contrôle le moment où les notifications s'arrêtent automatiquement. Vous pouvez choisir de cesser de recevoir des notifications pour un canal particulier avant son expiration en appelant la méthode stop à l'URI suivant :

https://www.googleapis.com/workspace/calendar/api/v3/reference/channels/stop

Cette méthode nécessite que vous fournissiez au moins les propriétés du canal id et les resourceId, comme illustré dans l'exemple ci-dessous. Notez que si l'API Google Calendar comporte plusieurs types de ressources disposant de watch méthodes, il n'existe qu'une seule stop méthode.

Seuls les utilisateurs disposant de l'autorisation appropriée peuvent arrêter un canal. En particulier :

  • Si le canal a été créé par un compte utilisateur standard, seul le même utilisateur du même client (identifié par les ID client OAuth 2.0 des jetons d'authentification) qui a créé le canal peut l'arrêter.
  • Si le canal a été créé par un compte de service, n'importe quel utilisateur du même client peut l'arrêter.

L'exemple de code suivant montre comment cesser de recevoir des notifications :

POST https://www.googleapis.com/workspace/calendar/api/v3/reference/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}