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

В этом документе описаны повторяющиеся списки аудиторий. Это расширенная функция 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, вы можете асинхронно получать уведомления Webhook, когда список аудиторий становится доступен.

Чтобы настроить уведомления Webhook, укажите поле 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
}