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

Recevoir des notifications Webhook pour vos listes d'audience

Ce guide explique comment utiliser des webhooks pour recevoir des notifications asynchrones pour connaître l'état de vos demandes d'exportation d'audiences. Cette fonctionnalité n'est disponible dans la version v1alpha de l'API Data.

Notifications webhook Il s'agit d'une fonctionnalité avancée de Google Analytics API. Pour vous familiariser avec la fonctionnalité d'exportation d'audience, consultez la section Créer une exportation d'audience.

Sans webhooks, vous devrez régulièrement interroger l'API pour déterminer quand une requête est traitée.

Créer un exemple d'application webhook à l'aide de Cloud Run

Pour créer un exemple d'application webhook à l'aide de Google Cloud, procédez comme suit : le tutoriel Démarrage rapide: déployer un exemple de service sur Cloud Run.

Pour que l'exemple de service écoute les requêtes de notification POST de webhook, Remplacez le fichier index.js du tutoriel de démarrage rapide par le code suivant : code:

  import express from 'express';

  const app = express();
  app.use(express.json());

  app.post('/', (req, res) => {
    const channelToken = req.get('X-Goog-Channel-Token');
    const bodyJson = JSON.stringify(req.body);

    console.log(`channel token: ${channelToken}`);
    console.log(`notification body: ${bodyJson}`);

    res.sendStatus(200);
  });

  const port = parseInt(process.env.PORT) || 8080;
  app.listen(port, () => {
    console.log(`helloworld: listening on port ${port}`);
  });

Pour chaque notification webhook entrante envoyée en tant que requête POST, ce code imprime le corps JSON de la notification webhook et une valeur de jeton de canal ; La fonction renvoie le code HTTP 200 pour indiquer que l'opération a réussi.

Une fois que vous avez terminé le tutoriel de démarrage rapide de Cloud Run et déployé l'application webhook à l'aide de la commande gcloud run deploy, enregistrez l'URL où votre service est déployé.

L'URL du service s'affiche dans la console, par exemple:

  Service URL: https://webhooks-test-abcdef-uc.a.run.app

Il s'agit de l'URI de notification du serveur. où votre application écoute les notifications webhook Google Analytics.

Créer une liste d'audience et activer les notifications Webhook

Pour demander des notifications Webhook, spécifiez les valeurs suivantes dans le webhookNotification objet:

L'URI de notification du serveur contenant l'adresse Web qui recevra les notifications webhook.
(Facultatif) Une chaîne arbitraire channelToken pour éviter le spoofing du message. Spécifiez le channelToken. dans l'en-tête HTTP X-Goog-Channel-Token du requête POST webhook.

Voici un exemple de requête utilisant des webhooks:

Requête HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/audienceLists
{
  "webhookNotification": {
    "uri": "https://webhooks-test-abcdef-uc.a.run.app",
    "channelToken": "123456"
  },
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

La réponse de la méthode audienceLists.create contient webhookNotification, qui confirme que le webhook spécifié a bien été a répondu en moins de cinq secondes.

Voici un exemple de réponse :

Réponse HTTP

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceList",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged": 51,
    "rowCount": 13956,
    "percentageCompleted": 100,
    "webhookNotification": {
      "uri": "https://webhooks-test-abcdef-uc.a.run.app",
      "channelToken": "123456"
    }
  }
}

Si un webhook ne répond pas ou si vous fournissez une URL de service incorrecte, un message d'erreur s'affiche à la place.

Voici un exemple d'erreur que vous pourriez recevoir:

{
  "error": {
    "code": 400,
    "message": "Expected response code of 200 from webhook URI but instead
    '404' was received.",
    "status": "INVALID_ARGUMENT"
  }
}

Traiter les notifications Webhook

La requête POST adressée à un service de webhook contient à la fois une version JSON de la Ressource d'opération de longue durée dans le corps, et un champ sentTimestamp. Le code temporel envoyé spécifie l'epoch Unix en microsecondes à laquelle la requête a été envoyée. Vous pouvez utiliser cette pour identifier les notifications relancées.

Une ou deux requêtes POST sont envoyées au webhook lors d'une Création de listes d'audience:

La première requête POST est envoyée immédiatement, indiquant liste d'audience à l'état CREATING. Si la première requête envoyée au le webhook échoue, l'opération audienceLists.create renvoie une erreur et les détails de l'échec du webhook.
La deuxième demande POST est envoyée une fois la liste d'audience terminée. création. La création est terminée lorsque la liste d'audience atteint l'un des l'état ACTIVE ou FAILED.

Voici un exemple de la première notification associée à une liste d'audience, dans la section CREATING:

  {
    "sentTimestamp":"1718261355692983",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName":"Purchasers",
    "dimensions":[{"dimensionName":"deviceId"}],
    "state":"CREATING",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged":0,
    "rowCount":0,
    "percentageCompleted":0,
    "webhookNotification":
      {
        "uri": "https://webhooks-test-abcdef-uc.a.run.app",
        "channelToken":"123456"
      }
  }

Voici un exemple de deuxième notification concernant une liste d'audience, dans la section ACTIVE:

  {
    "sentTimestamp":"1718261355692983",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName":"Purchasers",
    "dimensions":[{"dimensionName":"deviceId"}],
    "state":"ACTIVE",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged":68,
    "rowCount":13956,
    "percentageCompleted":100,
    "webhookNotification":
      {
        "uri": "https://webhooks-test-abcdef-uc.a.run.app",
        "channelToken":"123456"
      }
  }

La deuxième notification confirme que la liste d'audience a été créée et qu'elle prêts à être interrogés à l'aide de la méthode audienceLists.query .

Pour tester les webhooks après avoir appelé la méthode audienceLists.create, vous pouvez inspecter les journaux de votre exemple d'application webhook Cloud Run et consultez le corps JSON de chaque envoyée par Google Analytics.