Reciba notificaciones de webhook para sus listas de público

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úblicos. Esta función solo está disponible en la versión v1alpha de la API de datos

Notificaciones de webhook son una función avanzada de la capa de Datos de Google Analytics de la API. Para obtener una introducción al función de exportación de públicos, consulta cómo crear una exportación de públicos.

Sin webhooks, deberás 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 usando Google Cloud de la siguiente manera: 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 lo 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}`);
  });

Por cada notificación de webhook entrante enviada como una solicitud POST, este código se imprime el cuerpo JSON de la notificación de webhook y el valor del token de canal, y muestra el código HTTP 200 para indicar que la operación se realizó correctamente.

Cuando termines el 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 la que tu aplicación escucha las notificaciones de webhook 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 webhookNotification objeto:

  • El URI de notificación del servidor que contenga la dirección web que recibirá las notificaciones de webhook.

  • Una cadena arbitraria channelToken (opcional) para protegerse contra el mensaje que se falsificó. Especifica el channelToken. en el encabezado HTTP X-Goog-Channel-Token del 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 lo siguiente: webhookNotification, que confirma que el webhook especificado se realizó correctamente respondió 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, en su lugar, se muestra 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 webhook contiene una versión JSON del recurso de operación de larga duración en el cuerpo y en el campo sentTimestamp. La marca de tiempo enviada especifica el tiempo Unix en microsegundos en el que se envió la solicitud Puedes usar esta y marca de tiempo para identificar las notificaciones que se vuelven a reproducir.

Una o dos solicitudes POST se envían al webhook durante un Creación de listas de público:

  1. La primera solicitud POST se envía de inmediato y muestra la versión recién creada lista de público en su estado CREATING. Si la primera solicitud a la webhook falla, la operación audienceLists.create muestra un error y los detalles de fallas del webhook.
  2. La segunda solicitud POST se envía después de que se completa la lista de público. de la creación de cuentas de servicio. La creación se completa cuando la lista de público llega el estado ACTIVE o FAILED

A continuación, se incluye un ejemplo de la primera notificación para una lista de público, en la 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"
      }
  }

Este es un ejemplo de la segunda notificación para una lista de público, en el 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 segunda notificación confirma que se creó la lista de público y que está listo para ser consultado con audienceLists.query .

Para probar webhooks después de llamar al método audienceLists.create, puedes hacer lo siguiente: inspeccionar los registros de tu aplicación webhook de Cloud Run de muestra y ver el cuerpo JSON de cada de Google Analytics que envía Google Analytics.