Блог рекламных технологий

API Яндекс.Директа: встречайте пятую версию

adv
26 июня 2015, 15:24

Нашему программному интерфейсу пять лет. За это время он несколько раз сильно менялся, пока не дорос до «живой» версии 4 live в 2012 году. Наконец пришло время для запуска API 5 — новой версии с полностью перестроенной архитектурой, которая готова к появлению любых (даже самых неожиданных) настроек и форматов в Директе.

photoartboard.003.png

Первые методы API 5 появились в открытом доступе. Новая версия в разы удобнее и быстрее предыдущих. В течение года она будет работать в паре с привычным API 4 live — так что вы можете ускорять и оптимизировать рутинные операции, понемногу переключаясь на работу с API 5.


Сейчас в новом API можно управлять ставками и работать с рекламными материалами: создавать группы и объявления, добавлять ключевые слова, визитки, быстрые ссылки. По мере добавления методов мы поделимся с вами новостями.
Все свежие настройки и форматы Директа будут поддерживаться именно в пятой версии — её архитектура позволяет легко добавлять практически любую функциональность с поддержкой обратной совместимости.


О ключевых изменениях в API:


1. Отдельные веб-сервисы для операций с разными классами объектов. И у каждого — свой унифицированный набор методов. Такая архитектура позволяет работать только с нужными вам наборами данных, не выгружая все связанные с ними дополнительные параметры (к примеру, чтобы изменить регион показа для всех групп в кампании или добавить в список ключевых слов новую фразу не придется «возить» туда-обратно все данные кампании).
Большинство объектов — группу, визитку, быстрые ссылки и так далее — можно создать один раз и дальше использовать для всех объявлений, где они нужны.
Поддержка новых функций реализована без риска повредить уже отлаженной работе приложений: в API просто будут добавляться дополнительные веб-сервисы и наборы методов, которые вы сможете использовать, когда будете готовы.

2. Все объекты и ошибки подробно задокументированы. Чтобы элементы кампании было удобнее редактировать по отдельности, каждому из них теперь сразу присваивается свой Id.
По каждой операции вы получаете подробный отчет обо всех объектах внутри запроса, так что если один из них выдаст ошибку, вы точно будете знать, какой именно и что произошло. Остальные объекты внутри запроса не будут отклонены за ту же ошибку — вы получите отчет о том, что они успешно созданы или отредактированы.
Если в процессе работы с API что-то пойдет не так, сотрудникам службы поддержки будет достаточно идентификатора requestID, который вы получаете в ответе от сервера — в нём есть вся нужная информация.

3. Более прозрачная и гибкая система баллов. В API 5 баллы начисляются не раз в сутки, а равномерно в течение дня.
Баллы списываются за каждую операцию и в ответе от сервера к вам возвращается количество списанных и оставшихся баллов. Они рассчитываются и списываются точнее, поскольку для незначительных правок больше не приходится выгружать и загружать всю кампанию.
Мы упразднили почти все ограничения на количество запросов с одним и тем же методом, так что вы сами решаете, на какие операции вам важнее потратить баллы.

4. Универсальный язык методов. Принявшись за такие глобальные изменения в API, мы заодно поменяли названия методов, максимально приблизив их к международному обиходу. Так что специалистам, которые пишут приложения для разных рекламных систем, не придется держать в голове дополнительные термины. Banner превратился в Ad, Price — в Bid, Phrase — в Keyword и так далее.
У методов схожие названия, в которых легко разобраться. Например, VCards.add и Sitelinks.add для добавления элементов, а VCards.get и Sitelinks.get — для выгрузки данных о них.

5. И много других нововведений с учетом обратной связи от пользователей. Например, постраничная выборка данных и другие функции, о которых просили разработчики.
Более подробную информацию можно найти на странице API Директа. Изучайте API 5 в документации и на практике и делитесь с нами обратной связью. Мы будем благодарны вам за отзывы и предложения.




Версии 4 и 4 live будут закрыты в 2016 году. Мы предупредим вас об этом заранее. Но изучение новой версии лучше не откладывать на потом, поскольку интерфейс Директа стремительно пополняется новыми настройками, которые будут поддерживаться в API 5.

17 комментариев
Подписаться на комментарии к посту
a.borodatyuk@netpeak.net
26 июня 2015, 19:29

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

 

Я пишу к тому, чтобы вы подумали о том, чтобы убрать эти лимиты.

Речь о лимитах отчётов в очереди? 

k.vinokurov@getadiutor.com
27 июня 2015, 06:05

Речь о ограниченном количестве балов на аккаунт.

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

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

 

Баллы действительно начисляются на аккаунт рекламодателя, не на конкретное приложение. Их количество зависит от того, как рекламодатель работает с Директом.  В 5 версии используется прогрессивная шкала лимитов. Кроме того, сейчас можно использовать API как 5, так и 4 версии, и соответственно, использовать наборы баллов двух версий.

 

 

Коды ошибок - то что нужно! Спасибо!
https://tech.yandex.ru/direct/doc/dg-v4/reference/ErrorCodes-docpage/ 

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

В пятой версии используется прогрессивная шкала лимитов, которые начисляются по принципу скользящего окна. Для рекламодателей, эффективно и рационально использующих Директ, будет начисляться больше баллов. А сейчас вы можете использовать API как 5, так и 4 версии, и соответственно, использовать наборы баллов двух версий.

 

Про баллы в пятой версии можно подробнее почитать в документации https://tech.yandex.ru/direct/doc/dg/concepts/units-docpage/ 

 

 

Андрей Севастьянов
29 июня 2015, 15:07

 

Версии 4 и 4 live будут закрыты в 2016 году. Мы предупредим вас об этом заранее. Но изучение новой версии лучше не откладывать на потом, поскольку интерфейс Директа стремительно пополняется новыми настройками, которые будут поддерживаться в API 5.

Ребят, вы в своём уме, как можно отключить работающую версию апи? у нас целая система написана для управления кампаниями и объявлениями. Перейти с 4-ки на 5-ку это означает полностью переписать все коды, т.к. между ними нет никакой совместимости!

Речь не идет о внезапном отключении работающих версий. Переходить можно постепенно, по мере появления новых методов. Лаг по времени до полной "пересадки" на API5 будет достаточно большой — никак не меньше полугода. 

Новые функции Директа нельзя будет технически поддержать в старых версиях API. По мере их появления в вашу систему так или иначе можно будет внедрять методы API 5.

 

 

 

Андрей Севастьянов
1 июля 2015, 11:35

суть в том, что тот функционал который сейчас нами разработан на 4-й версии нас полностью устраивает (т.е. он полностью настроен и отлажен) и нам нет нужны переводить его на 5-ую версию, т.к. для нас это будет достаточно ресурсоёмко.

yndx.ishimova.support
1 июля 2015, 15:14

ну только развитие Директа не получится заморозить радо этого :) И в ближайший год сам сервис может перестроиться настолько, что так или иначе потребует изменений в приложениях. АПИ 4 к этому не готов, а АПИ 5 специально для этого создан.

Да пишите уж прямо: мы монополисты, вы никуда не денетесь. Что скажем, то и будете делать, неудачники.
Андрей Севастьянов
3 июля 2015, 13:07

Да, полностью согласен!

Андрей Севастьянов
3 июля 2015, 13:07

Если вы развиваете сервис для людей, думайте в перую очередь о людях, а не о своей выгоде и удобстве.

печально что всё так выходит :-(

yndx.ishimova.support
13 июля 2015, 16:37

Коллеги, удобство сервиса — это не удобство его команды, а удобство пользователей и дополнительные возможности, которые появляются с учетом обратной связи от вас.

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

Эти сценарии никак не зависят от размера сервиса и уж точно речь не о монополии. 

Разумеется, любые глобальные перемены — это стресс и дополнительные ресурсы с обеих сторон. Но результат себя оправдает: как минимум все будет работать быстрее и прозрачнее. Не говоря о том, что новая архитектура в будущем потребует 

На переход заложено достаточно много времени, больше, чем до конца года. Мы специально рассказали обо всем сразу, чтобы вы могли готовиться по мере выхода новых методов, а не единовременно, когда новый АПИ будет готов заменить старый. 

Добрый день, коллеги.

И с Новым Годом!

В данный момент API 5 уже можно использовать для мониторинга/изменения ставок например?

Для этого нужно получать новые токены, или можно пользоваться рабочими из 4 Live?