Notifications push

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

Présentation

L'API Directory 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. Il vous permet d'éliminer les coûts de réseau et de calcul supplémentaires liés à l'interrogation des ressources pour déterminer si elles ont changé. Chaque fois qu'une ressource surveillée change, l'API Directory envoie une notification à votre application.

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

Configurez 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.
Configurez un canal de notification pour chaque point de terminaison de ressource que vous souhaitez surveiller.
Un canal spécifie les informations de routage pour les messages de notification. Lors de la configuration du canal, vous devez identifier l'URL spécifique à laquelle vous souhaitez recevoir les notifications. Chaque fois que la ressource d'un canal change, l'API Directory envoie un message de notification sous forme de requête POST à cette URL.

Actuellement, l'API Directory est compatible avec les notifications de modifications apportées à la ressource Users.

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 Directory informe votre application lorsque des ressources surveillées changent.

Envoyer des requêtes à la montre

Chaque ressource de l'API Directory pouvant être surveillée est associée à une méthode watch à un URI de la forme suivante :

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 spécifique, envoyez une requête POST à la méthode watch pour la ressource.

Chaque canal de notification est associé à un utilisateur et à une ressource (ou un ensemble de ressources) spécifiques. Une requête watch ne sera traitée que si l'utilisateur actuel ou le compte de service possède cette ressource ou est autorisé à y accéder.

Exemples

Toutes les demandes de surveillance de la ressource User pour un seul domaine se présentent sous la forme générale suivante :

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=domain&event=event
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-myFilesChannelDest",
  "params": {
    "ttl": 3600
  }
}

Dans le corps de la requête, indiquez le id de votre chaîne, le type comme web_hook et votre URL de réception dans address. Vous pouvez également fournir les informations facultatives suivantes :

Un token à utiliser comme jeton de chaîne.
ttl dans params pour demander un délai avant expiration pour ce canal en secondes.

Utilisez les paramètres domain et event pour spécifier le domaine et le type d'événement pour lesquels vous souhaitez recevoir des notifications.

Toutes les demandes de surveillance de la ressource User pour un client se présentent sous la forme générale suivante :

POST https://admin.googleapis.com/admin/directory/users/v1/watch?customer=customer&event=event
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-myFilesChannelDest",
  "params": {
    "ttl": 3600
  }
}

Utilisez les paramètres customer et event pour spécifier l'ID unique du compte Google du client et le type d'événement pour lequel vous souhaitez recevoir des notifications.

Les valeurs possibles pour event sont les suivantes :

add : événement créé par l'utilisateur
delete : événement de suppression d'utilisateur
makeAdmin : événement de modification de l'état d'administrateur d'un utilisateur
undelete : événement de restauration d'un utilisateur
update : événement de mise à jour de l'utilisateur

Remarque : Pour plus de clarté, les exemples suivants omettent le corps de la requête.

Surveillez les événements créés par les utilisateurs pour le domaine mydomain.com :

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=mydomain.com&event=add

Surveillez les événements créés par l'utilisateur pour le client my_customer :

POST https://admin.googleapis.com/admin/directory/v1/users/watch?customer=my_customer&event=add

Propriétés obligatoires

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

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 chaîne unique similaire. Longueur maximale : 64 caractères.

La valeur d'ID que vous définissez est renvoyée dans l'en-tête HTTP X-Goog-Channel-Id de chaque message de notification que vous recevez pour ce canal.
Chaîne de propriété type définie sur la valeur web_hook.
Chaîne de propriété address définie sur l'URL qui écoute et répond aux notifications pour ce canal de notification. Il s'agit de l'URL de rappel de votre webhook, qui doit utiliser HTTPS.

Notez que l'API Directory ne peut envoyer de 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 ces champs facultatifs avec 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 à 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 l'en-tête HTTP X-Goog-Channel-Token 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 :
- Utilisez un format d'encodage extensible, tel que les paramètres de requête d'URL. Exemple : forwardTo=hr&createdBy=mobile
- N'incluez pas de données sensibles, comme des jetons OAuth.
Remarque : Si vous devez envoyer des données très sensibles, assurez-vous qu'elles sont chiffrées avant de les ajouter au jeton.
Chaîne de propriété expiration définie sur un code temporel Unix (en millisecondes) de la date et de l'heure auxquelles vous souhaitez que l'API Directory cesse d'envoyer des messages pour ce canal de notification.

Si un canal a une heure d'expiration, elle est incluse en tant que valeur de l'en-tête HTTP X-Goog-Channel-Expiration (au format lisible par l'homme) 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 la ressource Users 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",
  "resourceId": "B4ibMJiIhTjAQd7Ff2K2bexk8G4",
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 1384823632000
}

Le corps de la réponse fournit des informations sur la chaîne, telles que :

id : ID que vous avez spécifié pour ce canal.
resourceId : ID de la ressource observée.
resourceUri : ID spécifique à la version de la ressource observé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.

Remarque : La propriété resourceId est un identifiant stable et indépendant de la version pour la ressource. La propriété resourceUri est l'URI canonique de la ressource observée dans le contexte de la version actuelle de l'API. Elle est donc spécifique à la version.

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 méthode watch de la ressource Users 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 Directory 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 sans problème, mais vous pouvez aussi 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 à arrêter de recevoir des 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 Directory 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

Les messages de synchronisation ont toujours une valeur d'en-tête HTTP X-Goog-Message-Number de 1. Chaque notification ultérieure pour ce canal comporte 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 une durée d'expiration, avec une valeur déterminée par votre demande ou par les limites ou valeurs par défaut internes de l'API Directory (la valeur la plus restrictive est utilisée). Le cas échéant, l'heure d'expiration de la chaîne est incluse sous la forme d'un code temporel Unix (en millisecondes) dans les informations renvoyées par la méthode watch. De plus, la date et l'heure d'expiration (au format lisible par l'humain) sont incluses dans chaque message de notification que votre application reçoit pour ce canal dans l'en-tête HTTP X-Goog-Channel-Expiration.

Il n'existe actuellement 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 y aura probablement une période de "chevauchement" pendant laquelle les deux canaux de notification pour la même ressource seront actifs.

Recevoir des notifications

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

Remarque : Les requêtes HTTPS pour la diffusion des notifications spécifient un user-agent APIs-Google et respectent les directives robots.txt, comme décrit dans User-Agent APIs-Google.

Interpréter le format des messages de notification

Tous les messages de notification incluent un ensemble d'en-têtes HTTP avec des 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 Directory 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`	Nombre 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` ou nom d'événement.
`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 dans un format lisible par l'humain. 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 destinés aux utilisateurs contiennent les informations suivantes dans le corps de la requête :

Propriété	Description
`kind`	Identifie cette ressource comme une ressource utilisateur. Valeur : chaîne fixe "`admin#directory#user`".
`id`	Identifiant unique de la ressource utilisateur.
`etag`	ETag du message de notification. Différent de l'ETag de la ressource User.
`primaryEmail`	Adresse e-mail principale de l'utilisateur.

Exemples

Les messages de notification pour les événements de ressources User ont la forme générale suivante :

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: directoryApiId
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event
X-Goog-Resource-State:  event
X-Goog-Message-Number: 10

{
  "kind": "admin#directory#user",
  "id": long,
  "etag": string,
  "primaryEmail": string
}

Voici un exemple d'événement de suppression d'utilisateur :

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 189
X-Goog-Channel-ID: deleteChannel
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Mon, 09 Dec 2013 22:24:23 GMT
X-Goog-Resource-ID:  B4ibMJiIhTjAQd7Ff2K2bexk8G4
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=mydomain.com&event=delete&alt=json
X-Goog-Resource-State:  delete
X-Goog-Message-Number: 236440

{
  "kind": "admin#directory#user",
  "id": "111220860655841818702",
  "etag": "\"Mf8RAmnABsVfQ47MMT_18MHAdRE/evLIDlz2Fd9zbAqwvIp7Pzq8UAw\"",
  "primaryEmail": "user@mydomain.com"
}

Répondre à des notifications

Pour indiquer la réussite, 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 Directory effectue de nouvelles tentatives avec intervalle exponentiel. Tout autre code d'état de retour est considéré comme un échec de message.

Arrêter les notifications

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

https://www.googleapis.com/admin/directory_v1/channels/stop

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

Seuls les utilisateurs disposant des autorisations appropriées peuvent arrêter un canal. En particulier :

Si la chaîne a été créée 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éé la chaîne peut l'arrêter.
Si le canal a été créé par un compte de service, tout utilisateur du même client peut l'arrêter.

L'exemple de code suivant montre comment arrêter de recevoir des notifications :

POST https://www.googleapis.com/admin/directory_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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

Notifications push Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Présentation

Créer des canaux de notification

Envoyer des requêtes à la montre

Exemples

Propriétés obligatoires

Propriétés facultatives

Regarder la réponse

Message de synchronisation

Renouveler les canaux de notification

Recevoir des notifications

Interpréter le format des messages de notification

En-têtes

Exemples

Répondre à des notifications

Arrêter les notifications

Notifications push