GetEventsLog (Live)

Возвращает записи из журнала событий.

Яндекс Директ автоматически регистрирует события, связанные с общими счетами, кампаниями и объявлениями, например результаты модерации, пополнение баланса и другое. Журнал событий ведется для каждого пользователя. Метод GetEventsLog возвращает записи из журнала событий за указанный период времени.

Новое в версии Live 4

Входной параметр Currency стал обязательным.

Добавлен входной параметр Currency и результирующий параметр Currency.

Добавлен входной параметр AccountIDS и результирующий параметр AccountID.

Добавлены входные параметры Limit и Offset.

Входные данные

Ниже показана структура входных данных в формате JSON.

{
   "method": "GetEventsLog",
   "param": {
      /* GetEventsLogRequest */
      "TimestampFrom": (string),
      "TimestampTo": (string),
      "LastEventOnly": (string),
      "WithTextDescription": (string),
      "Currency": (string),
      "Logins": [
         (string)
         ...
      ],
      "Filter": {
         /* GetEventsLogFilter */
         "CampaignIDS": [
            (int)
            ...
         ],
         "BannerIDS": [
            (long)
            ...
         ],
         "PhraseIDS": [
            (long)
            ...
         ],
         "AccountIDS": [
            (int)
            ...
         ],
         "EventType": [
            (string)
            ...
         ]
      },
      "Limit": (int),
      "Offset": (int)
   }
}

Ниже приведено описание параметров.

Параметр Описание Требуется
Объект GetEventsLogRequest
TimestampFrom

Момент времени, начиная с которого требуется получить записи о событиях. Указывается в формате ISO 8601, например 2011-05-24T23:59:59Z.

 Да
TimestampTo

Момент времени, по который требуется получить записи о событиях. Указывается в формате ISO 8601, например 2011-05-25T23:59:59Z.

Если параметр не задан, возвращаются записи по текущий момент времени.

 Нет
LastEventOnly

Получить только последнюю запись по каждому типу событий — Yes/No.

Если параметр не задан, возвращаются все записи за указанный период времени.

 Нет
WithTextDescription

Выводить в ответ описания событий — Yes/No.

Если параметр не задан, описания не выводятся.

 Нет
Currency

Валюта, в которой должны быть выражены денежные значения (минимальная цена, остаток средств, сумма зачисленных средств) в ответе.

Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN.

 Да
Logins

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

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

 Только для рекламных агентств
Filter Объект GetEventsLogFilter с условиями фильтрации записей о событиях. Если не задан, фильтрация не применяется, и возвращаются все записи за указанный период времени. Нет
Limit

Количество возвращаемых событий (размер страницы). Вместе с параметром Offset позволяет организовать постраничную выборку. Список событий упорядочен по времени.

Если не задан, возвращаются все события.

 Нет
Offset Количество событий, которое должно быть пропущено при выборке. Игнорируется, если не задан Limit. Нет
Объект GetEventsLogFilter
CampaignIDS Идентификаторы кампаний, для которых требуется получить записи о событиях. Нет
BannerIDS Идентификаторы объявлений, для которых требуется получить записи о событиях. Нет
PhraseIDS Идентификаторы фраз, для которых требуется получить записи о событиях. Нет
AccountIDS Идентификаторы общих счетов, для которых требуется получить записи о событиях. Нет
EventType

Типы событий, записи о которых требуется получить. Возможные значения указаны ниже:

  • BannerModerated — объявление проверено модератором;
  • CampaignFinished — кампания остановлена в связи с наступлением даты окончания показов;
  • LowCTR — фраза отключена за низкий CTR;
  • MoneyOut — закончились средства на кампании или на общем счете;
  • MoneyWarning — баланс кампании или общего счета уменьшился до уровня, при котором отправляются уведомления (параметр MoneyWarningValue);
  • MoneyIn — пополнен баланс кампании или общий счет;
  • PausedByDayBudget — кампания остановлена, поскольку исчерпан дневной лимит бюджета;
  • WarnMinPrice — изменилась минимальная цена за клик;
  • WarnPlace — изменилась позиция показа объявления.
 Нет
Параметр Описание Требуется
Объект GetEventsLogRequest
TimestampFrom

Момент времени, начиная с которого требуется получить записи о событиях. Указывается в формате ISO 8601, например 2011-05-24T23:59:59Z.

 Да
TimestampTo

Момент времени, по который требуется получить записи о событиях. Указывается в формате ISO 8601, например 2011-05-25T23:59:59Z.

Если параметр не задан, возвращаются записи по текущий момент времени.

 Нет
LastEventOnly

Получить только последнюю запись по каждому типу событий — Yes/No.

Если параметр не задан, возвращаются все записи за указанный период времени.

 Нет
WithTextDescription

Выводить в ответ описания событий — Yes/No.

Если параметр не задан, описания не выводятся.

 Нет
Currency

Валюта, в которой должны быть выражены денежные значения (минимальная цена, остаток средств, сумма зачисленных средств) в ответе.

Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN.

 Да
Logins

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

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

 Только для рекламных агентств
Filter Объект GetEventsLogFilter с условиями фильтрации записей о событиях. Если не задан, фильтрация не применяется, и возвращаются все записи за указанный период времени. Нет
Limit

Количество возвращаемых событий (размер страницы). Вместе с параметром Offset позволяет организовать постраничную выборку. Список событий упорядочен по времени.

Если не задан, возвращаются все события.

 Нет
Offset Количество событий, которое должно быть пропущено при выборке. Игнорируется, если не задан Limit. Нет
Объект GetEventsLogFilter
CampaignIDS Идентификаторы кампаний, для которых требуется получить записи о событиях. Нет
BannerIDS Идентификаторы объявлений, для которых требуется получить записи о событиях. Нет
PhraseIDS Идентификаторы фраз, для которых требуется получить записи о событиях. Нет
AccountIDS Идентификаторы общих счетов, для которых требуется получить записи о событиях. Нет
EventType

Типы событий, записи о которых требуется получить. Возможные значения указаны ниже:

  • BannerModerated — объявление проверено модератором;
  • CampaignFinished — кампания остановлена в связи с наступлением даты окончания показов;
  • LowCTR — фраза отключена за низкий CTR;
  • MoneyOut — закончились средства на кампании или на общем счете;
  • MoneyWarning — баланс кампании или общего счета уменьшился до уровня, при котором отправляются уведомления (параметр MoneyWarningValue);
  • MoneyIn — пополнен баланс кампании или общий счет;
  • PausedByDayBudget — кампания остановлена, поскольку исчерпан дневной лимит бюджета;
  • WarnMinPrice — изменилась минимальная цена за клик;
  • WarnPlace — изменилась позиция показа объявления.
 Нет

Результирующие данные

Метод возвращает массив объектов EventsLogItem, каждый из которых представляет одну запись о событии. Ниже показана структура результирующих данных в формате JSON.

{
   "data": [
      {  /* EventsLogItem */
         "AccountID": (int),
         "CampaignID": (int),
         "BannerID": (long),
         "PhraseID": (long),
         "TextDescription": (string),
         "EventType": (string),
         "Timestamp": (string),
         "EventName": (string),
         "Attributes": {
            /* EventsLogItemAttributes */
            "ModerationResult": (string),
            "MinPrice": (float),
            "Rest": (float),
            "Payed": (float),
            "FinishDate": (date),
            "OldPlace": (string),
            "IsEditedByModerator": (string),
            "StopTime": (string),
            "Currency": (string)
         }
      }
      ...
   ]
}

Ниже приведено описание параметров.

Параметр Описание
Объект EventsLogItem
AccountID Идентификатор общего счета, к которому относится событие. Может отсутствовать.
CampaignID Идентификатор кампании, к которой относится событие. Может отсутствовать.
BannerID Идентификатор объявления, к которому относится событие. Может отсутствовать.
PhraseID Идентификатор фразы, к которому относится событие. Может отсутствовать.
TextDescription Описание события.
EventType

Тип события. Одно из значений:

  • BannerModerated — объявление проверено модератором;
  • CampaignFinished — кампания остановлена в связи с наступлением даты окончания показов;
  • LowCTR — фраза отключена за низкий CTR;
  • MoneyOut — закончились средства на кампании или на общем счете;
  • MoneyWarning — баланс кампании или общего счета уменьшился до уровня, при котором отправляются уведомления (параметр MoneyWarningValue);
  • MoneyIn — пополнен баланс кампании или общий счет;
  • PausedByDayBudget — кампания остановлена, поскольку исчерпан дневной лимит бюджета;
  • WarnMinPrice — изменилась минимальная цена за клик;
  • WarnPlace — изменилась позиция показа объявления.
Timestamp Момент регистрации события в формате ISO 8601, например 2011-05-25T23:59:59Z.
EventName Краткое описание события.
Attributes Объект EventsLogItemAttributes с параметрами события. Состав параметров зависит от EventType.
Объект EventsLogItemAttributes
ModerationResult Результат модерации. Выводится для события BannerModerated.
MinPrice

Актуальная минимальная цена за клик. Выводится для события WarnMinPrice.

Значение конвертируется в валюту, указанную в параметре Currency, и округляется вверх с точностью до шага торгов в этой валюте.
Rest

Остаток средств на балансе кампании. Выводится для события MoneyWarning.

Значение конвертируется в валюту, указанную в параметре Currency, и округляется по математическим правилам с точностью до второго знака после запятой.

Если значение выражено в реальной валюте, оно не включает НДС.
Payed

Сумма зачисленных средств. Выводится для события MoneyIn.

Значение конвертируется в валюту, указанную в параметре Currency, и округляется по математическим правилам с точностью до второго знака после запятой.

Если значение выражено в реальной валюте, оно не включает НДС.
FinishDate Дата остановки кампании. Выводится для события CampaignFinished.
OldPlace Предыдущая позиция показа объявления. Выводится для события WarnPlace.
IsEditedByModerator Признак того, что объявление изменено модератором (Yes/No). Выводится для события BannerModerated.
StopTime Дата и время остановки кампании. Выводится для события PausedByDayBudget.
Currency

Валюта, в которой выражены денежные значения.

Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN.
Параметр Описание
Объект EventsLogItem
AccountID Идентификатор общего счета, к которому относится событие. Может отсутствовать.
CampaignID Идентификатор кампании, к которой относится событие. Может отсутствовать.
BannerID Идентификатор объявления, к которому относится событие. Может отсутствовать.
PhraseID Идентификатор фразы, к которому относится событие. Может отсутствовать.
TextDescription Описание события.
EventType

Тип события. Одно из значений:

  • BannerModerated — объявление проверено модератором;
  • CampaignFinished — кампания остановлена в связи с наступлением даты окончания показов;
  • LowCTR — фраза отключена за низкий CTR;
  • MoneyOut — закончились средства на кампании или на общем счете;
  • MoneyWarning — баланс кампании или общего счета уменьшился до уровня, при котором отправляются уведомления (параметр MoneyWarningValue);
  • MoneyIn — пополнен баланс кампании или общий счет;
  • PausedByDayBudget — кампания остановлена, поскольку исчерпан дневной лимит бюджета;
  • WarnMinPrice — изменилась минимальная цена за клик;
  • WarnPlace — изменилась позиция показа объявления.
Timestamp Момент регистрации события в формате ISO 8601, например 2011-05-25T23:59:59Z.
EventName Краткое описание события.
Attributes Объект EventsLogItemAttributes с параметрами события. Состав параметров зависит от EventType.
Объект EventsLogItemAttributes
ModerationResult Результат модерации. Выводится для события BannerModerated.
MinPrice

Актуальная минимальная цена за клик. Выводится для события WarnMinPrice.

Значение конвертируется в валюту, указанную в параметре Currency, и округляется вверх с точностью до шага торгов в этой валюте.
Rest

Остаток средств на балансе кампании. Выводится для события MoneyWarning.

Значение конвертируется в валюту, указанную в параметре Currency, и округляется по математическим правилам с точностью до второго знака после запятой.

Если значение выражено в реальной валюте, оно не включает НДС.
Payed

Сумма зачисленных средств. Выводится для события MoneyIn.

Значение конвертируется в валюту, указанную в параметре Currency, и округляется по математическим правилам с точностью до второго знака после запятой.

Если значение выражено в реальной валюте, оно не включает НДС.
FinishDate Дата остановки кампании. Выводится для события CampaignFinished.
OldPlace Предыдущая позиция показа объявления. Выводится для события WarnPlace.
IsEditedByModerator Признак того, что объявление изменено модератором (Yes/No). Выводится для события BannerModerated.
StopTime Дата и время остановки кампании. Выводится для события PausedByDayBudget.
Currency

Валюта, в которой выражены денежные значения.

Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN.

Примеры входных данных

Python

{
   'TimestampFrom': '2012-02-15T23:59:59Z',
   'TimestampTo': '2012-02-18T23:59:59Z',
   'Filter': {
      'CampaignIDS': [3193279],
      'EventType': ['MoneyIn', 'CampaignFinished']
   }
}

PHP

array(
   'TimestampFrom' => '2012-02-15T23:59:59Z',
   'TimestampTo' => '2012-02-18T23:59:59Z',
   'Filter' => array(
      'CampaignIDS' => array(3193279),
      'EventType' => array('MoneyIn', 'CampaignFinished')
   )
)

Perl

{
   'TimestampFrom' => '2012-02-15T23:59:59Z',
   'TimestampTo' => '2012-02-18T23:59:59Z',
   'Filter' => {
      'CampaignIDS' => [3193279],
      'EventType' => ['MoneyIn', 'CampaignFinished']
   }
}