Взаимодействие с API Директа. Получаем статистику.
Для автоматизации работы с Яндекс.Директ все сервисы используют доступ через API. Это позволяет получать доступ ко всему функционалу Директа, от получения статистики и управления ставками до создания рекламных кампаний с нуля. Для использования API Директа не обязательно быть профессиональным программистом, достаточно базовых знаний в PHP или Python. Также желательно разобраться, как работают инструмент cURL и формат обмена данными JSON (это не сложно). Наглядный пример взаимодействия с API Директа – «Директ Коммандер».
Чтобы можно было попробовать API на практике, Яндекс предоставляет тестовый доступ к песочнице, которая имитирует работающие рекламные кампании. На которых можно испытать работу своих скриптов.
Получить «боевой» доступ к реальным рекламным кампаниям не сложно, нужно заполнить заявку и приложить листинг работающего скрипта.
В этой статье я расскажу об использовании API Яндекс.Директ для получения статистики при помощи PHP, а также о регистрации приложения и получении тестового доступа.
С чего начать?
1. Регистрируем приложение
Чтобы зарегистрировать своё приложение для работы с API, войдите в свой аккаунт на Яндексе и перейдите по ссылке https://oauth.yandex.ru/, нажмите кнопку «Зарегистрировать новое приложение».
Вы попадёте на страницу «Создание приложения». Здесь нужно заполнить все поля, отмеченные звёздочкой (*), остальное не обязательно. В поле «Название приложения» пишем любое название, например «Первое тестовое приложение», далее в блоке «Платформы» отмечаем галкой «Веб-сервисы», для заполнения поля «Callback URI #1», необходимо кликнуть по ссылке «Подставить URL для разработки», в блоке «Доступы» выбираем «Яндекс.Директ» и ставим галку «Использование API Яндекс.Директа»
Пролистываем страницу до конца, нажимаем кнопку «Создать приложение». После этого откроется страница с названием и параметрами нового приложения. Сразу же скопируйте и сохраните ID нового приложения. Это потребуется в дальнейшем.
Поздравляю! Вы зарегистрировали своё первое приложение в Яндекс.OAuth!
OAuth-авторизация позволяет приложению работать с сервисами Яндекса от имени пользователя без авторизации по паролю (для этого используется специальный токен). Уровень доступа для приложения определяется пользователем.
2. Получаем доступ к API
Чтобы приложение могло использовать API Яндекс.Директа, ему необходимо получить доступ к этому инструменту.
Войдите в Яндекс.Директ под тем же логином, на который зарегистрировано приложение в OAuth. Пролистайте страницу до самого низа, найдите блок «Управление кампаниями», перейдите по ссылке API.
На открывшейся странице переходим по ссылке «Получить доступ к API»
Далее соглашаемся с Условиями использования. После этого откроется страница «Настройки API» c активной вкладкой «Параметры», где нужно заполнить «Координаты технического специалиста по работе с API Директа» — Контактное лицо и Эл. Почта. На вкладке «Мои приложения» можно увидеть, какие приложения имеют доступ к аккаунту Яндекс.Директ через API на текущий момент. Например, если вы использовали Директ.Коммандер для работы с рекламными кампаниями, то увидите его в списке этих приложений.
Чтобы открыть доступ нашему приложению к API, переходим на вкладку «Мои заявки» и создаём новую заявку на тестовый доступ.
В заявке необходимо заполнить все поля, отмеченные красной звёздочкой (*).
Выбираем, ранее зарегистрированное приложение из списка, указываем e-mail для службы поддержки Яндекса, в специфике работы можно выбрать Прямого рекламодателя, предназначением работы программы будет автоматизация регулярной работы с кампаниями в Директе. В качестве новых возможностей укажите «Ежедневно снимает новые показатели статистики», а ожидаемой датой разработки можно установить любой день.
Остаётся согласиться с условиями Пользовательского соглашения и отправить заявку. После одобрения доступа к API (это займёт менее часа), можно начинать разработку приложения. Статус заявки будет отображаться на вкладке «Мои приложения».
3. Получаем статистику Яндекс.Директ при помощи PHP
Для доступа к рекламным кампаниям через API потребуется токен разработчика. Чтобы его получить (только после одобрения заявки на доступ!) переходим по ссылке
https://oauth.yandex.ru/authorize?response_type=token&client_id=ИДЕНТИФИКАТОР_ПРИЛОЖЕНИЯ
Копируем ссылку, вставляем в адресную строку браузера, копируем ID приложения, он отображается на вкладке «Мои заявки». Переходим по созданной ссылке. Загрузится страница с подтверждением доступа, где необходимо нажать кнопку «Разрешить».
На следующем экране отобразится тот самый авторизационный токен, который нужно сохранить.
Для работы с тестовым доступом обязательно потребуется доступ к песочнице. Иначе, API Директа будет возвращать ошибку.
Переходим на вкладку «Песочница», и включаем её.
Теперь можно приступать к написанию кода для запросов к API Яндекс.Директ на PHP
Общаться с API будем через cURL на языке JSON-запросов. В версиях PHP от 5.2.0 функционал для обработки JSON уже вшит в ядро. Поэтому, если вы будете использовать более ранние версии для написания кода, тогда придётся подключать сторонние библиотеки, для обработки JSON.
В данном примере используется PHP 5.6
Создаём на сервере php-файл, и вставляем в него следующий код. За основу взят пример кода для получения статистики из официальной документации API Яндекс.Директ.
/*
Для полноценного использования протокола HTTPS можно включить проверку SSL-сертификата сервера API Директа.
Чтобы включить проверку, установите опцию CURLOPT_SSL_VERIFYPEER в true, а также раскомментируйте строку с опцией CURLOPT_CAINFO и укажите путь к локальной копии корневого SSL-сертификата.
*/
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
// curl_setopt($curl, CURLOPT_CAINFO, getcwd().’\CA.pem’);
// — Запуск цикла для выполнения запросов —
// Если получен HTTP-код 200, то выводится содержание отчета
// Если получен HTTP-код 201 или 202, выполняются повторные запросы
while (true) <
echo (‘Ошибка cURL: ‘.curl_errno($curl).’ — ‘.curl_error($curl));
// Получение кода состояния HTTP
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
echo «Параметры запроса указаны неверно или достигнут лимит отчетов в очереди
»;
echo «RequestId: <$requestId>
»;
echo «JSON-код запроса:
<$body>
»;
echo «JSON-код ответа сервера:
<$responseBody>
»;
> elseif ($httpCode == 200) <
> elseif ($httpCode == 201) <
echo «Отчет успешно поставлен в очередь в режиме офлайн
»;
echo «Повторная отправка запроса через <$retryIn>секунд
»;
echo «RequestId: <$requestId>
»;
> elseif ($httpCode == 202) <
echo «Отчет формируется в режиме offline.
»;
echo «Повторная отправка запроса через <$retryIn>секунд
»;
echo «RequestId: <$requestId>
»;
> elseif ($httpCode == 500) <
echo «При формировании отчета произошла ошибка. Пожалуйста, попробуйте повторить запрос позднее
»;
echo «RequestId: <$requestId>
»;
echo «JSON-код ответа сервера:
<$responseBody>
»;
> elseif ($httpCode == 502) <
echo «Время формирования отчета превысило серверное ограничение.
»;
echo «Пожалуйста, попробуйте изменить параметры запроса — уменьшить период и количество запрашиваемых данных.
»;
echo «RequestId: <$requestId>
»;
echo «Произошла непредвиденная ошибка.
»;
echo «RequestId: <$requestId>
»;
echo «JSON-код запроса:
<$body>
»;
echo «JSON-код ответа сервера:
<$responseBody>
»;
PHP и Яндекс Директ: наш опыт использования
18 июня Яндекс анонсировал публичный доступ к API Яндекс Директ. Мы, как рекламное агентство, получили этот доступ немного раньше и сейчас используем его для управления ставками в рекламных кампаниях. Хотелось бы поделиться нашим опытом.
Первоначальные наши впечатления от API были достаточно противоречивые, все таки заметно, что это первая версия. Местами присутствуют несуразности в именовании элементов API, зачастую избыточна, на наш взгляд, система типов параметров методов.
Нашей целью было предоставить разработчикам проектов относительно простой механизм описания правил автоматического формирования ставок, при этом разработчик должен легко описывать тривиальные ситуации и иметь возможность реализовать произвольный алгоритм, если это потребуется отделам рекламы или продвижения интернет-проектов.
Использование чистого API в этой связи мы сочли малоперспективным 🙂 и решили написать над ним более удобный враппер.
Мы сразу же столкнулись с одним неприятным моментом. API использует протокол SOAP, на сервере используется SOAP::Lite. SOAP::Lite имеет некие специфические особенности при формировании представления массивов объектов, возвращаемых SOAP-методами, в результате которых на клиенте при использовании стандартного PHP-модуля SOAP Client cтановится невозможным использовать опцию classmap.
Эта опция позволяет связать типы данных SOAP с классами объектов, представляющими эти типы, и без нее, вообще-то, плохо. С другими реализациями SOAP-сервера, например на Java, такой проблемы не возникает, проверено на сервисах Google и разных других. Честно говоря, наших знаний о SOAP недостаточно, чтобы предложить вменяемый выход из этой ситуации, проблема скорее всего на стороне PHP, а не SOAP::Lite. Яндекс в свою очередь рекомендует использовать NuSOAP.
В общем, протокол вроде бы и стандартный, а щастья нет 🙁
Кстати говоря, для нормальной работы, скажем, с Google Adwords API, запрос, формируемый стандартным PHP Soap Client, приходится нещадно патчить, примеры можно посмотреть в исходниках PHP-клиента для этого сервиса.
Использовать NuSOAP мы убоялись и решили обойтись без classmap, работаем с простыми stdClass-объектами, которые возвращает API, добавляя по необходимости к ним поведение при помощи объектов-врапперов. Кроме того, врапперы выполняют трансляцию имен свойств из нашего стандарта (с подчеркиваниями) в CamelCase — хорошо, когда все единообразно.
Таким образом, разработчик может вызывать методы API в стандартной нотации нашей библиотеки, с логированием вызовов, выдерживанием временных промежутков между ними и т.д.
Основываясь на этом, добавляем поведение в сущности и коллекции. Использование собственных коллекций нам очень пригодилось, поскольку позволяет, например, писать так:
В настоящее время для большинства выборок в API отсутствует возможность применять правила фильтрации (некоторые методы позволяют, но не все). Поскольку выборка по различным условиями нам нужна, пришлось реализовывать ее на клиенте опять же в базовом классе коллекции.
В данном случае из набора фраз, который был возвращен веб-сервисом, мы отбираем фразы, начинающиеся на «рекламная фотосъемка» и «фотосъемка рекламы».
Where-условие представляет собой массив, ключи которого содержат имя поля, на которое накладывается условие, и операцию, которая используется для сопоставления, а значения — образец или список образцов, с которыми производится сопоставление. Результат выполнения — коллекция того же класса, что и исходная, но содержащая отфильтрованные элементы.
Пока нам хватает таких операций:
Теперь о том, как мы приспособили все это для разработчиков проектов.
Для каждого проекта создается сценарий управления рекламной кампанией. Он представляет собой PHP-скрипт, например следующего вида:
Сценарии запускаются приложением командной строки, реализованным в виде модуля Service.Yandex.Direct.Manager, приложение, в свою очередь, запускается кроном.
В каждом вызове мы определяем список объявление, для которых нужно изменить цены. Это делается путем последовательной выборки «кампании → объявления → фразы».
На самом деле, нас интересуют цены, а цены привязаны к фразам. Однако приложение умеет само достраивать недостающие звенья цепочки. Полное выражение в нашем случае выглядело бы так:
В принципе, ничего не мешает писать в файле сценария код, выполняющий те или иные действия над ценами и вызывающий затем стандартный метод update_prices(). Например, можно было бы написать так:
Приведенный выше код проходит по всем фразам, проверяет, обеспечивает ли текущая ставка показ в спецразмещениях, и соответствующим образом корректирует ее.
Если проект предъявляет какие-то особые требования к управлению кампанией, так и нужно делать, однако в большинстве проектов задачи по управлению ценами как правило сходные и очень простые, поэтому можно выделить эти стандартные действия в готовые методы, реализующие ту или иную стратегию изменения ставок.
Программист тестирует сценарий, после чего сценарий добавляется в приложение, управляющее кампаниями. Пока нам хватает одного процесса, но вообще можно запускать несколько экземпляров менеджера кампаний с отдельными очередями для разных клиентов.
Что мы получили в итоге? Написание объектного враппера над SOAP API позволило нам минимизировать количество кода для решения рутинных задач и в то же время сделать этот код достаточно читаемым для того, чтобы при необходимости даже непрограммист мог понять, по каким правилам формируются ставки. При этом мы оставляем для программиста возможность реализации произвольного алгоритма манипулирования ставками.
Автоматизация Яндекс.Директ. Часть 1
Совместно с коллегами из ADF Media — Артемом Дурневым и Султаном Назаралиевым, мы решили выпустить цикл из 6 статей, посвященных автоматизации процессов в Яндекс Директе. Сегодня вас ждет вступительная часть, в которой мы поговорим про API, токены Директа и Песочницу.
Чтобы автоматизировать работу Я.Директа, мы должны понимать, что такое API.
API — это составляющая часть сервиса, которая позволяет отправлять запросы и получать ответы.
Единого сценария работы с API нет. У каждого сервиса — сценарий свой. Единственное общее — это токены. Не важно с какой рекламной площадкой вы работаете, в любом случае вам нужно будет получать токен.
Токен — это «ключ» к сервису. Где-то токены нужно получать каждый час, а где-то вы должны владеть двумя «токенами» и передавать их на сервер, чтобы получать «истинный» токен в зашифрованном виде. А где-то вы просто получаете от системы один токен и пользуетесь им продолжительное время.
Так как мы говорим про Яндекс, то в нем получение токена организовано по принципу OAuth. Срок действия токена — один год.
OAuth — это протокол авторизации. Например, получив токен, вы можете передать его любому человеку для авторизации в сервисе, которым пользуетесь. Ему не нужно будет знать ваш логин и пароль, если у него есть токен.
Та же история с Я.Директом. Если вы передадите токен, человек сможет управлять рекламными кампаниями и скачивать данные из статистики за вас.
Токен Яндекс.Директа выглядит следующим образом:
Казалось бы, что это просто набор цифр и букв, но на самом деле каждый такой токен содержит следующую информацию:
Таким образом, токен показывает, что может делать данное приложение от имени определенного аккаунта.
Есть два варианта получения токена. Простой и сложный. Сложный заключается в том, что нам необходимо стать разработчиком и зарегистрировать приложение. Делается это следующим образом:
Указываем название приложения. В описании можно указать для чего создается приложение.
В графе «платформы” указываем веб-сервисы и нажимаем “Подставить URL для разработки».
Далее необходимо указать какие доступы мы можем запрашивать токеном.
После пройденных шагов, вы получите ID и пароль приложения.
После регистрации OAuth приложения нужно подать заявку на доступ к API Яндекс.Директ. Для этого заходим в Яндекс.Директ и переходим во вкладку API, как показано ниже.
Далее открываем «Мои заявки»
Смело нажимаем на «Полный доступ» и заполняем поля. Вот как заполнили мы:
В демо-доступе указали ссылку на Google Таблицу.
Срок рассмотрения заявки до 7 дней, но, как правило, рассмотрение занимает один-два дня. После этого заявка будет одобрена или отклонена. Как только приложение будет одобрено, вы сможете «вытаскивать» токены.
Переходим по ссылке вида:
(Не забудьте, поменять хвостик, заменив его на свой ID, который получили выше)
И в ответ на наш запрос — получаем токен.
Простой способ получения токена — Переходим на сайт ADF-media и авторизовываемся. В ответ на авторизацию, сайт покажет вам ваш токен.
Давайте сделаем первую часть цикла статей максимально полезной и поговорим еще и про Песочницу. Пока поверхностно, чтобы иметь о ней минимально представление.
Песочница — это среда для отладки приложений, взаимодействующих с API Директа.
Песочница имитирует API Директа, но полностью изолирована от настоящих данных. Это «игровая площадка», на которой можно вызывать методы API, получать ответы, наблюдать изменение тестовых кампаний и объявлений. Действия, которые доступны в API только при положительном балансе, в Песочнице доступны без фактического внесения средств.
Запросы к Песочнице не изменяют данные в Директе. Созданные объявления нигде не показываются, а списываемые и зачисляемые средства не влияют на настоящие кампании. Однако для кампаний имитируется полный набор состояний — от модерации до остановки показов при исчерпании средств. Статистические отчеты хотя и содержат условные данные, но по структуре совпадают с настоящими отчетами. Это делает Песочницу полнофункциональной средой для отладки приложений.
Песочница не имеет веб-интерфейса, и посмотреть тестовые кампании в интерфейсе невозможно. Работать с Песочницей можно только через вызовы методов API.
Но нужно помнить, что:
Мы знаем, что такое API, как зарегистрировать приложение и зачем это нужно, а также понимаем, что такое Песочница.
в следующей статье, мы воспользуемся полученными знаниями для передачи первых данных из Яндекс.Директа в Google Таблицы (без знания программирования).
Api яндекс директ php
Здесь мы будем рассказывать о новостях и тонкостях использования нашего API.
Подробное описание API представлено в документации. Также вам может пригодиться раздел с ответами на популярные вопросы.
Чтобы начать работу с API Яндекс.Директа, ознакомьтесь с информацией о доступе. Посмотрите рекомендации и требования к приложениям, если вы хотите написать на основе API свою программу.
Вопросы об API можно задавать через форму обратной связи.
Команда API Яндекс.Директа
В API Директа появился сервис DynamicFeedAdTargets. Он предназначен для выполнения операций с условиями нацеливания по фидам для динамических текстовых объявлений.
Примерно через восемь рабочих недель параметр StrategyPriority перестанет поддерживаться в сервисах:
Пожалуйста, запланируйте обновление своих приложений до конца января 2021 года. Мы напомним вам об изменениях перед тем, как они вступят в силу.
Если у вас появились вопросы, вы можете задать их специалистам службы поддержки.
В сервисе Campaigns, в стратегиях WB_MAXIMUM_CONVERSION_RATE,AVERAGE_ROI и AVERAGE_CPA ограничена возможность оптимизации по всем целям. Теперь в параметре GoalId для этих стратегий необходимо передавать идентификатор конкретной цели Яндекс.Метрики.
В сервисе Campaigns появились новые стратегии:
Стратегии принесут конверсии по цене, указанной при настройке стратегии.
Появилась поддержка профилей организаций из Яндекс.Справочника:
Смарт-баннеры — красивый и удобный формат Директа для ретаргетинга и генерации продаж, объявления с оплатой за клик и динамическим контентом. Чтобы вам было удобнее автоматизировать работу со смарт-баннерами, мы добавили возможность управлять ими в API Директа.
Какие нововведения появились в API:
Прочитать подробности об управлении смарт-баннерами через API можно в документации.
Добавлен таргетинг по интересам для текстово-графических объявлений:
Изменения подробно описаны в документации.
Метод Dictionaries.get возвращает в справочнике Currencies новый параметр MinimumAccountDailyBudget — минимальный дневной бюджет общего счета.
Валютный параметр MinimumPayment, который ранее совмещал два значения — минимальный платеж (без учета НДС) и минимальный дневной бюджет общего счета, используйте только в качестве ограничения минимального платежа.
Значения возвращаемых параметров SharedAccountFunds.Spend и CampaignFunds.Sum теперь включают НДС.
В сервисе Campaigns для настройки ADD_METRICA_TAG в структуре Settings значение по умолчанию изменено с NO на YES.
Таким образом, для новых кампаний настройка по умолчанию включена. Это означает, что к ссылкам объявлений автоматически добавляется метка ?yclid= с уникальным номером клика. Необходимо убедиться, что страницы сайта рекламодателя корректно открываются по ссылкам с этой меткой.
В методы сервиса Campaigns добавлен параметр AttributionModel для кампаний с типом «Текстово-графические объявления» и «Динамические объявления».
В сервисе Reports для входного параметра AttributionModels добавлено значение LYDC — «Последний переход из Яндекс.Директа». Статистика по новой модели атрибуции доступна за период начиная с 30 июля 2019 г.
Сервис Sitelinks теперь поддерживает до 8 быстрых ссылок в каждом наборе.
Суммарная длина текстов быстрых ссылок № 1–4 — не более 66 символов. Суммарная длина текстов быстрых ссылок № 5–8 — также не более 66 символов.
В сервис Campaigns внесены изменения, о которых мы сообщали ранее:
Изменения подробно описаны в документации.
Хотим предупредить вас, что в середине августа в сервисе Campaigns произойдут изменения, связанные с недавно анонсированным обновлением стратегий. Изменения затронут кампании с типом TEXT_CAMPAIGN и MOBILE_APP_CAMPAIGN.
Если на поиске автоматическая стратегия:
Если у вас появились вопросы, вы можете задать их специалистам службы поддержки.
В API Директа появилась поддержка наборов минус-фраз:
Если у вас появились вопросы, вы можете задать их специалистам службы поддержки.
Появилась поддержка видеообъявлений в медийных кампаниях:
Ограничение. Настройка Сбор аудитории видео в настоящее время не поддерживается в API.
Подробнее об управлении медийными кампаниями читайте в документации.
Хотим предупредить вас, что скоро к объявлениям в Директе можно будет добавить до восьми быстрых ссылок. Новый лимит начнет применяться в июне.
Изменения затронут сервис Sitelinks — если вы используете его, подготовьте свои приложения.
Любые вопросы вы можете задать специалистам службы поддержки API Директа.
Изменения, о которых мы писали ранее, вступили в силу: в API Директа появилась поддержка Турбо-страниц.
Параметр Href в структурах TextImageAd, TextAdBuilderAd, CpcVideoAdBuilderAd, CpmBannerAdBuilderAd стал nillable в методах Ads.update и Ads.get.
Параметры Href и Description стали nillable в методе Sitelinks.get.
В метод Sitelinks.get добавлен входной параметр SitelinkFieldNames.
Подробнее о Турбо-страницах читайте в документации.
Недавно мы запустили Турбо-страницы для десктопов. Теперь во многих типах объявлений ссылка на сайт стала необязательной — рекламодатель может указать только Турбо-страницу.
Что изменится в API
В сервисе Ads появится новое поле — TurboPageId. В структуре TextAd достаточно будет указать одно из полей Href, VCardId и TurboPageId.
В структурах TextImageAd, TextAdBuilderAd, CpcVideoAdBuilderAd, CpmBannerAdBuilderAd достаточно будет указать одно из полей Href и TurboPageId. Таким образом, поле Href станет необязательным в методе add, а в методах update и get оно станет nillable. Обратите внимание: метод get может вернуть nil (null) в поле Href — например, если рекламодатель удалил основную ссылку объявления. Приложение должно корректно обработать такой ответ.
В сервисе Sitelinks также появится поле TurboPageId. В структуре Sitelink достаточно будет указать одно из полей Href и TurboPageId. Кроме того, в методе get появится входной параметр SitelinkFieldNames: в нём можно перечислить имена полей быстрой ссылки, которые требуется получить. В ответе метода get поля Href и Description станут nillable — приложение также должно корректно обработать значение nil (null) в этих полях.
Список опубликованных Турбо-страниц рекламодателя можно будет получить с помощью нового метода — TurboPages.get.
Когда произойдут изменения
Поддержка Турбо-страниц в API появится ориентировочно через две-три недели. Пожалуйста, запланируйте обновление своих приложений. Если у вас появились вопросы, вы можете задать их специалистам службы поддержки API Директа.