Ce document explique comment utiliser les notifications push pour informer votre application lorsqu'une ressource est modifiée.
Présentation
L'API Google Agenda 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 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 ressource surveillée change, l'API Google Calendar notifie votre application.
Pour utiliser les notifications push, vous devez effectuer deux opérations:
Configurez votre URL de réception ou le 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 est modifiée.
Configurez un (canal de notification) pour chaque point de terminaison de ressource que vous souhaitez surveiller.
Un canal spécifie des informations de routage pour les messages de notification. Lors de la configuration du canal, vous devez identifier l'URL spécifique pour laquelle vous souhaitez recevoir des notifications. Chaque fois que la ressource d'un canal change, l'API Google Agenda envoie un message de notification sous la forme d'une requête
POST
à cette URL.
Actuellement, l'API Google Agenda accepte les notifications concernant les modifications apportées aux ressources Acl, CalendarList, Événements et Paramètres.
Créer des canaux de notification
Pour demander des notifications push, vous devez configurer un canal de notification pour chaque ressource à surveiller. Une fois vos canaux de notification configurés, l'API Google Calendar informe votre application lorsqu'une ressource surveillée change.
Envoyer des demandes de visionnage
Chaque ressource de l'API Google Calendar consultable est associée à une méthode watch
sur 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 requête POST
à la méthode watch
de la ressource.
Chaque canal de notification est associé à la fois à un utilisateur particulier et à une ressource (ou un ensemble de ressources) particulière. Une requête watch
n'aboutira que si l'utilisateur actuel est le propriétaire de cette ressource ou est autorisé à y accéder.
Exemple
Pour surveiller les modifications apportées à un ensemble 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", // Your channel ID. "type": "web_hook", "address": "https://mydomain.com/notifications", // Your receiving URL. ... "token": "target=myApp-myCalendarChannelDest", // (Optional) Your channel token. "expiration": 1426325213000 // (Optional) Your requested channel expiration time. }
Propriétés obligatoires
Pour chaque requête watch
, vous devez renseigner les champs suivants:
-
Une chaîne de propriété
id
qui identifie de manière unique ce nouveau canal de notification au sein de votre projet. Nous vous recommandons d'utiliser un identifiant unique universel (UUID) ou toute chaîne unique similaire. Ne doit pas dépasser 64 caractères.La valeur d'ID que vous avez définie est renvoyée dans l'en-tête HTTP
X-Goog-Channel-Id
de chaque message de notification que vous recevez pour ce canal. -
Une chaîne de propriété
type
définie sur la valeurweb_hook
. -
Chaîne de propriété
address
définie sur l'URL qui écoute les notifications de ce canal de notification et y répond. Il s'agit de l'URL de rappel de votre webhook, qui doit utiliser le protocole HTTPS.Notez que l'API Google Agenda 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 l'objet ne correspond pas au nom d'hôte cible
Propriétés facultatives
Vous pouvez également spécifier les champs facultatifs suivants dans votre requête watch
:
-
Propriété
token
qui spécifie une valeur de chaîne arbitraire à utiliser comme jeton de canal. Vous pouvez utiliser les jetons de canal de notification à diverses 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 spoofing) 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 l'en-tête HTTP
X-Goog-Channel-Token
de chaque message de notification reçu par votre application pour ce canal.Si vous utilisez des jetons de canal de notification, nous vous recommandons de procéder comme suit:
Utilisez un format d'encodage extensible, tel que des paramètres de requête d'URL. Exemple :
forwardTo=hr&createdBy=mobile
N'incluez pas de données sensibles telles que des jetons OAuth.
-
Une chaîne de propriété
expiration
définie sur un horodatage Unix (en millisecondes) correspondant à la date et à l'heure auxquelles vous souhaitez que l'API Google Agenda cesse d'envoyer des messages pour ce canal de notification.Si un canal possède un délai d'expiration, celui-ci est inclus en tant que valeur de l'en-tête HTTP
X-Goog-Channel-Expiration
(dans un format lisible) dans chaque message de notification reçu par votre application pour ce canal.
Pour en savoir plus sur la requête, reportez-vous à la méthode watch
pour les ressources Acl, CalendarList, Events et Settings dans la documentation de référence de l'API.
Regarder la réponse
Si la requête watch
crée un canal de notification, elle renvoie un code d'état HTTP 200 OK
.
Le corps du message de la réponse de la montre 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"", // ID you specified for this channel. "resourceId": "o3hgv1538sdjfh", // ID of the watched resource. "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events", // Version-specific ID of the watched resource. "token": "target=myApp-myCalendarChannelDest", // Present only if one was provided. "expiration": 1426325213000, // Actual expiration time as Unix timestamp (in ms), if applicable. }
En plus des propriétés que vous avez envoyées dans le cadre de votre requête, les informations renvoyées incluent également resourceId
et resourceUri
, qui permettent d'identifier la ressource surveillée sur ce canal de notification.
Vous pouvez transmettre les informations renvoyées à d'autres opérations du canal de notification, par exemple lorsque vous souhaitez ne plus recevoir de notifications.
Pour en savoir plus sur la réponse, reportez-vous à la méthode watch
pour les ressources Acl, CalendarList, Events et Settings dans la documentation de référence de l'API.
Synchroniser le message
Après avoir créé un canal de notification pour surveiller une ressource, l'API Google Agenda 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 ne souhaitez pas conserver la chaîne, vous pouvez utiliser les valeurs X-Goog-Channel-ID
et X-Goog-Resource-ID
dans un appel pour ne plus recevoir de notifications. Vous pouvez également utiliser la notification sync
pour effectuer une initialisation en vue d'événements ultérieurs.
Le format des messages sync
que l'API Google Calendar envoie à votre URL de réception est indiqué 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
La valeur de l'en-tête HTTP X-Goog-Message-Number
des messages de synchronisation est toujours 1
. Chaque notification suivante pour ce canal comporte un numéro de message supérieur à la précédente, bien que les numéros des messages ne soient 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 internes ou les valeurs par défaut de l'API Google Agenda (la valeur la plus restrictive est utilisée). Le délai d'expiration du canal, le cas échéant, est inclus sous forme d'horodatage Unix (en millisecondes) dans les informations renvoyées par la méthode watch
. De plus, la date et l'heure d'expiration sont incluses (au format lisible) dans chaque message de notification reçu par votre application pour ce canal dans l'en-tête HTTP X-Goog-Channel-Expiration
.
Actuellement, il n'est pas possible de renouveler automatiquement 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 peut y avoir un "chevauchement" de temps pendant lequel les deux canaux de notification de la même ressource sont actifs.
Recevoir les notifications
Chaque fois qu'une ressource surveillée change, votre application reçoit un message de notification décrivant la modification. L'API Google Agenda envoie ces messages en tant que requêtes HTTPS POST
à l'URL que vous avez spécifiée en tant que propriété address
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 les préfixes X-Goog-
.
Certains types de notifications peuvent également inclure un corps de message.
En-têtes
Les messages de notification publiés par l'API Google Calendar à votre URL de réception incluent les en-têtes HTTP suivants:
En-tête | Description |
---|---|
Toujours présent | |
|
UUID ou autre chaîne unique que vous avez fournie pour identifier ce canal de notification. |
|
Entier identifiant ce message pour ce canal de notification. La valeur est toujours 1 pour les messages sync . Le nombre de messages augmente pour chaque message suivant sur le canal, mais ces messages ne sont pas séquentiels. |
|
Valeur opaque identifiant la ressource surveillée. Cet ID est stable entre les versions de l'API. |
|
Nouvel état de la ressource qui a déclenché la notification.
Valeurs possibles : sync , exists ou not_exists .
|
|
Identifiant spécifique à la version de l'API pour la ressource surveillée. |
Parfois présent | |
|
Date et heure d'expiration du canal de notification, exprimées dans un format lisible. Présent uniquement s'il est défini. |
|
Jeton de canal de notification qui a été défini par votre application et que vous pouvez utiliser pour vérifier la source de la notification. Présent uniquement s'il est défini. |
Les messages de notification publiés par l'API Google Calendar à votre URL de réception n'incluent pas de corps. Ces messages ne contiennent pas d'informations spécifiques sur les ressources mises à jour. Vous devrez effectuer un autre appel d'API pour voir tous les détails des modifications.
Exemples
Message de notification de modification pour la collection modifiée d'événements:
POST https://mydomain.com/notifications // Your receiving URL. 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 des API Google et renvoie 500
, 502
, 503
ou 504
, l'API Google Calendar effectue de nouvelles tentatives avec un intervalle exponentiel entre les tentatives.
Tout autre code d'état renvoyé est considéré comme un échec de message.
Comprendre les événements de notification de l'API Google Agenda
Cette section fournit des détails sur les messages de notification que vous pouvez recevoir lorsque vous utilisez les notifications push avec l'API Google Calendar.
Livré quand | ||
---|---|---|
sync |
LCA, listes d'agendas, événements, paramètres. | Une chaîne a bien été créée. Vous devriez commencer à recevoir des notifications le concernant. |
exists |
LCA, listes d'agendas, événements, paramètres. | Une modification a été apportée à une ressource. 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
détermine le moment où les notifications s'arrêtent automatiquement. Vous pouvez choisir de ne plus recevoir de notifications pour un canal particulier avant son expiration en appelant la méthode stop
à l'URI suivant:
https://www.googleapis.com/calendar/v3/channels/stop
Cette méthode nécessite que vous fournissiez au moins les propriétés id
et resourceId
du canal, comme illustré dans l'exemple ci-dessous. Notez que si l'API Google Calendar comporte plusieurs types de ressources ayant des méthodes watch
, il n'existe qu'une seule méthode stop
.
Seuls les utilisateurs disposant des autorisations appropriées peuvent arrêter une chaîne. En particulier :
- Si le canal a été créé par un compte utilisateur standard, seul l'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 ne plus recevoir de notifications:
POST https://www.googleapis.com/calendar/v3/channels/stop Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66", "resourceId": "ret08u3rv24htgh289g" }