Ce guide explique comment utiliser des webhooks pour recevoir des notifications asynchrones sur l'état de vos demandes d'exportation d'audience. Cette fonctionnalité n'est disponible que dans la version v1alpha de l'API Data.
Les notifications Webhook constituent une fonctionnalité avancée de l'API Data de Google Analytics. Pour en savoir plus sur la fonctionnalité d'exportation d'audience, consultez la section Créer une exportation d'audience.
Sans webhooks, vous devez interroger régulièrement l'API pour déterminer le moment où une requête est terminée.
Créer un exemple d'application webhook à l'aide de Cloud Run
Vous pouvez créer un exemple d'application webhook à l'aide de Google Cloud en suivant 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 de webhook POST, remplacez le fichier index.js du tutoriel de démarrage rapide par le code suivant:
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 de webhook et une valeur de jeton de canal, puis renvoie le code HTTP 200 pour indiquer que l'opération a réussi.
Une fois que vous avez atteint la fin du tutoriel de démarrage rapide sur 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 dans lequel votre application écoute les notifications webhook de Google Analytics.
Créer une liste d'audience et activer les notifications Webhook
Pour demander des notifications Webhook, spécifiez les valeurs suivantes dans l'objet webhookNotification:
L'URI de notification du serveur contenant l'adresse Web qui recevra les notifications Webhook.
(Facultatif) Une chaîne arbitraire
channelTokenpour empêcher le spoofing du message. Spécifiez lechannelTokendans l'en-tête HTTPX-Goog-Channel-Tokende la requête POST du 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 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 d'envoi spécifie l'heure de l'epoch Unix en microsecondes à laquelle la requête a été envoyée. Vous pouvez utiliser ce code temporel pour identifier les notifications relancées.
Une ou deux requêtes POST sont envoyées au webhook lors de la création d'une liste d'audience:
- La première requête POST est envoyée immédiatement et la liste d'audience que vous venez de créer s'affiche à l'état
CREATING. Si la première requête envoyée au webhook échoue, l'opérationaudienceLists.createrenvoie une erreur et les détails de cet échec. - La deuxième requête POST est envoyée une fois la liste d'audience terminée. La création est terminée lorsque la liste d'audience atteint l'état
ACTIVEouFAILED.
Voici un exemple de première notification pour une liste d'audience, à l'état 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 pour une liste d'audience, à l'état 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 est prête à être interrogée à 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 consulter le corps JSON de chaque notification envoyée par Google Analytics.