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

Notifications push

Ce document explique comment utiliser des notifications push pour informer votre application lorsqu'une ressource est modifiée.

Présentation

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

Pour utiliser les notifications push, vous devez:

Configurez votre URL de réception ou le 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 est modifiée.
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 que la ressource d'un canal change, l'API SDK Admin envoie un message de notification sous la forme de requête POST à cette URL.

Actuellement, l'API SDK Admin prend en charge les notifications concernant les 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 à surveiller. Une fois vos canaux de notification configurés, l'API SDK Admin informe votre application lorsqu'une ressource surveillée change.

Envoyer des demandes de montre

Chaque ressource de l'API SDK Admin pouvant être visionnée est associée à une méthode 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 apportées à une ressource particulière, 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 n'aboutira que si l'utilisateur ou le compte de service actuel possède cette ressource ou est autorisée à y accéder.

Exemples

Toutes les requêtes de surveillance pour la ressource Activity ont la forme générale:

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 des notifications que pour des événements, utilisateurs ou applications spécifiques.

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

Soyez attentif aux activités d'administration:

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

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

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

Surveillez les activités d'administration d'un utilisateur spécifique:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/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

Surveiller 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

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

Une chaîne de propriété id qui identifie de manière unique ce nouveau canal de notification au sein de votre projet. Nous vous recommandons d'utiliser un identifiant unique universel (UUID) ou toute chaîne unique similaire. Ne doit pas dépasser 64 caractères.

La valeur d'ID que vous avez définie 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.
Une chaîne de propriété address définie sur l'URL qui écoute les notifications de ce canal de notification et y répond. Il s'agit de l'URL de rappel de votre webhook, qui doit utiliser le protocole HTTPS.

Notez que l'API SDK Admin ne peut envoyer des 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 les champs facultatifs suivants dans votre requête watch:

Une 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 à diverses 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 reçu par votre application pour ce canal.

Si vous utilisez des jetons de canal de notification, nous vous recommandons de procéder comme 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 telles que 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.
Une chaîne de propriété expiration définie sur un horodatage Unix (en millisecondes) de la date et de l'heure auxquelles vous souhaitez que l'API SDK Admin cesse d'envoyer des messages pour ce canal de notification.

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

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

Pour plus d'informations sur la requête, reportez-vous à la méthode watch pour 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 le cadre de 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 de la ressource. La propriété resourceUri est 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 du canal de notification, par exemple lorsque vous souhaitez ne plus recevoir de notifications.

Pour en savoir plus sur la réponse, reportez-vous à la méthode watch pour 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 en cours de démarrage. 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, mais vous pouvez également l'utiliser. Par exemple, si vous ne souhaitez pas conserver le canal, vous pouvez utiliser les valeurs X-Goog-Channel-ID et X-Goog-Resource-ID dans un appel pour ne plus recevoir de 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 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 d'en-tête HTTP X-Goog-Message-Number des messages de synchronisation est toujours 1. Chaque notification ultérieure pour ce canal comporte un numéro de message supérieur à la précédente, bien que les numéros des messages ne soient pas séquentiels.

Renouveler les canaux de notification

Un canal de notification peut avoir un délai d'expiration, avec une valeur déterminée par votre requête, ou par les limites internes ou les valeurs par défaut de l'API du SDK Admin (la valeur la plus restrictive est utilisée). Le délai d'expiration du canal, le cas échéant, est inclus en tant qu'horodatage Unix (en millisecondes) dans les informations renvoyées par la méthode watch. De plus, la date et l'heure d'expiration sont incluses (dans un format lisible) dans chaque message de notification que votre application reçoit pour ce canal dans l'en-tête HTTP X-Goog-Channel-Expiration.

Actuellement, il n'existe pas de 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 peut y avoir un "chevauchement" de temps pendant lequel les deux canaux de notification de la même ressource sont actifs.

Recevoir les notifications

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

Remarque:Les requêtes HTTPS d'envoi de notifications spécifient un user-agent APIs-Google et respectent les instructions du fichier robots.txt, comme décrit dans la section User-agent Google pour les API.

Interpréter le format du message de notification

Tous les messages de notification incluent un ensemble d'en-têtes HTTP avec les 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 SDK Admin à 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 identifiant ce message pour ce canal de notification. La valeur est toujours `1` pour les messages `sync`. Le nombre de messages augmente 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 entre les versions de l'API.
`X-Goog-Resource-State`	Nouvel état de la ressource ayant 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. Présent uniquement s'il est défini.
`X-Goog-Channel-Token`	Jeton du canal de notification défini par votre application, que vous pouvez utiliser pour vérifier la source de la notification. Présent uniquement s'il est 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 cela en tant que ressource Activity. Valeur: chaîne fixe "`admin#reports#activity`".
`id`	Identifiant unique de l'enregistrement d'activité.
`id.time`	Heure d'occurrence 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, minutes et 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 appartient l'événement. Les valeurs possibles sont les suivantes : admin agenda conduire 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 réalisé l'activité indiquée dans le rapport. Dans cette version de l'API, `callerType` correspond à la requête d'entité `USER` ou OAuth 2LO ayant effectué l'action répertorié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 du propriétaire des documents 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 (Internet Protocol) de l'utilisateur lorsqu'il se connecte à Google Workspace. Elle peut refléter ou non sa position géographique. Il peut s'agir, par exemple, de celle du serveur proxy de l'utilisateur ou de 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 modifié par un administrateur 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. De plus, chaque `eventName` est associé à une fonctionnalité ou un service 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 indiqué, le rapport affiche 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 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 des événements de ressources "Activité" 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: 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'administration:

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": "admin@example.com",
    "profileId": "0123456789987654321"
  },
  "ownerDomain": "apps-reporting.example.com",
  "ipAddress": "192.0.2.0",
  "events": [
    {
      "type": "USER_SETTINGS",
      "name": "CREATE_USER",
      "parameters": [
        {
          "name": "USER_EMAIL",
          "value": "liz@example.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 SDK Admin effectue une nouvelle tentative 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 SDK Admin

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

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

Arrêter les notifications

La propriété expiration détermine 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. Pour ce faire, appelez 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 indiqué 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 des autorisations appropriées peuvent arrêter une chaîne. Plus spécifiquement :

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 client peut l'arrêter.

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