Ce document explique comment utiliser les notifications push qui informent vos en cas de modification d'une ressource.
Présentation
L'API Google Agenda fournit des notifications push qui vous permettent de surveiller des changements de ressources. Vous pouvez utiliser cette fonctionnalité pour améliorer les performances votre application. Il vous permet d'éliminer les tâches de réseau et de calcul les coûts liés aux ressources de sondage pour déterminer si elles ont changé. Chaque fois qu'une ressource surveillée est modifiée, l'API Google Calendar informe vos application.
Pour utiliser les notifications push, vous devez:
Configurer votre URL de réception ou votre "webhook" destinataire de rappel.
Ce est un serveur HTTPS qui gère les messages de notification API déclenché lorsqu'une ressource est modifiée.
Configurez un (canal de notification) pour chaque point de terminaison de ressource que vous souhaitez montre.
Un canal spécifie les informations de routage pour les notifications messages. Lors de la configuration de la chaîne, vous devez identifier l'URL spécifique 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
à cette URL.
Actuellement, l'API Google Calendar est compatible avec les notifications concernant les modifications apportées à les 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 définis l'API Google Calendar informe votre application lorsqu'une ressource surveillée des modifications.
Envoyer des demandes de visionnage
Chaque ressource de l'API Google Calendar pouvant être surveillée est associée à
watch
à 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
ressource spécifique, envoyez une requête POST
au
watch
pour la ressource.
Chaque canal de notification est associé à la fois à un utilisateur particulier et
une ressource spécifique (ou un ensemble de ressources). Une requête watch
ne fonctionne que si l'utilisateur actuel
est propriétaire de cette ressource ou est autorisé à y accéder.
Exemple
Pour commencer à surveiller les modifications apportées à une collection d'événements dans un agenda donné:
POST https://www.googleapis.com/calendar/v3/calendars/[email protected]/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 fournir les champs suivants:
-
Une chaîne de propriété
id
qui l'identifie de manière unique un nouveau canal de notification dans votre projet. Nous vous recommandons d'utiliser un identifiant unique universel (UUID) ou tout autre code similaire chaîne unique. Ne doit pas dépasser 64 caractères.La valeur d'ID que vous avez définie est renvoyée dans le En-tête HTTP
X-Goog-Channel-Id
de chaque notification qui vous est envoyé pour cette chaîne. -
Une chaîne de propriété
type
définie sur la valeurweb_hook
-
Une chaîne de propriété
address
définie sur l'URL qui écoute et répond aux notifications pour ce canal de notification. C'est l'URL de rappel du webhook. Elle doit utiliser HTTPS.Notez que l'API Google Calendar peut envoyer des notifications aux cette adresse HTTPS uniquement 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 à la cible nom d'hôte.
Propriétés facultatives
Vous pouvez également spécifier ces champs facultatifs avec votre
Requête watch
:
-
Une propriété
token
qui spécifie une chaîne arbitraire à utiliser comme jeton de canal. Vous pouvez utiliser le canal de notification des jetons à des fins diverses. Par exemple, vous pouvez utiliser la pour vérifier que chaque message entrant est destiné à un canal application créée) pour s'assurer que la notification n'est pas ou pour acheminer le message vers la bonne destination votre demande en fonction de l'objectif de ce canal. Longueur maximale: 256 caractères.Le jeton est inclus dans En-tête HTTP
X-Goog-Channel-Token
dans chaque notification que votre application reçoit pour ce canal.Si vous utilisez des jetons de canal de notification, nous vous recommandons de:
Utilisez un format d'encodage extensible, tel que les requêtes d'URL. paramètres. Exemple :
forwardTo=hr&createdBy=mobile
N'incluez pas de données sensibles telles que les jetons OAuth.
-
Une chaîne de propriété
expiration
définie sur Code temporel Unix (en millisecondes) de la date et de l'heure auxquelles l'API Google Calendar doit arrêter d'envoyer des messages pour ce canal de notification.Si un canal a un délai d'expiration, celui-ci est inclus comme valeur de l'en-tête HTTP
X-Goog-Channel-Expiration
(dans un format lisible ) dans chaque message de notification que l'application reçoit 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 une notification
canal, 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"", // ID you specified for this channel. "resourceId": "o3hgv1538sdjfh", // ID of the watched resource. "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/[email protected]/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 votre demande, le
les informations renvoyées incluent également les champs resourceId
et
resourceUri
pour identifier la ressource surveillée
canal de notification.
Vous pouvez transmettre les informations renvoyées à un autre canal de notification par exemple lorsque vous voulez arrêter de recevoir notifications.
Pour en savoir plus sur la réponse, consultez le 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 Calendar envoie un message sync
pour indiquer que
Les notifications ont démarré. Le protocole HTTP X-Goog-Resource-State
la valeur d'en-tête de ces messages est sync
. En raison du réseau
des problèmes de synchronisation, 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 X-Goog-Channel-ID
et
X-Goog-Resource-ID
valeurs dans un appel de
ne plus recevoir de notifications. Vous pouvez également utiliser
Notification sync
pour effectuer une initialisation en vue de
les événements ultérieurs.
Format des messages sync
envoyés par l'API Google Calendar
votre URL de réception est indiquée 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 un code HTTP X-Goog-Message-Number
la valeur d'en-tête de 1
. Chaque notification ultérieure pour cette chaîne
un numéro de message plus grand que le précédent, même si le message
ne se suivent pas.
Renouveler les canaux de notification
Un canal de notification peut avoir un délai d'expiration, avec une valeur
déterminé par votre demande ou par les limites internes de l'API Google Calendar
ou par défaut (la valeur utilisée est la plus restrictive). La date d'expiration de la chaîne
l'heure, le cas échéant, est incluse sous la forme d'un code temporel Unix.
(en millisecondes) dans les informations renvoyées par la méthode watch
. En outre,
la date et l'heure d'expiration sont indiquées (au format intelligible) dans chaque
de notification reçu par votre application pour ce canal dans le
En-tête HTTP X-Goog-Channel-Expiration
.
Il n'existe actuellement aucun moyen automatique de renouveler un canal de notification. Quand ?
d'un canal 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
soit un "chevauchement" période pendant laquelle les deux canaux de notification
même ressource sont actifs.
Recevoir des notifications
Chaque fois qu'une ressource surveillée est modifiée, votre application reçoit une
de notification décrivant la modification. L'API Google Calendar envoie ces
les messages en tant que requêtes HTTPS POST
vers l'URL que vous avez spécifiée en tant que
Propriété address
pour cette notification
canal.
Interpréter le format du message de la notification
Tous les messages de notification incluent un ensemble d'en-têtes HTTP contenant
Préfixes X-Goog-
.
Certains types de notifications peuvent également inclure
corps du message.
En-têtes
les messages de notification envoyés par l'API Google Calendar à votre adresse e-mail L'URL comprend les en-têtes HTTP suivants:
En-tête | Description |
---|---|
Toujours présenter | |
|
UUID ou autre chaîne unique que vous avez fournie pour identifier cet élément canal de notification. |
|
Entier qui identifie ce message pour cette notification
canal. La valeur est toujours 1 pour les messages sync . Envoyer un message
nombres augmentent pour chaque message ultérieur sur le canal, mais ils sont
et non séquentielles. |
|
Valeur opaque identifiant la ressource surveillée. Cet ID est stable entre les versions de l'API. |
|
Nouvel état de la ressource ayant 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 au format dans un format lisible par l'humain. Présent uniquement si défini. |
|
Un jeton de canal de notification défini par votre application que vous pouvez utiliser pour vérifier la source de notification. Présent uniquement si définis. |
Les messages de notification publiés par l'API Google 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 devrez effectuer un autre appel d'API pour afficher 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/[email protected]/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 de Google
et renvoie 500
, 502
, 503
ou 504
, l'API Google Calendar
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 Calendar
Cette section fournit des informations sur les messages de notification que vous pouvez recevoir en cas d'utilisation de notifications push avec l'API Google Calendar.
Distribué lorsque | ||
---|---|---|
sync |
LCA, listes d'agendas, événements et paramètres. | Un critère a bien été créé. Vous devriez commencer à recevoir des notifications à ce sujet. |
exists |
LCA, listes d'agendas, événements et 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
contrôle à quel moment les notifications s'arrêtent automatiquement. Vous pouvez
choisir de ne plus recevoir les notifications d'une chaîne en particulier
expire en appelant la méthode stop
l'URI suivant:
https://www.googleapis.com/calendar/v3/channels/stop
Pour utiliser cette méthode, vous devez indiquer au moins
id
et resourceId
, comme indiqué dans les
dans l'exemple ci-dessous. Notez que si l'API Google Calendar comporte plusieurs types de
ressources comportant des méthodes watch
, il n'y en a qu'une
stop
.
Seuls les utilisateurs disposant des autorisations appropriées peuvent arrêter une chaîne. En particulier :
- Si la chaîne a été créée par un compte utilisateur standard, seul le même du même client (identifié par les ID client OAuth 2.0 du jetons d'authentification) qui l'a créée peuvent l'arrêter.
- Si le canal a été créé par un compte de service, tout utilisateur du même le client peut arrêter la chaîne.
L'exemple de code suivant montre comment arrêter de recevoir des 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" }