Notifications push

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

Présentation

L'API du SDK d'administration 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 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 Admin SDK en informe 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 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 qu'une ressource de chaîne change, l'API Admin SDK envoie un message de notification sous la forme d'une requête POST à cette URL.

Remarque:Le mot "canal" utilisé dans ce document fait spécifiquement référence à un canal de notification et non à d'autres types de canaux utilisés dans cette API ou ce service. Plusieurs canaux de notification peuvent être actifs en même temps pour la même ressource.

Actuellement, l'API du SDK Admin prend en charge les notifications de modifications apportées à la ressource Activities.

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 Admin SDK informe votre application lorsqu'une ressource surveillée change.

Envoyer des requêtes de visionnage

Chaque ressource d'API du SDK Admin pouvant être visionné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 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 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 de la ressource "Activités" se présentent sous la forme générale suivante:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/userKey or all/applications/applicationName/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-myFilesChannelDest", // (Optional) Your channel token.
  "payload": true, // (Optional) Whether to include the payload (message body) in notifications.
  "expiration": 3600 // (Optional) Your requested channel expiration time.
}

Vous pouvez utiliser les paramètres userKey, applicationName, eventName et filters pour ne recevoir que des notifications pour des événements, des utilisateurs ou des applications spécifiques.

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

Surveillez toutes les activités des administrateurs:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch

Surveillez toutes les activités liées aux documents:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch

Surveillez l'activité d'administration d'un utilisateur spécifique:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/[e-mail]/applications/admin/watch

Surveillez un événement spécifique, comme la modification du mot de passe d'un utilisateur:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD

Surveillez les modifications apportées à un document spécifique:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch?eventName=EDIT&filters==doc_id=123456abcdef

Propriétés obligatoires

Vous devez fournir les champs suivants avec chaque requête watch:

• 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 une 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.

• Une 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 du SDK Admin 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 falsifié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 cette chaîne.

  Si vous utilisez des jetons de canal de notification, nous vous recommandons ce qui suit:

  • 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 hautement 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 du SDK administrateur cesse d'envoyer des messages pour ce canal de notification.

  Si un canal a un délai d'expiration, celui-ci est inclus en tant que valeur de l'en-tête HTTP X-Goog-Channel-Expiration (au format intelligible) dans chaque message de notification que votre application reçoit pour ce canal.

Remarque:Pour l'API Admin SDK, la durée d'expiration maximale est de 21 600 secondes. Si vous ne définissez pas la propriété expiration dans votre requête, l'heure d'expiration est définie par défaut sur 21 600 secondes après l'heure actuelle.

Pour en savoir plus sur la requête, consultez la méthode watch de la ressource Activities 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": "reportsApiId", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 3600, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

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 regardée sur ce canal de notification.

Remarque:La propriété resourceId est un identifiant stable et indépendant de la version de la ressource. La propriété resourceUri correspond à l'URI canonique de la ressource surveillé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 arrêter de recevoir des notifications.

Pour plus de détails sur la réponse, reportez-vous à la méthode watch de la ressource Activities 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 SDK Admin envoie un message sync pour indiquer que les notifications sont lancées. La valeur de l'en-tête HTTP X-Goog-Resource-State pour ces messages est sync. En raison de problèmes de synchronisation réseau, il est possible que vous receviez 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 la notification sync pour effectuer une initialisation en vue de préparer les événements ultérieurs.

Le format des messages sync que l'API SDK Admin 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 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 Admin SDK (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, la date et l'heure d'expiration sont incluses (au format lisible par l'humain) 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'une chaîne approche de son expiration, vous devez la remplacer par une nouvelle 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 change, votre application reçoit un message de notification décrivant le changement. L'API Admin SDK 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.

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

Interpréter le format du message de la 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 du SDK Admin 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	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 ultérieur 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 entre les versions d'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.
Présent parfois
X-Goog-Channel-Expiration	Date et heure d'expiration du canal de notification, exprimées au 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éfini.

Les messages de notification pour les activités contiennent les informations suivantes dans le corps de la requête:

Propriété	Description
kind	Identifie cette ressource comme une ressource Activity. Valeur: chaîne fixe "admin#reports#activity".
id	Identifiant unique de l'enregistrement d'activité.
id.time	Heure de l'activité. La valeur est au format de date et d'heure ISO 8601. L'heure correspond à la date complète suivie des heures, des minutes et des secondes au format AAAA-MM-JJThh:mm:ssTZD. Par exemple, 2010-04-05T17:30:04+01:00.
id.uniqueQualifier	Qualificatif unique si plusieurs événements ont la même heure.
id.applicationName	Nom de l'application à laquelle l'événement appartient. Les valeurs possibles sont les suivantes : admin agenda drive groupes groups_enterprise login mobile saml jeton user_accounts
id.customerId	Identifiant unique d'un compte Google Workspace.
actor	Utilisateur effectuant l'action
actor.callerType	Type d'auteur ayant effectué l'activité indiquée dans le rapport. Dans cette version de l'API, callerType correspond à la requête USER ou à l'entité OAuth 2LO ayant effectué l'action listée dans le rapport .
actor.email	Adresse e-mail principale de l'utilisateur dont les activités sont signalées.
actor.profileId	ID de profil Google Workspace unique de l'utilisateur.
ownerDomain	Domaine de la console d'administration ou propriétaire du document de l'application Docs. Il s'agit du domaine concerné par l'événement du rapport.
ipAddress	Adresse IP de l'utilisateur effectuant l'action. Il s'agit de l'adresse IP de l'utilisateur lorsqu'il se connecte à Google Workspace. Elle peut ou non refléter l'emplacement physique de l'utilisateur. Par exemple, l'adresse IP peut correspondre à celle du serveur proxy de l'utilisateur ou à celle d'un réseau privé virtuel (VPN). L'API est compatible avec IPv4 et IPv6.
events[]	Événements d'activité dans le rapport.
events[].type	Type d'événement. Le service ou la fonctionnalité Google Workspace qu'un administrateur modifie est identifié dans la propriété type, qui identifie un événement à l'aide de la propriété eventName.
events[].name	Nom de l'événement. Il s'agit du nom spécifique de l'activité signalée par l'API. Chaque eventName est associé à un service ou à une fonctionnalité Google Workspace spécifique, que l'API organise en types d'événements. Pour les paramètres de requête eventName en général : Si aucun eventName n'est fourni, le rapport renvoie toutes les instances possibles d'un eventName. Lorsque vous demandez un eventName, la réponse de l'API renvoie toutes les activités qui contiennent ce eventName. Il est possible que les activités renvoyées aient d'autres propriétés eventName en plus de celle demandée.
events[].parameters[]	Paires de valeurs de paramètres pour diverses applications.
events[].parameters[].name	Nom du paramètre.
events[].parameters[].value	Valeur de la chaîne du paramètre.
events[].parameters[].intValue	Valeur entière du paramètre.
events[].parameters[].boolValue	Valeur booléenne du paramètre.

Exemples

Les messages de notification pour les événements de ressource Activité se présentent sous la forme suivante:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: reportsApiId
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/reports/v1/activity/userKey/applications/applicationName
X-Goog-Resource-State:  eventName
X-Goog-Message-Number: 10

{
  "kind": "admin#reports#activity",
  "id": {
    "time": datetime,
    "uniqueQualifier": long,
    "applicationName": string,
    "customerId": string
  },
  "actor": {
    "callerType": string,
    "email": string,
    "profileId": long
  },
  "ownerDomain": string,
  "ipAddress": string,
  "events": [
    {
      "type": string,
      "name": string,
      "parameters": [
        {
          "name": string,
          "value": string,
          "intValue": long,
          "boolValue": boolean
        }
      ]
    }
  ]
}

Exemple d'événement d'activité d'administrateur:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 596
X-Goog-Channel-ID: reportsApiId
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret987df98743md8g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json
X-Goog-Resource-State:  CREATE_USER
X-Goog-Message-Number: 23

{
  "kind": "admin#reports#activity",
  "id": {
    "time": "2013-09-10T18:23:35.808Z",
    "uniqueQualifier": "-0987654321",
    "applicationName": "admin",
    "customerId": "ABCD012345"
  },
  "actor": {
    "callerType": "USER",
    "email": "[e-mail]",
    "profileId": "0123456789987654321"
  },
  "ownerDomain": "apps-reporting.example.com",
  "ipAddress": "192.0.2.0",
  "events": [
    {
      "type": "USER_SETTINGS",
      "name": "CREATE_USER",
      "parameters": [
        {
          "name": "USER_EMAIL",
          "value": "[e-mail]"
        }
      ]
    }
  ]
}

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 du SDK Admin effectue une nouvelle tentative avec un temps d'attente exponentiel. Tout autre code d'état renvoyé est considéré comme un échec de message.

Comprendre les événements de notification de l'API Admin SDK

Cette section fournit des informations sur les messages de notification que vous pouvez recevoir lorsque vous utilisez des notifications push avec l'API Admin SDK.

Les notifications push de l'API Reports contiennent deux types de messages: les messages de synchronisation et les notifications d'événement. Le type de message est indiqué dans l'en-tête HTTP X-Goog-Resource-State. Les valeurs possibles pour les notifications d'événement sont les mêmes que pour la méthode activities.list. Chaque application possède des événements uniques:

• admin
• agenda
• drive
• groupes
• login
• mobile
• saml
• jeton
• user_accounts

Remarque:D'autres événements d'état des ressources peuvent être ajoutés au fil du temps. Vos gestionnaires de messages de notification doivent ignorer de manière appropriée les valeurs inattendues.

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

https://www.googleapis.com/admin/reports_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 SDK Admin comporte plusieurs types de ressources ayant des méthodes watch, il n'existe qu'une seule méthode 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, n'importe quel utilisateur du même client peut l'arrêter.

L'exemple de code suivant montre comment cesser de recevoir des notifications:

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

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

Exigences particulières

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

Les notifications ne sont pas fiables à 100 %. Attendez-vous à ce qu'un faible pourcentage de messages soit perdu dans des conditions de fonctionnement normales. Veillez à gérer ces messages manquants de manière appropriée afin que l'application se synchronise toujours, même si aucun message push n'est reçu.

Il est possible que les notifications ne soient pas envoyées dans l'ordre dans lequel les événements se produisent.