En esta guía, se explica cómo usar webhooks para recibir notificaciones asíncronas sobre el estado de tus solicitudes de exportación de público. Esta función solo está disponible en la versión v1alpha de la API de datos.
Las notificaciones de webhook son una función avanzada de la API de datos de Google Analytics. Para obtener una introducción a la función de exportación de públicos, consulta Cómo crear una exportación de público.
Sin webhooks, tendrás que sondear periódicamente la API para determinar cuándo se completa una solicitud.
Crea una aplicación de webhook de muestra con Cloud Run
Puedes crear una aplicación de webhook de muestra con Google Cloud si sigues el instructivo Guía de inicio rápido: Implementa un servicio de muestra en Cloud Run.
Para que el servicio de muestra escuche las solicitudes de notificación de webhook POST, reemplaza el archivo index.js del instructivo de inicio rápido por el siguiente código:
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}`);
});
Para cada notificación de webhook entrante enviada como una solicitud POST, este código imprime el cuerpo JSON de la notificación de webhook y un valor del token de canal, y muestra el código HTTP 200 para indicar la operación exitosa.
Una vez que llegues al final del instructivo de inicio rápido de Cloud Run y hayas implementado la aplicación webhook con el comando gcloud run deploy, guarda la URL en la que se implementa tu servicio.
La URL del servicio se muestra en la consola, por ejemplo:
Service URL: https://webhooks-test-abcdef-uc.a.run.app
Este es el URI de notificación del servidor en el que tu aplicación escucha las notificaciones de webhook desde Google Analytics.
Cómo crear una lista de público y activar las notificaciones de webhook
Para solicitar notificaciones de webhook, especifica los siguientes valores en el objeto webhookNotification:
El URI de notificación del servidor que contiene la dirección web que recibirá las notificaciones de webhook.
(Opcional) Una cadena arbitraria
channelTokenpara proteger contra el mensaje que se falsifica en la identidad. Especifica elchannelTokenen el encabezado HTTPX-Goog-Channel-Tokende la solicitud POST de webhook.
Esta es una solicitud de ejemplo que usa webhooks:
Solicitud 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 respuesta del método audienceLists.create contiene webhookNotification, que confirma que el webhook especificado respondió de forma correcta en menos de 5 segundos.
Esta es una respuesta de ejemplo:
Respuesta 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 no responde o si proporcionas una URL de servicio incorrecta, se mostrará un mensaje de error.
Este es un ejemplo de error que podrías recibir:
{
"error": {
"code": 400,
"message": "Expected response code of 200 from webhook URI but instead
'404' was received.",
"status": "INVALID_ARGUMENT"
}
}
Procesa notificaciones de webhook
La solicitud POST a un servicio de webhook contiene una versión JSON del recurso de operación de larga duración en el cuerpo y un campo sentTimestamp. La marca de tiempo enviada especifica el tiempo Unix epoch en microsegundos en el que se envió la solicitud. Puedes usar esta marca de tiempo para identificar las notificaciones que se vuelven a reproducir.
Se envían una o dos solicitudes POST al webhook durante la creación de una lista de público:
- La primera solicitud POST se envía de inmediato y muestra la lista de público recién creada en su estado
CREATING. Si la primera solicitud al webhook falla, la operaciónaudienceLists.createmuestra un error y los detalles de la falla del webhook. - La segunda solicitud POST se envía después de que la lista de público completa la creación. La creación se completa cuando la lista de público alcanza el estado
ACTIVEoFAILED.
El siguiente es un ejemplo de la primera notificación para una lista de público, en el estado 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"
}
}
A continuación, se muestra un ejemplo de la segunda notificación para una lista de público, en el estado 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"
}
}
Con la segunda notificación, se confirma que se creó la lista de público y que está lista para consultarse con el método audienceLists.query.
Para probar webhooks después de llamar al método audienceLists.create, puedes inspeccionar los registros de la aplicación de webhook de Cloud Run de muestra y ver el cuerpo JSON de cada notificación que envía Google Analytics.