Взаимодействие с API Директа. Получаем статистику.
Олег Барабанов
29.06.2018
8 732
Для автоматизации работы с Яндекс.Директ все сервисы используют доступ через 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 Яндекс.Директ.
<!DOCTYPE html>
<html lang="ru">
<head>
<meta charset="utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Статистика Яндекс.Директ через API</title>
<link rel="stylesheet" href="css/normalize.css" />
</head>
<!-- Тело страницы -->
<body>
<?php
// Настройки для вывода содержимого буфера, которые позволяют делать вывод на экран
// при использовании функции sleep
ob_implicit_flush();
//--- Входные данные ---------------------------------------------------//
// Адрес сервиса Reports для отправки JSON-запросов (регистрозависимый)
$url = 'https://api-sandbox.direct.yandex.com/json/v5/reports'; // при работе с песочницей, используем поддомен api-sandbox
// OAuth-токен пользователя, от имени которого будут выполняться запросы, его получали на предыдущем этапе
$token = 'ПОЛУЧЕННЫЙ_ТЕСТОВЫЙ_ТОКЕН';
// Логин клиента рекламного агентства
// Обязательный параметр, если запросы выполняются от имени рекламного агентства
// Укажите здесь логин аккаунта на котором получен тестовый доступ к API Директа
$clientLogin = 'ЛОГИН_НА_КОТОРОМ_ЗАРЕГИСТРИРОВАНО_ПРИЛОЖЕНИЕ';
//--- Подготовка запроса -----------------------------------------------//
// Создание тела запроса
$report_name = date("Y-m-d-H-i-s"); // Используем текущую дату и время с точностью до секунд в качестве названия отчёта, т.к. при каждом запросе должно передаваться уникальное название отчёта
$params = [
"params" => [
"SelectionCriteria" => [
"DateFrom" => "2018-06-01", // начальная дата в формате ГГГГ-ММ-ДД
"DateTo" => "2018-06-08" // конечная дата для выборки статистики
],
"FieldNames" => ["Date", "CampaignName", "LocationOfPresenceName", "Impressions", "Clicks", "Cost"],
"ReportName" => "НАЗВАНИЕ_ОТЧЕТА",
"ReportType" => "CUSTOM_REPORT", // прописываем произвольный тип отчёта
"DateRangeType" => "CUSTOM_DATE", // произвольный период запроса
"Format" => "TSV", // формат ответа API
"IncludeVAT" => "NO",
"IncludeDiscount" => "NO"
]
];
// Преобразование входных параметров запроса в формат JSON
$body = json_encode($params);
// Создание HTTP-заголовков запроса
$headers = array(
// OAuth-токен. Использование слова Bearer обязательно
"Authorization: Bearer $token",
// Логин клиента рекламного агентства
"Client-Login: $clientLogin",
// Язык ответных сообщений
"Accept-Language: ru",
// Режим формирования отчета
"processingMode: auto",
// Формат денежных значений в отчете
"returnMoneyInMicros: false",
// Не выводить в отчете строку с названием отчета и диапазоном дат
"skipReportHeader: true",
// Не выводить в отчете строку с названиями полей
// "skipColumnHeader: true",
// Не выводить в отчете строку с количеством строк статистики
"skipReportSummary: true"
);
// Инициализация cURL
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $body);
/*
Для полноценного использования протокола 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');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HEADER, true);
curl_setopt($curl, CURLINFO_HEADER_OUT, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
// --- Запуск цикла для выполнения запросов ---
// Если получен HTTP-код 200, то выводится содержание отчета
// Если получен HTTP-код 201 или 202, выполняются повторные запросы
while (true) {
$result = curl_exec($curl);
if (!$result) {
echo ('Ошибка cURL: '.curl_errno($curl).' - '.curl_error($curl));
break;
} else {
// Разделение HTTP-заголовков и тела ответа
$responseHeadersSize = curl_getinfo($curl, CURLINFO_HEADER_SIZE);
$responseHeaders = substr($result, 0, $responseHeadersSize);
$responseBody = substr($result, $responseHeadersSize);
// Получение кода состояния HTTP
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
// Извлечение HTTP-заголовков ответа
// Идентификатор запроса
$requestId = preg_match('/RequestId: (\d+)/', $responseHeaders, $arr) ? $arr[1] : false;
// Рекомендуемый интервал в секундах для проверки готовности отчета
$retryIn = preg_match('/retryIn: (\d+)/', $responseHeaders, $arr) ? $arr[1] : 60;
if ($httpCode == 400) {
echo "Параметры запроса указаны неверно или достигнут лимит отчетов в очереди<br>";
echo "RequestId: {$requestId}<br>";
echo "JSON-код запроса:<br>{$body}<br>";
echo "JSON-код ответа сервера:<br>{$responseBody}<br>";
break;
} elseif ($httpCode == 200) {
echo "Отчет создан успешно<br>";
echo "RequestId: {$requestId}<br>";
echo $responseBody;
break;
} elseif ($httpCode == 201) {
echo "Отчет успешно поставлен в очередь в режиме офлайн<br>";
echo "Повторная отправка запроса через {$retryIn} секунд<br>";
echo "RequestId: {$requestId}<br>";
sleep($retryIn);
} elseif ($httpCode == 202) {
echo "Отчет формируется в режиме offline.<br>";
echo "Повторная отправка запроса через {$retryIn} секунд<br>";
echo "RequestId: {$requestId}<br>";
sleep($retryIn);
} elseif ($httpCode == 500) {
echo "При формировании отчета произошла ошибка. Пожалуйста, попробуйте повторить запрос позднее<br>";
echo "RequestId: {$requestId}<br>";
echo "JSON-код ответа сервера:<br>{$responseBody}<br>";
break;
} elseif ($httpCode == 502) {
echo "Время формирования отчета превысило серверное ограничение.<br>";
echo "Пожалуйста, попробуйте изменить параметры запроса - уменьшить период и количество запрашиваемых данных.<br>";
echo "RequestId: {$requestId}<br>";
break;
} else {
echo "Произошла непредвиденная ошибка.<br>";
echo "RequestId: {$requestId}<br>";
echo "JSON-код запроса:<br>{$body}<br>";
echo "JSON-код ответа сервера:<br>{$responseBody}<br>";
break;
}
}
}
curl_close($curl);
?>
</body>
</html>
В результате выполнения скрипта у вас должно получится примерно следующее.
Чтобы было удобнее читать результат работы скрипта, можно немного модифицировать наш код. Для вывода используется формат TSV. Это аналог формата CSV, единственным отличием является разделитель значений колонок. В CSV разделителем является запятая “,”, а в TSV – табуляция.
Результат выборки статистики для каждого дня записан с новой строки, чтобы вывести его построчно в окне браузера, после каждой строки отчёта нужно вставить тэг переноса строки <br>.
Используем следующий алгоритм:
$responseBody = explode ("\n",$responseBody); // преобразовываем отчёт в массив, разделитель «новая строка»
foreach ($responseBody as $response_row) {
echo $response_row."<br>"; // выводим каждую строку отчёта и добавляем в конце тэг переноса строки
}
Вставляем этот код в строке 129, вместо echo $responseBody;
Запускаем скрипт, на выходе получаем более удобочитаемый формат вывода отчёта.
Отчёт сформирован за каждый день с 01.06.2018 по 08.06.2018 по следующим показателям:
Date – дата,
CampaignName – название кампании,
LocationOfPresenceName – таргетинг,
Impressions – количество показов,
Clicks – количество кликов,
Cost – стоимость.
Этот пример наглядно демонстрирует возможность взаимодействия с API Директа. Кроме получения статистики можно редактировать рекламные кампании и управлять ставками вплоть до уровня ключевого слова.
Получить больше информации о типах отчётов и данных, которые можно запросить, вы сможете получить в разделе официальной документации по API Яндекс.Директа https://tech.yandex.ru/direct перейдя в раздел "Документация"Провести Аудит РК!
Подпишись и следи за выходом новых статей в нашем монстрограммеОстались вопросы?
Не нашли ответ на интересующий Вас вопрос? Или не нашли интересующую Вас статью? Задавайте вопросы и темы статей которые Вас интересуют в комментариях.
Этот веб-сайт использует файлы cookie, чтобы улучшить вашу работу во время навигации по веб-сайту. Из них файлы cookie, которые классифицируются как необходимые, хранятся в вашем браузере, поскольку они необходимы для работы основных функций веб-сайта. Мы также используем сторонние файлы cookie, которые помогают нам анализировать и понимать, как вы используете этот веб-сайт. Эти файлы cookie будут храниться в вашем браузере только с вашего согласия. У вас также есть возможность отказаться от этих файлов cookie. Но отказ от некоторых из этих файлов cookie может повлиять на ваш опыт просмотра.
Необходимые файлы cookie абсолютно необходимы для правильной работы веб-сайта. Эти файлы cookie анонимно обеспечивают основные функции и функции безопасности веб-сайта.
Cookie
Duration
Description
cookielawinfo-checkbox-analytics
11 months
Этот файл cookie устанавливается подключаемым модулем GDPR Cookie Consent. Файл cookie используется для хранения согласия пользователя на использование файлов cookie в категории «Аналитика».
cookielawinfo-checkbox-functional
11 months
Cookie-файл устанавливается в соответствии с GDPR, чтобы записать согласие пользователя на использование cookie-файлов в категории «Функциональные».
cookielawinfo-checkbox-necessary
11 months
Этот файл cookie устанавливается подключаемым модулем GDPR Cookie Consent. Файлы cookie используются для хранения согласия пользователя на файлы cookie в категории «Необходимые».
cookielawinfo-checkbox-others
11 months
Этот файл cookie устанавливается подключаемым модулем GDPR Cookie Consent. Файл cookie используется для хранения согласия пользователя на использование файлов cookie в категории «Другое».
cookielawinfo-checkbox-performance
11 months
Этот файл cookie устанавливается подключаемым модулем GDPR Cookie Consent. Файл cookie используется для хранения согласия пользователя на использование файлов cookie в категории «Производительность».
viewed_cookie_policy
11 months
Файл cookie устанавливается подключаемым модулем GDPR Cookie Consent и используется для хранения информации о том, согласился ли пользователь на использование файлов cookie. Он не хранит никаких личных данных.
Функциональные файлы cookie помогают выполнять определенные функции, такие как совместное использование содержимого веб-сайта в социальных сетях, сбор отзывов и другие сторонние функции.
Файлы cookie производительности используются для понимания и анализа ключевых показателей производительности веб-сайта, что помогает улучшить пользовательский интерфейс для посетителей.
Аналитические файлы cookie используются для понимания того, как посетители взаимодействуют с веб-сайтом. Эти файлы cookie помогают предоставить информацию о таких показателях, как количество посетителей, показатель отказов, источник трафика и т.д.
Рекламные файлы cookie используются для предоставления посетителям релевантной рекламы и маркетинговых кампаний. Эти файлы cookie отслеживают посетителей на веб-сайтах и собирают информацию для предоставления персонализированной рекламы.
29.06.2018 
8 732 
Для автоматизации работы с Яндекс.Директ все сервисы используют доступ через API. Это позволяет получать доступ ко всему функционалу Директа, от получения статистики и управления ставками до создания рекламных кампаний с нуля. Для использования API Директа не обязательно быть профессиональным программистом, достаточно базовых знаний в PHP или Python. Также желательно разобраться, как работают инструмент cURL и формат обмена данными JSON (это не сложно). Наглядный пример взаимодействия с API Директа – «Директ Коммандер».
Чтобы можно было попробовать API на практике, Яндекс предоставляет тестовый доступ к песочнице, которая имитирует работающие рекламные кампании. На которых можно испытать работу своих скриптов.
Получить «боевой» доступ к реальным рекламным кампаниям не сложно, нужно заполнить заявку и приложить листинг работающего скрипта.
В этой статье я расскажу об использовании API Яндекс.Директ для получения статистики при помощи PHP, а также о регистрации приложения и получении тестового доступа.
Вы попадёте на страницу «Создание приложения». Здесь нужно заполнить все поля, отмеченные звёздочкой (*), остальное не обязательно. В поле «Название приложения» пишем любое название, например «Первое тестовое приложение», далее в блоке «Платформы» отмечаем галкой «Веб-сервисы», для заполнения поля «Callback URI #1», необходимо кликнуть по ссылке «Подставить URL для разработки», в блоке «Доступы» выбираем «Яндекс.Директ» и ставим галку «Использование API Яндекс.Директа»
Пролистываем страницу до конца, нажимаем кнопку «Создать приложение». После этого откроется страница с названием и параметрами нового приложения. Сразу же скопируйте и сохраните ID нового приложения. Это потребуется в дальнейшем.
Поздравляю! Вы зарегистрировали своё первое приложение в Яндекс.OAuth!
OAuth-авторизация позволяет приложению работать с сервисами Яндекса от имени пользователя без авторизации по паролю (для этого используется специальный токен). Уровень доступа для приложения определяется пользователем.
На открывшейся странице переходим по ссылке «Получить доступ к API»
Далее соглашаемся с Условиями использования. После этого откроется страница «Настройки API» c активной вкладкой «Параметры», где нужно заполнить «Координаты технического специалиста по работе с API Директа» - Контактное лицо и Эл. Почта. На вкладке «Мои приложения» можно увидеть, какие приложения имеют доступ к аккаунту Яндекс.Директ через API на текущий момент. Например, если вы использовали Директ.Коммандер для работы с рекламными кампаниями, то увидите его в списке этих приложений.
Чтобы открыть доступ нашему приложению к API, переходим на вкладку «Мои заявки» и создаём новую заявку на тестовый доступ.
В заявке необходимо заполнить все поля, отмеченные красной звёздочкой (*).
Выбираем, ранее зарегистрированное приложение из списка, указываем e-mail для службы поддержки Яндекса, в специфике работы можно выбрать Прямого рекламодателя, предназначением работы программы будет автоматизация регулярной работы с кампаниями в Директе. В качестве новых возможностей укажите «Ежедневно снимает новые показатели статистики», а ожидаемой датой разработки можно установить любой день.
Остаётся согласиться с условиями Пользовательского соглашения и отправить заявку. После одобрения доступа к API (это займёт менее часа), можно начинать разработку приложения. Статус заявки будет отображаться на вкладке «Мои приложения».
Копируем ссылку, вставляем в адресную строку браузера, копируем ID приложения, он отображается на вкладке «Мои заявки». Переходим по созданной ссылке. Загрузится страница с подтверждением доступа, где необходимо нажать кнопку «Разрешить».
На следующем экране отобразится тот самый авторизационный токен, который нужно сохранить.
Для работы с тестовым доступом обязательно потребуется доступ к песочнице. Иначе, API Директа будет возвращать ошибку.
Переходим на вкладку «Песочница», и включаем её.
Чтобы было удобнее читать результат работы скрипта, можно немного модифицировать наш код. Для вывода используется формат TSV. Это аналог формата CSV, единственным отличием является разделитель значений колонок. В CSV разделителем является запятая “,”, а в TSV – табуляция.
Результат выборки статистики для каждого дня записан с новой строки, чтобы вывести его построчно в окне браузера, после каждой строки отчёта нужно вставить тэг переноса строки <br>.
Используем следующий алгоритм:
Отчёт сформирован за каждый день с 01.06.2018 по 08.06.2018 по следующим показателям:
25 мин.
Комментарии
Получается данные мы получаем тестовые. Из песочницы
А реальные то как получить?