Повторяющиеся списки аудиторий

В этом документе описываются повторяющиеся списки аудиторий – продвинутая функция Google Analytics Data API версии 1. Общие сведения о функции экспорта списков аудиторий можно найти в руководстве по основам экспорта аудиторий.

Повторяющиеся списки аудитории создаются ежедневно по мере изменения состава аудитории, чтобы вы работали с самыми актуальными данными.

Обычные (однократные) списки аудитории – это статические списки пользователей, которые входили в аудиторию на момент создания списка.

Создавать новый список аудитории ежедневно

Время, необходимое для обработки данных об аудитории за один день и обновления списка, может быть разным. Невозможно гарантировать, что данные в списке аудитории будут обновлены в течение 24 часов.

Например, даже если вы запрашиваете список аудитории в одно и то же время каждый день, в некоторые дни он будет таким же, как и в предыдущий день, а в другие дни он будет отличаться и содержать изменения за дополнительный день.

Создание нового списка аудитории ежедневно

Списки аудиторий основаны на данных о событиях за день до последних изменений в составе аудитории. Если вы создадите список аудитории до ежедневного обновления, в нем будут использоваться данные за два предыдущих дня. Если вы создадите список аудитории после ежедневного обновления, в нем будут использоваться данные за вчерашний день.

Периодически опрашивайте повторяющийся список аудитории

Повторяющиеся списки аудиторий создаются только тогда, когда доступны данные за дополнительный день. Это избавляет от необходимости гадать, когда создавать новые списки аудиторий. Вместо этого вы можете в течение дня отправлять запросы к повторяющемуся списку аудитории, чтобы узнать, доступны ли дополнительные данные.

Периодический опрос повторяющегося списка аудитории в течение дня

Как создать повторяющийся список аудитории

Чтобы создать повторяющийся список аудитории, вызовите метод recurringAudienceLists.create, используя в запросе объект RecurringAudienceList. Обязательные параметры:

  • Действительное название аудитории в поле audience в формате properties/{propertyId}/audiences/{audienceId}. Чтобы получить это значение, используйте метод audiences.list Google Analytics Admin API версии 1. Поле Audience.name в ответе audiences.list содержит название аудитории.
  • Допустимый список параметров в поле dimensions. Список параметров, поддерживаемых этим методом, можно найти в документации по схеме экспорта аудиторий. В список аудитории включаются только данные по параметрам, указанным в этом поле.

Ниже приведен пример запроса на создание повторяющегося списка аудитории.

HTTP-запрос.

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

Ответ метода recurringAudienceLists.create содержит название в поле name (например, properties/1234567/recurringAudienceLists/123), которое можно использовать в последующих запросах для получения метаданных конфигурации этого повторяющегося списка аудитории. Кроме того, метаданные конфигурации содержат названия ресурсов для экземпляров списка аудитории, созданных для этого повторяющегося списка аудитории.

Ответ HTTP

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

Метаданные конфигурации опроса

Используйте метод recurringAudienceLists.get, чтобы получить метаданные конфигурации для определенного повторяющегося списка аудитории. Метаданные конфигурации содержат названия ресурсов для экземпляров списка аудитории, созданных для этого повторяющегося списка аудитории.

Пример:

HTTP-запрос.

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists/123

В ответ возвращается экземпляр RecurringAudienceList. Он содержит метаданные конфигурации, в том числе названия ресурсов для экземпляров списка аудитории, созданных для этого повторяющегося списка аудитории.

Ответ HTTP

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

Чтобы получить список всех повторяющихся списков аудитории для ресурса, используйте метод recurringAudienceLists.list.

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

Вместо того чтобы периодически запрашивать метаданные конфигурации определенного повторяющегося списка аудитории с помощью метода recurringAudienceLists.get, вы можете асинхронно получать уведомления вебхука, когда список аудитории становится доступен.

Чтобы настроить уведомления вебхука, укажите поле webhookNotification при создании нового повторяющегося списка аудитории.

Дополнительную информацию об использовании вебхуков в Google Analytics Data API версии 1 можно найти в Async audience lists with webhooks.

Как получить пользователей из экспортированной аудитории

Чтобы получить пользователей из экспорта аудитории, вызовите метод audienceExports.query и укажите название экспорта аудитории, полученное из метаданных конфигурации, предоставленных recurringAudienceLists.get или recurringAudienceLists.list.

HTTP-запрос.

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

Если экспорт аудитории готов, возвращается ответ со списком пользователей в аудитории:

Ответ HTTP

{
  "audienceExport": {
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  },
  "audienceRows": [
    {
      "dimensionValues": [
        {
          "value": "1000276123.1681742376"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000374452.1668627377"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000391956.1652750758"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000410539.1682018694"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000703969.1666725875"
        }
      ]
    }
  ],
  "rowCount": 5
}