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

Notifications push

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/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 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 valeur web_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.
Remarque:Si vous devez envoyer des messages très sensibles données, assurez-vous qu'elles sont chiffrées avant de les ajouter à un jeton d'accès.
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/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 votre demande, le les informations renvoyées incluent également les champs resourceId et resourceUri pour identifier la ressource surveillée canal de notification.

Remarque:La propriété resourceId est une stable et indépendant de la version de la ressource. La La propriété resourceUri correspond à l'URI canonique de la propriété ressource dans le contexte de la version actuelle de l'API. spécifique à chaque version.

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.

Remarque:Requêtes HTTPS de diffusion de notifications spécifier un user-agent APIs-Google et respecter le fichier robots.txt comme décrit dans la section API Google user-agent

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
`X-Goog-Channel-ID`	UUID ou autre chaîne unique que vous avez fournie pour identifier cet élément canal de notification.
`X-Goog-Message-Number`	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.
`X-Goog-Resource-ID`	Valeur opaque identifiant la ressource surveillée. Cet ID est stable entre les versions de l'API.
`X-Goog-Resource-State`	Nouvel état de la ressource ayant 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 dans un format lisible par l'humain. Présent uniquement si défini.
`X-Goog-Channel-Token`	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/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 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.

X-Goog-Resource-State	Applicable à	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"
}

Considérations particulières

Lorsque vous utilisez les notifications push, tenez compte des points suivants:

Événements et LCA par agenda Si vous souhaitez être informé de toutes les modifications d'événements ou de LCA pour les agendas A et B, vous devez vous abonner séparément aux événements/collections LCA pour A et B.

Les paramètres et les listes d'agendas sont définis par utilisateur Les paramètres et les listes d'agendas ne peuvent contenir qu'une collection par utilisateur. Vous ne pouvez donc vous abonner qu'une seule fois.

Par ailleurs, vous ne recevez pas de notification lorsque vous accédez à une nouvelle collection (un nouvel agenda, par exemple). Toutefois, vous êtes averti si cet agenda est ajouté à la liste (à condition que vous soyez abonné à la collection associée).

Les notifications ne sont pas fiables à 100 %. Attendez-vous à ce qu'un faible pourcentage de messages soit abandonné dans des conditions de travail normales. Veillez à gérer ces messages manquants correctement, de sorte que l'application se synchronise toujours si aucun message push n'est reçu.