GetChanges (Live)

Проверяет наличие изменений в кампаниях, объявлениях и персональных данных клиентов, а также в справочнике регионов, справочнике временных зон, в Яндекс Каталоге.

Метод сообщает о наличии или отсутствии изменений после указанной даты без детализации, что именно изменилось. Рекомендуется использовать метод следующим образом:

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

    Метод возвращает параметр Timestamp — текущее время на сервере по UTC.

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

  3. В случае получения ответа о наличии изменений актуальные данные можно получить с помощью соответствующих методов:

Примечание

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

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

Ниже показана структура входных данных в формате JSON. Параметры CampaignIDS, BannerIDS, Logins являются взаимоисключающими — только один из них может присутствовать в запросе.

{
   "method": "GetChanges",
   "param": {
      /* GetChangesRequest */
      "CampaignIDS": [
         (int)
         ...
      ],
      "BannerIDS": [
         (long)
         ...
      ],
      "Logins": [
         (string)
         ...
      ],
      "Timestamp": (string)
   }
}

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

Параметр

Описание

Требуется

Объект GetChangesRequest

CampaignIDS

Массив, содержащий идентификаторы кампаний (не более 100).

Нет

BannerIDS

Массив, содержащий идентификаторы объявлений (не более 1000). Объявления могут принадлежать разным кампаниям.

Нет

Logins

Массив, содержащий логины клиентов (агентств).

Нет

Timestamp

Момент времени, начиная с которого проверяются изменения. Указывается в формате YYYY-MM-DDThh:mm:ssZ (согласно ISO 8601), например 2014-05-24T23:59:59Z. Если метод вызван без параметра Timestamp, остальные параметры игнорируются, возвращается только текущее время на сервере.

Нет

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

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

{
   "data": {
      /* GetChangesResponse */
      "Campaigns": {
         /* GetChangesIntData */
         "Updated": [
            (int)
            ...
         ],
         "NotUpdated": [
            (int)
            ...
         ],
         "NotFound": [
            (int)
            ...
         ]
      },
      "Banners": {
         /* GetChangesLongData */
         "Updated": [
            (long)
            ...
         ],
         "NotUpdated": [
            (long)
            ...
         ],
         "NotFound": [
            (long)
            ...
         ]
      },
      "Logins": {
         /* GetChangesStringData */
         "Updated": [
            (string)
            ...
         ],
         "NotUpdated": [
            (string)
            ...
         ],
         "NotFound": [
            (string)
            ...
         ]
      },
      "CampaignsStatChange": [
         {  /* CampaignStatChangeItem */
            "CampaignID": (int),
            "BorderDate": (date)
         }
         ...
      ],
      "Timestamp": (string),
      "RubricsChanged": (string),
      "TimeZonesChanged": (string),
      "RegionsChanged": (string)
   }
}

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

Параметр

Описание

Объект GetChangesResponse

Campaigns

Присутствует в ответе, если при вызове метода задан массив CampaignIDS. Показывает наличие или отсутствие изменений в кампаниях либо что кампании с указанными идентификаторами не найдены.

Под изменением кампании подразумевается изменение параметров, которые возвращает метод GetCampaignsParams (Live), в том числе значимое изменение статуса кампании.

Banners

Присутствует в ответе, если при вызове метода задан массив CampaignIDS или массив BannerIDS. В первом случае показывает наличие или отсутствие изменений в объявлениях, принадлежащих указанным кампаниям, во втором — то же самое для указанных объявлений либо что объявления с такими идентификаторами не найдены.

Под изменением объявления подразумевается изменение параметров, которые возвращает метод GetBanners (Live), в том числе значимое изменение статуса объявления.

Logins

Присутствует в ответе, если при вызове метода задан массив Logins. Показывает наличие или отсутствие изменений в персональных данных клиентов.

CampaignsStatChange

Массив объектов CampaignStatChangeItem. Объекты содержат дату актуальности статистики (BorderDate) для кампаний, у которых в течение проверяемого периода статистика была скорректирована. Если таких кампаний нет, параметр не выводится.

Проверяемые кампании указываются явно в массиве CampaignIDS или определяются по принадлежности клиентам, логины которых указаны в массиве Logins.

Timestamp

Момент времени, когда выполнялся метод GetChanges. Выводится в формате YYYY-MM-DDThh:mm:ssZ, например 2014-05-24T23:59:59Z. Это время указывают при следующем вызове метода GetChanges, чтобы проверять изменения после данного момента.

RubricsChanged

Показывает наличие или отсутствие изменений в Яндекс Каталоге — Yes/No.

TimeZonesChanged

Показывает наличие или отсутствие изменений в справочнике временных зон — Yes/No.

RegionsChanged

Показывает наличие или отсутствие изменений в справочнике регионов — Yes/No.

Объект GetChangesIntData

NotUpdated

Содержит указанные при вызове идентификаторы кампаний, по которым не было изменений.

Updated

Содержит указанные при вызове идентификаторы кампаний, по которым произошли изменения.

NotFound

Содержит указанные при вызове идентификаторы кампаний, которые удалены или не существовали.

Объект GetChangesLongData

NotUpdated

Содержит указанные при вызове идентификаторы объявлений, по которым не было изменений.

Updated

Содержит указанные при вызове идентификаторы объявлений, по которым произошли изменения.

NotFound

Содержит указанные при вызове идентификаторы объявлений, которые удалены или не существовали.

Объект GetChangesStringData

NotUpdated

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

Updated

Содержит указанные при вызове логины, по которым изменились персональные данные клиентов.

NotFound

Содержит указанные при вызове логины, которые удалены или не существовали.

Объект CampaignStatChangeItem

CampaignID

Идентификатор кампании.

BorderDate

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

Сформированные ранее отчеты по статистике могут оказаться не актуальными, если в них отражены данные после даты BorderDate. Такие отчеты рекомендуется переформировать.

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

Python

{
   'CampaignIDS': [1327944,1327967],
   'Timestamp': '2011-05-24T23:59:59Z'
}

PHP

array(
   'BannerIDS' => array(1974642, 20920155, 20155899, 64654),
   'Timestamp' ='2011-05-24T23:59:59Z'
)

Perl

{
   'Logins' => ['agrom', 'john_smith', 'john_smith_old'],
   'Timestamp' ='2011-05-24T23:59:59Z'
}

Примеры результирующих данных

Состав результирующих данных зависит от входных параметров. Во всех случаях метод возвращает текущее время на сервере в параметре Timestamp.

Вызов без параметров

Возвращается текущее время на сервере.

{
   "data": {
      "Timestamp": "2011-05-24T23:59:59Z"
   }
}

Вызовов c параметром Timestamp

Возвращается информация о наличии изменений в Яндекс Каталоге, справочнике регионов и справочнике временных зон.

{
   "data": {
      "Timestamp": "2011-05-24T23:59:59Z",
      "RubricsChanged": "Yes",
      "TimeZonesChanged": "No",
      "RegionsChanged": "No"
   }
}

Вызов c параметрами BannerIDS и Timestamp

Возвращается информация о наличии изменений в объявлениях после указанной даты.

{
   "data": {
      "Banners": {
         "Updated": [1974642, 20920155],
         "NotUpdated": [20155899],
         "NotFound": [64654]
      },
      "Timestamp": "2011-05-24T23:59:59Z",
      "RubricsChanged": "Yes",
      "TimeZonesChanged": "No",
      "RegionsChanged": "No"
   }
}

Вызов c параметрами CampaignIDS и Timestamp

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

{
   "data": {
      "Campaigns": {
         "Updated": [1327944]
      },
      "Banners": {
         "Updated": [123123,123123],
         "NotUpdated": [43532452],
      },
      "CampaignsStatChange": [
         {
            "CampaignID": 1327944,
            "BorderDate": "2011-03-17"
         }
      ],
      "Timestamp": "2011-05-24T23:59:59Z",
      "RubricsChanged": "Yes",
      "TimeZonesChanged": "No",
      "RegionsChanged": "No"
   }
}

Вызов c параметрами Logins и Timestamp

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

{
   "data": {
     "Logins": {
         "Updated": ["agrom"],
         "NotUpdated": ["john_smith"],
         "NotFound": ["john_smith_old"]
      },
     "CampaignsStatChange": [
         {
            "CampaignID": 1327944,
            "BorderDate": "2011-03-17"
         },
         {
            "CampaignID": 23667919,
            "BorderDate": "2011-05-17"
         }
      ],
      "Timestamp": "2011-05-24T23:59:59Z",
      "RubricsChanged": "No",
      "TimeZonesChanged": "No",
      "RegionsChanged": "No"
   }
}
Предыдущая
GetChanges
Следующая
Коды ошибок и предупреждений