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

В этом документе описаны повторяющиеся списки аудитории, которые являются расширенной функцией API данных Google Analytics v1. Общие сведения о функции экспорта списка аудитории см. в руководстве по основам экспорта аудитории .

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

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

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

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

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

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

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

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

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

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

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

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

  • Допустимое имя аудитории в поле audience в формате properties/{propertyId}/audiences/{audienceId} . Чтобы получить это значение, вы можете использовать метод audiences.list Google Analytics Admin API v1. Поле 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 вы можете асинхронно получать уведомления Webhook, когда список аудитории становится доступным.

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

Следуйте инструкциям Async audience lists with webhooks для получения дополнительной информации об использовании веб-перехватчиков в API данных Google Analytics v1.

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

Чтобы получить пользователей в экспорте аудитории, вызовите метод 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
}