Версии API

Стабильные версии API выпускаются один-два раза в год и после выпуска не меняются. На основе стабильной версии создается отдельная версия с обозначением «Live», например «Live 4». Ее развитие оперативно следует за новыми возможностями Яндекс.Директа, поэтому примерно раз в месяц в версию Live вносятся изменения.

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

Выбор между Live и стабильной версией

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

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

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

Рекомендации по использованию версии Live

Изменения вносятся в версию Live без уведомления пользователей. Источником информации об изменениях является новостная рассылка (подписка в интерфейсе Яндекс.Директа на странице «Управление доступом к API Директа»).

Ниже перечислены характерные изменения версии Live и даны рекомендации, повышающие адаптивность клиентских программ.

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

2. Новый параметр в ответе. Если программа знакома с форматом Live, она корректно обрабатывает новые параметры, иначе пропускает их. Игнорирование новых параметров не приводит к ошибкам, поскольку лишь выражает отказ от использования новых возможностей (они добавляются в версию Live таким образом, чтобы не повлиять на существующие функции).

   

   Если программа формирует запрос к API и не включает в запрос обязательные параметры (поскольку они не известны программе), значения таких параметров в базе данных могут быть заменены на предустановленные. Чтобы избежать этого, рекомендуется придерживаться техники, описанной в п.3.

3. Методы CreateOrUpdateCampaign

   [no-highlight[ Создает кампанию c указанными параметрами или изменяет параметры существующей кампании. подробнее CreateOrUpdateCampaign ]no-highlight]

   , CreateOrUpdateBanners

   [no-highlight[ Создает объявление или редактирует параметры существующего объявления. подробнее CreateOrUpdateBanners ]no-highlight]

   , UpdateClientInfo

   [no-highlight[ Изменяет персональные данные и полномочия пользователей. подробнее UpdateClientInfo ]no-highlight]

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

   [no-highlight[ Возвращает параметры кампании. подробнее GetCampaignParams ]no-highlight]

   , GetBanners

   [no-highlight[ Возвращает параметры объявлений. подробнее GetBanners ]no-highlight]

   и GetClientInfo

   [no-highlight[ Возвращает персональные данные пользователей. подробнее GetClientInfo ]no-highlight]

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