Notifications push

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

Présentation

L'API Directory 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 coûts 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 en informe votre application.

Pour utiliser les notifications push, vous devez:

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

    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 montre.

    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 à laquelle vous souhaitez recevoir des notifications. Chaque fois que la ressource d'un canal change, l'API Directory envoie un message de notification sous forme de POST à cette URL.

Actuellement, l'API Directory prend en charge les notifications de modifications apportées à la ressource Users (Utilisateurs).

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 Directory informe votre application lorsqu'une ressource surveillée des modifications.

Envoyer des demandes de visionnage

Chaque ressource de l'API Directory pouvant être regardé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 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 (ou un ensemble de ressources) spécifique. Une requête watch ne sera pas acceptée, sauf si l'utilisateur actuel ou le compte de service est propriétaire de cette ressource ou est autorisé à y accéder.

Exemples

Toutes les requêtes de surveillance pour 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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

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 requêtes de surveillance de la ressource "Utilisateur" d'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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

Utilisez les paramètres customer et event pour spécifier l'identifiant 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'un utilisateur
  • makeAdmin : événement de modification de l'état d'administrateur de l'utilisateur
  • undelete : événement de non suppression de l'utilisateur
  • update: événement mis à jour par l'utilisateur

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

Surveillez les événements créés par l'utilisateur 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

Avec 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 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. Elle 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 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 :

  • 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 la méthode pour vérifier que chaque message entrant est destiné à un canal application créée) pour s'assurer que la notification 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 paramètres de requête d'URL. Exemple : forwardTo=hr&createdBy=mobile

    • N'incluez pas de données sensibles telles que les jetons OAuth.

  • 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 une chaîne a une date d'expiration, elle est incluse en tant que valeur de l'en-tête HTTP X-Goog-Channel-Expiration (au format lisible par l'humain) dans chaque message de notification que votre application reçoit pour cette chaîne.

Pour en savoir plus sur la requête, reportez-vous à 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 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": "B4ibMJiIhTjAQd7Ff2K2bexk8G4", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1384823632000, // 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 à d'autres opérations de canal de notification, par exemple lorsque vous souhaitez arrêter de recevoir des notifications.

Pour en savoir plus sur la réponse, consultez le watch pour 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. 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 les valeurs X-Goog-Channel-ID et X-Goog-Resource-ID dans un appel pour arrêter de recevoir des 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 Directory 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

La valeur de l'en-tête HTTP X-Goog-Message-Number des messages de synchronisation est toujours 1. Chaque notification ultérieure pour ce canal a un numéro de message supérieur au précédent, bien que les numéros de message ne soient pas séquentiels.

Renouveler les canaux de notification

Un canal de notification peut avoir une date d'expiration, avec une valeur déterminée soit par votre requête, soit par les limites ou valeurs par défaut internes de l'API Directory (la valeur la plus restrictive est utilisée). La date d'expiration de la chaîne, 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. De plus, le la date et l'heure d'expiration sont incluses (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 qu'il y ait une période de "chevauchement" lorsque les deux canaux de notification de la 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 Directory envoie ces messages en tant que requêtes POST HTTPS à l'URL que vous avez spécifiée comme 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 des 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 Directory à votre 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 ce 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 ou un 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 au format dans un format lisible par l'humain. N'est présent que si 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. Présent uniquement si définis.

Les messages de notification destinés aux utilisateurs contiennent les informations suivantes dans le corps de la requête:

Propriété Description
kind Identifie l'élément en tant que ressource "User". Valeur: chaîne fixe "admin#directory#user".
id Identifiant unique de la ressource utilisateur.
etag ETag du message de notification. Diffère de l'ETag de la ressource utilisateur.
primaryEmail Adresse e-mail principale de l'utilisateur.

Exemples

Les messages de notification pour les événements de ressources User se présentent sous la forme générale:

POST https://mydomain.com/notifications // Your receiving URL.
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
}

Exemple d'événement supprimé par un utilisateur:

POST https://mydomain.com/notifications // Your receiving URL.
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 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 Directory effectue des nouvelles tentatives avec un intervalle exponentiel après une erreur. Tout autre code d'état renvoyé est considéré comme un échec de message.

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 de notifications pour un canal particulier avant son expiration en appelant la méthode stop à l'URI suivant :

https://www.googleapis.com/admin/directory_v1/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 Directory comporte plusieurs types de ressources comportant des méthodes watch, il n'y en a qu'une stop.

Seuls les utilisateurs disposant de l'autorisation appropriée 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, tout utilisateur du même le client peut arrêter la chaîne.

L'exemple de code suivant montre comment cesser 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"
}