Notifications push

Propriétés obligatoires

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

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

• Une 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 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 :

• 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 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, comme des 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 du SDK administrateur 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'homme) dans chaque message de notification que votre application reçoit pour cette chaîne.

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 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 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 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 du SDK Admin envoie un message sync pour indiquer que les notifications commencent. La valeur de l'en-tête HTTP X-Goog-Resource-State pour 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 la notification sync pour effectuer une initialisation en vue de préparer 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 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 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.

Actuellement, il n'existe 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.

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.

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 une 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 SDK Admin

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énements sont les mêmes que pour la méthode activities.list. Chaque application possède des événements uniques :

• admin
• agenda
• en voiture
• groupes
• login
• mobile
• saml
• jeton
• user_accounts