Notifications push

Ce document explique comment utiliser les notifications push qui informent vos en cas de modification d'une ressource.

Présentation

L'API SDK Admin 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 SDK Admin en informe 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 SDK Admin envoie un message de notification sous forme de POST à cette URL.

Remarque:Le mot "chaîne" telles qu'utilisées dans ce document fait spécifiquement référence à un canal de notification et non à tout autre type canaux utilisés dans cette API ou ce service.

Actuellement, l'API SDK Admin prend en charge les notifications concernant les modifications 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 définis l'API SDK Admin informe votre application lorsqu'une ressource surveillée des modifications.

Envoyer des demandes de visionnage

Chaque ressource de l'API SDK Admin pouvant être visionné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 ou 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 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 des notifications que pour des événements, des utilisateurs ou des applications spécifiques.

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

Surveillez toutes les activités d'administration:

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

Surveillez toutes les activités liées à Google Docs:

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, tel que le changement de 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

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 SDK Admin 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 vous souhaitez que l'API SDK Admin 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.

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

Pour en savoir plus 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 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": "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 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 la ressource Activities 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 SDK Admin 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 SDK Admin 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 SDK Admin 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 SDK Admin 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

Messages de notification publiés par l'API SDK Admin à 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 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. 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 pour les activités contiennent les informations suivantes dans le corps de la requête:

Propriété	Description
kind	Identifie l'activité en tant que ressource d'activité. Valeur: chaîne fixe "admin#reports#activity".
id	Identifiant unique de l'enregistrement d'activité.
id.time	Heure à laquelle l'activité s'est produite. La valeur est en 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: <ph type="x-smartling-placeholder"> </ph> admin agenda en voiture 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. La position géographique de l'utilisateur n'est pas forcément indiquée. Par exemple, l'adresse IP peut être l'adresse 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 modifiés par un administrateur sont identifiés 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: <ph type="x-smartling-placeholder"> </ph> Si aucun eventName n'est indiqué, le rapport renvoie toutes les instances possibles d'une 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 valeur/paramètre 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 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 pour une 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": "[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 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 SDK Admin 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 SDK Admin

Cette section fournit des informations sur les messages de notification que vous pouvez recevoir lors de l'utilisation de 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:

• admin
• agenda
• en voiture
• 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 normalement toute valeur inattendue.

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/admin/reports_v1/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 SDK Admin 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/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 les notifications push, tenez compte des points suivants:

Les notifications ne sont pas fiables à 100 %. Attendez-vous à ce qu'un faible pourcentage de messages soit placé sous dans des conditions de travail normales. Veillez à traiter les messages manquants comme il se doit, afin que le 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.