Вчера ходил на очередную встречу разработчиков по API Директа. Андрей Кашин, он в Яндексе отвечает за API Директа, рассказывал про закрытие API версий 4 и 4 Live и про развитие 5-й версии.

Во время встречи из зала было задано множество вопросов по поводу метода Changes.check. Для меня это было странно, т.к. не для всех был понятен алгоритм работы с этим методом. В связи с этим решил написать небольшую документацию, ну и заодно рассказать про некоторые подводные камни, которые могут встретиться при работе с сервисом Changes.

Самое больное в переходе с 4-й ветки на 5-ю для меня заключалось в ужесточении ограничений и перевода всех методов на бальную систему. Если раньше при запросе кампаний клиента никаких ограничений не было (ну кроме 5-ти одновременных запросов), то теперь приходится учитывать баллы. Раньше мы запрашивали список кампаний для всех клиентов раз в 5 минут и обновляли данные в БД. Теперь так не получается. Теперь надо отслеживать изменения с помощью Changes.check и на основе ответа обновлять данные.

Итак. Для начала необходимо получить список кампаний, в которых произошли изменения с помощью метода Changes.checkCampaigns передав в параметрах дату с которой необходимо отследить изменения.

{
  "method": "checkCampaigns",
  "params": {
    "Timestamp": "2015-02-02T10:08:22Z"
  }
}

В случае, если изменения произошли после даты, переданной в параметрах, то API вернёт примерно такой результат:

{
  "result": {
    "Campaigns": [{
      "CampaignId": 13243,
      "ChangesIn": ["SELF"]
    },
    {
      "CampaignId": 13326,
      "ChangesIn": ["SELF","CHILDREN"]
    },
    {
      "CampaignId": 14742,
      "ChangesIn": ["CHILDREN", "STAT"]
    }],
    "Timestamp": "2015-02-02T12:24:31Z"
  }
}

В ответе видно, что кампании 13243 и 13326 были обновлены и необходимо получить информацию об этих кампаниях с помощью метода Campaigns.get, а в кампаниях 13326 и 14742 произошли изменения внутри кампаний. Эти изменения необходимо получить с помощью метода Changes.check.

Теперь необходимо запросить изменения для тех кампаний, в которых произошли изменения:

{
  "method": "check",
  "params": {
    "CampaignIds": [13326,14742],
    "FieldNames": ["AdGroupIds","AdIds","CampaignsStat"],
    "Timestamp": "2015-02-02T10:08:22Z"
  }
}

Ответ API будет примерно таким:

{
  "result": {
    "Modified": {
      "AdGroupIds": [23543,23544,23874],
      "AdIds": [33651,33921,34028,34106],
      "CampaignsStat": [
        {
          "CampaignId": 14742,
          "BorderDate": "2015-01-28"
        }
      ]
    },
    "NotFound": {
      "CampaignIds": [13326]
    },
    "Timestamp": "2015-02-02T12:23:11Z"
  }
}

Далее необходимо обновить данные для групп объявлений и ключевых слов в этих группах для идентификаторов указанных в массиве Modified.AdGroupIds с помощью методов AdGroups.get и Keywords.get.

Аналогично необходимо поступить с обновлением объявлений. Идентификаторы изменённых объявлений находятся в массиве Modified.AdIds.

В случае, если массив Modified.CampaignsStat не пуст, то для каждой кампании, указанной в массиве необходимо получить данные начиная с даты BorderDate.

В массиве NotFound перечислены идентификаторы сущностей, которые не найдены в базе Директа. Их можно удалить из вашего кеша (например, БД).

Теперь немного о подводных камнях.

Камень номер раз. В данный момент API 5 не поддерживает работу с кампаниями с типом «Смарт-баннеры», но методы сервиса Changes возвращают информацию о изменениях в этих кампаниях. При попытке получить информацию о кампании такого типа метод Campaigns.get не вернёт ничего, но метод для получения информации об объявлениях вернёт ошибку 1002. В связи с этим перед вызовом Changes.check необходимо свериться со списком кампаний, которые находятся у вас в кеше.

Камень номер два. Получение списка кампаний пока необходимо делать с помощью метода Campaigns.get, а не Changes.checkCampaigns, т.к. нет гарантии, что после внедрения поддержки кампаний с типом «Смарт-баннеры» метод Changes.checkCampaigns сообщит о том, что необходимо получить информацию о таких кампаниях.

Вот, собственно, и всё. Ничего сложного в сервисе Changes нет.

Все примеры (с минимальными изменениями) взяты из официальной документации API 5 Директа.