Как получать уведомления о списках аудиторий с помощью веб-перехватчиков

В этом руководстве рассказывается, как использовать веб-перехватчики для получения асинхронных уведомлений о статусе запросов на экспорт аудиторий. Эта функция доступна только в альфа-версии 1 API данных.

Уведомления webhook – это продвинутая функция API данных Google Аналитики. Чтобы узнать больше об экспорте аудиторий, прочитайте статью Как создать экспорт аудитории.

Без веб-хуков вам придется периодически опрашивать API, чтобы узнать, когда запрос будет выполнен.

Как создать образец приложения webhook с помощью Cloud Run

Вы можете создать образец приложения webhook с помощью Google Cloud, следуя инструкциям из руководства Краткое руководство: развертывание образца сервиса в Cloud Run.

Чтобы образец сервиса мог получать запросы уведомлений POST webhook, замените файл index.js из руководства по быстрому началу работы следующим кодом:

  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}`);
  });

Для каждого входящего уведомления вебхука, отправленного в виде запроса POST, этот код выводит тело JSON уведомления вебхука и значение токена канала, а также возвращает код HTTP 200, чтобы указать на успешное выполнение операции.

После того как вы завершите краткое руководство по Cloud Run и развернете приложение webhook с помощью команды gcloud run deploy, сохраните URL, по которому развернут ваш сервис.

URL сервиса отображается в консоли, например:

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

Это URI уведомления сервера, на котором ваше приложение принимает уведомления webhook от Google Аналитики.

Как создать список аудитории и включить уведомления webhook

Чтобы запросить уведомления webhook, укажите следующие значения в объекте webhookNotification:

  • URI уведомления сервера, содержащий веб-адрес, на который будут отправляться уведомления webhook.

  • (Необязательно.) Произвольная строка channelToken для защиты от подделки сообщений. Укажите channelToken в HTTP-заголовке X-Goog-Channel-Token запроса POST для веб-перехватчика.

Пример запроса с использованием вебхуков:

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"
    }
  ]
}

Ответ метода audienceLists.create содержит объект webhookNotification, который подтверждает, что указанный веб-хук успешно ответил менее чем за пять секунд.

Вот пример ответа:

Ответ 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"
    }
  }
}

Если вебхук не отвечает или вы указали неверный URL сервиса, вместо ответа возвращается сообщение об ошибке.

Вот пример ошибки, которую вы можете получить:

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

Как обрабатывать уведомления webhook

Запрос POST к сервису вебхука содержит как версию JSON ресурса долго выполняемой операции в теле, так и поле sentTimestamp. Временная метка отправки указывает время отправки запроса в микросекундах с начала эпохи Unix. По этой временной метке можно определить, что уведомление было воспроизведено повторно.

Во время создания списка аудиторий в вебхук отправляется один или два запроса POST:

  1. Первый запрос POST отправляется сразу, и в нем показывается только что созданный список аудиторий в состоянии CREATING. Если первый запрос к веб-перехватчику не удастся выполнить, операция audienceLists.create вернет ошибку и сведения о сбое веб-перехватчика.
  2. Второй запрос POST отправляется после того, как список аудиторий будет создан. Создание завершается, когда список аудитории достигает статуса ACTIVE или FAILED.

Вот пример первого уведомления для списка аудиторий в состоянии 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"
      }
  }

Ниже приведен пример второго уведомления для списка аудиторий в состоянии 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"
      }
  }

Второе уведомление подтверждает, что список аудитории создан и готов к запросам с помощью метода audienceLists.query.

Чтобы протестировать веб-перехватчики после вызова метода audienceLists.create, вы можете проверить журналы образца приложения веб-перехватчика Cloud Run и посмотреть тело JSON каждого уведомления, отправленного Google Аналитикой.