Эта страница переведена с помощью Cloud Translation API.

Получайте уведомления веб-перехватчиков для списков аудитории.

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

Веб-хуки — это расширенная функция API данных Google Analytics. Введение в функцию экспорта аудитории см. в разделе «Создание экспорта аудитории» .

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

Создайте пример приложения для веб-перехватчиков с помощью Cloud Run.

Вы можете создать пример приложения для веб-перехватчиков с использованием Google Cloud, следуя руководству «Быстрый старт: развертывание примера сервиса в Cloud Run» .

Для того чтобы тестовый сервис мог принимать POST-запросы на уведомления через веб-перехватчик, замените файл 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 и развертывания приложения веб-перехватчика с помощью команды gcloud run deploy , сохраните URL-адрес, по которому развернута ваша служба.

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

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

Это URI серверных уведомлений , по которому ваше приложение будет прослушивать уведомления веб-перехватчика от Google Analytics.

Создайте список целевой аудитории и включите уведомления через веб-перехватчики.

Для запроса уведомлений через веб-перехватчик укажите следующие значения в объекте webhookNotification :

URI уведомления сервера, содержащий веб-адрес, на который будут приходить уведомления через веб-перехватчик.
(Необязательно) Произвольная строка 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 , подтверждающее, что указанный веб-хук успешно ответил менее чем за 5 секунд.

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

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

Обработка уведомлений веб-перехватчика

POST-запрос к службе веб-перехватчиков содержит в теле JSON-версию ресурса длительной операции и поле sentTimestamp . Отправленная метка времени указывает время в формате Unix epoch в микросекундах, когда был отправлен запрос. Эту метку времени можно использовать для идентификации повторно отслеженных уведомлений.

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

Первый POST-запрос отправляется немедленно, отображая вновь созданный список аудитории в состоянии CREATING . Если первый запрос к веб-хуку завершается неудачей, операция audienceLists.create возвращает ошибку и подробную информацию о сбое веб-хука.
Второй 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 Analytics.