Notifications push

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.

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

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.

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.

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.

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

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
        }
      ]
    }
  ]
}

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