Яндекс руководство разработчика

Время на прочтение
6 мин

Количество просмотров 14K

Привет! Я Илья Назаров, менеджер отдела интернет-продвижения Digital Lab – студии веб- и мобильной разработки. Сегодня разберем просмотр геолокаций из Яндекс.Аудиторий в Excel и Power BI.

Большинство рекламодателей и специалистов по настройке рекламы знают, зачем нужны Яндекс.Аудитории. Один из самых востребованных вариантов – сегменты на основе геолокации. Что может быть проще? Рисуете на карте полигоны или загружаете адреса, указываете радиусы и задаете условия взаимодействия людей с локациями. ⠀

Через несколько часов аудитории готовы: они расскажут про ваш бизнес всем, кто подходит под критерии и пользуется интернетом. Но проходит время. Люди, входившие в аудитории, оказываются недоступны. Или вы получаете доступ к аудитории, созданной кем-то другим. И вот вы уже не помните и не понимаете, вокруг каких локаций и с какими условиями настроены аудитории, даже если они понятно названы. Знакомая ситуация?

Возможности веб-интерфейса Яндекс.Аудиторий по работе с готовыми сегментами сильно ограничены. Максимум вы можете:

• найти похожих пользователей,

• поделиться сегментом с кем-нибудь,

• придумать ему другое название,

• удалить.

Первые 3 действия требуют четкого понимания того, что именно содержится внутри. Поэтому ревизия давно забытых или чужих аудиторий нередко заканчивается действием 4 и созданием нового сегмента с названием, «по которому точно никогда не забуду, кто там находится».

Вспоминаем все

Есть рабочие варианты проверки того, что же находится внутри геолокации: 

1. зовете программиста, который покажет свой кунг-фу Python этому Яндексу;

2. гуглите и пытаетесь сами во всем разобраться;

3. повторяете за мной и пользуетесь стандартными инструментами специалистов по контекстной рекламе и интернет-маркетологов (например, Excel), а заодно повышаете свою квалификацию.

Хотя мы будем работать напрямую с API Яндекса, никакие навыки программирования не понадобятся.Получить координаты точек из аудитории можно в Excel, но интереснее увидеть их на карте, поэтому предлагаю воспользоваться Power BI. Он покажет их прямо на дашборде (в Excel все аналогично, но о нем – в самом конце).

Устанавливаем Power BI

Скачайте и установите Power BI Desktop. Программа только для Windows, поэтому маководам нужно использовать Parallels Desktop. Регистрация не обязательна: и без нее все замечательно работает.

Шаг 1. Получаем токен для доступа к API Яндекса

Токен – это своего рода пароль, который помогает API Яндекса вас узнавать и отвечать на запросы вашей программы, предоставляя нужные данные. Чтобы его получить, нужно зарегистрировать новое приложение по этой инструкции или воспользоваться моей ссылкой для получения токена.

Но где же моя ссылка? Хочу предупредить: полученный по ссылке токен категорически не рекомендуется давать никому, даже мне. Его обладатель получит доступ к чтению статистики и изменению Яндекс.Метрики, Яндекс.Аудиторий и Яндекс.Директа.

Узнаю ли я ваш токен без вашего ведома? Нет. Вы получите его на странице Яндекс (убедитесь сами по адресной строке), поэтому токен увидите только вы и сам Яндекс.

Сможете ли вы отключить или поменять токен? Да. Достаточно поменять пароль аккаунта Яндекс или отозвать доступ на странице Яндекс.Паспорта в разделе «Входы и устройства» > «Устройства, сервисы и программы».

Зарегистрируйте собственное предложение (на самом деле это просто) или пройдите по этой ссылке на страницу авторизации Яндекса.

Убедитесь, что вы залогинены в нужном аккаунте, и разрешите доступ к нему для приложения Power BI connector.

После нажатия на большую желтую кнопку вы увидите токен.

Пока не закрывайте эту страницу!

Шаг 2. Находим полный список аудиторий

Запустите Power BI.

1. Нажмите нижнюю часть кнопки Get data («Получить данные»), чтобы открыть меню часто используемых источников данных.

2. В нижней части меню выберите пункт Blank query.

Откроется редактор Power Query.

Нажмите кнопку Advanced Editor для открытия расширенного редактора. Удалите весь имеющийся там код и вместо него вставьте этот:

let
    token = "", // вставьте свой токен между двойными кавычками
                header = [

        #"Authorization" = "OAuth " & token,
        #"Content-Type" = "application/json" // для GET списка сегментов
],
    Url = "https://api-audience.yandex.ru/v1/management/segments", // список сегментов
    
    Options = [
            Headers = header // заголовки запроса
    ],
     Source = Web.Contents(Url,Options),

    Json = Json.Document(Source),
    Segments = Json[segments],
     getFieldNames = (rec as any) => let

        names = List.Transform(rec, Record.FieldNames),
        combine = List.Combine(names)
    in
        if Value.Is(rec, type record)
        then Record.FieldNames(rec)
        else List.Distinct(combine),
                unpack = 

            Table.FromRecords(Segments,getFieldNames(Segments),MissingField.UseNull)

in
    unpack

Получится примерно следующее:

Теперь во вторую строку (token = “”) вставьте полученный токен между двойными кавычками и нажмите Done. Вы увидите таблицу с сегментами Яндекс.Аудиторий, к которым есть доступ у аккаунта с этим токеном.

Шаг 3. Достаем нужное и отсекаем лишнее

Среди вас наверняка найдутся те, кому не нужно объяснять, что делать дальше. Поэтому рассказываю тем, кто редко или неуверенно пользуется Power BI. Остальные могут воспринимать этот текст как совет, а не руководство к действию.

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

Для фильтрации:

1. В правой части заголовка колонки type нажмите кнопку с треугольником, направленным вершиной вниз, чтобы открыть меню фильтра.

2. Оставьте галочку только напротив значения geo.

3. Нажмите кнопку OК.

Убедитесь, что в колонке status остались только строки со статусом processed (готовые). Если это не так, отфильтруйте колонку status точно так же, как только что фильтровали колонку type. Картинка без комментариев:

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

1. Нажмите на кнопку Manage Columns.

2. Выберите пункт Choose Columns.

3. В открывшемся списке оставьте только колонки name и points.

У вас останется таблица из двух колонок: name – название аудитории из интерфейса Яндекс.Аудиторий, points – список географических координат точек внутри нее.

1. Нажмите кнопку с расходящимися в разные стороны стрелками рядом с заголовком колонки points.

2. В появившемся меню извлечения элементов из списка выберите Expand to New Rows («Развернуть в новые строки»).

3. Список координат по каждой аудитории распакуется в новые строки таблицы. В каждой строке будет находиться одна координата. Нужно извлечь оттуда широту и долготу.

1. Снова нажмите расходящиеся в разные стороны стрелки в правой части заголовка колонки points. Появится меню извлечения элементов из записи.

2. Просто нажмите OК.

3. Вы увидите 2 новые колонки: с географической широтой и долготой.

4. Теперь поменяйте тип данных в таблице: Переключитесь на вкладку Transform («Преобразования») и выделите все колонки, кликая по их заголовкам с зажатой кнопкой Shift (или нажмите Ctrl+A).

5. Нажмите Detect Data Type («Определить тип данных»).

Данные готовы для загрузки в модель.

Вернитесь на вкладку Home.

1. Нажмите Close & Apply («Закрыть и применить»).

2. Окно Power Query Editor автоматически закроется, данные начнут загружаться в модель.

Шаг 4. Рисуем карту

Вернитесь в Power BI Desktop. 

На панели Visualizations («Диаграммы») щелкните по диаграмме Map («Карта») с изображением глобуса.

На рабочей области появится заглушка карты, на месте которой появится сама карта.

1. Справа на панели Fields появятся загруженные данные с названиями колонок. Схватите мышкой колонку points.latitude и перетащите ее в поле Latitude («Широта») на панели Visualizations. Если в Visualizations не видите Latitude, то выберите заглушку карты щелчком мыши, и поле появится.

2. Повторите действие, перетащив мышкой points.longitude в поле Longitude («Долгота»).

Вы увидите карту с точками:

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

Срезы (слайсеры)

Схватите мышкой название колонки name и перетащите его в любое свободное место на рабочей области.Как только вы отпустите мышку, Power BI создаст новую диаграмму Table («Таблица») со списком аудиторий.

Не снимая выделения с таблицы аудиторий, щелкните мышкой по кнопке Slicer («Срезы») на панели Visualizations.

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

Больше не нужно гадать!

Шаг 5. Работаем в Excel

Шаги 2 и 3 можно сделать в Excel начиная с 2016-й версии (вообще можно с 2012-й, но понадобится что-то установить – гугл в помощь).Мне не нужно заново повторять эти шаги, поэтому просто копирую все, что сделал в Power BI. Сначала в Power BI нажимаю кнопку Transform data («Преобразовать данные»).

Открывается уже знакомый редактор запросов Power Query Editor, где:

1. Выбираю нужный запрос.

2. Захожу в расширенный редактор.

3. Копирую весь имеющийся там код в буфер обмена.

Показываю на примере Excel 2019 для Windows.

1. Переключитесь на вкладку «Данные».

2. Нажмите «Получить данные» для открытия контекстного меню.

3. Выберите группу «Из других источников».

4. Выберите пункт «Пустой запрос».

Откроется редактор Power Query.

1. Нажмите «Расширенный редактор».

2. Замените код в окне расширенного редактора на скопированный из Power BI или из начала статьи.

3. Нажмите «Готово».

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

1. Нажмите «Изменить учетные данные», появится окно «Доступ к веб-содержимому». 

2. Нажмите «Подключение».

Появится таблица, аналогичная таблице в Power Query. Нажмите «Закрыть и загрузить», и данные загрузятся на лист.

Что делать с ними в Excel? Можно добавлять в каждую аудиторию по одной точке и получить сервис прямого геокодирования, где адрес превращается в географические координаты (но есть и более удобные инструменты, о которых можем поговорить потом).

На самом деле в Excel можно делать почти все то же самое, что и в Power BI. Например, напрямую работать с API Яндекса. Сегодня мы научились загружать аудитории, но можно и подключиться к Яндекс.Метрике или получить статистику из Яндекс.Директ.

Заключение

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

API Яндекс.Директа – это интерфейс рекламной системы для разработчиков программ. Он позволяет автоматизировать работу с Яндекс.Директ и использовать все его функции – от получения статистики до создания рекламных кампаний с нуля. И всё абсолютно бесплатно.

Результат работы с API – ваше приложение по управлению контекстной рекламой в Яндекс.Директ с собственными настройками и алгоритмами. Кстати, для этого совсем не обязательно быть профи в программировании – достаточно базовых знаний PHP или Python.

Как всё это применять и что нужно, чтобы начать работу – смотрите в этой статье.

Для чего нужен API Яндекс.Директ

API Директа дает возможность разрабатывать и внедрять алгоритмы для управления рекламными кампаниями под ваши нужды. Это пригодится как агентствам, так и крупным рекламодателям, которые запускают и ведут масштабные кампании. Их деятельность предполагает множество рутинных действий, например:

• Массовое создание и редактирование кампаний, объявлений и ключевых фраз;
• Управление ставками;
• Получение статистики по показам и кликам;
• Прогноз бюджета.

Инструмент API позволяет создать приложение, в котором все нужные вам однотипные операции выполняются автоматически и в котором можно создавать удобные инструменты для просмотра и редактирования кампаний. Автоматизировать можно практически всё, даже обновление цены за клик по заданному вами алгоритму.

Вы разрабатываете что-то наподобие Директ Коммандера. Эта программа – готовое решение Яндекса на основе API Яндекс.Директа. Как её применять, смотрите руководство по старой и новой версиям.

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

Структура API

По сути API Директа – это набор сервисов, каждый из которых привязан к конкретному классу объектов и имеет отдельный URL. Объекты API взаимосвязаны между собой, как показано на скриншоте:

Изображение из руководства Яндекса для разработчиков

Сервисы верхнего уровня – Campaign и AdGroup. Первый содержит настройки рекламной кампании, второй нужен для работы с группами объявлений.

На следующем уровне – сервисы Ad (параметры объявления), Keyword (ключевые фразы), Audience Target (условия нацеливания на аудиторию) и DynamicTextAdTarget (условия нацеливания для динамических объявлений).

Далее идут сервисы для работы с элементами объявления: AdImage (изображениями), VCard (виртуальной визиткой), SitelinksSet (блоком быстрых ссылок), AdExtension (расширением к объявлению).

Для управления условиями ретаргетинга и подбора аудитории есть специальный сервис – RetargetingList.

У каждого сервиса свой набор методов для выполнения операций с его объектами. Основные методы, которые доступны для всех объектов – это добавление (add), изменение параметров (update), удаление (delete) и получение параметров (get).

Есть также специфические методы, которые поддерживают определенные объекты. Например, отправление объявлений на модерацию (moderate) – метод для сервиса Ads. Весь список доступных методов по областям применения смотрите в документации API.

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

Шаг 1: создание и регистрация приложения на Яндекс.OAuth

Авторизуйтесь в Яндекс.Директе. Используйте для этого аккаунт разработчика – именно от этого имени ваше приложение будет выполнять запросы и управлять данными.

Перейдите по ссылке oauth.yandex.ru. Нажмите кнопку «Зарегистрировать новое приложение»:

В правой части страницы – ссылки на справочные материалы для разработчиков.

Далее вы попадаете на форму «Создание приложения», где нужно указать все его необходимые параметры:

Обязательные опции помечены звездочкой, это «Название» и «Доступы». Но чем больше информации о приложении вы укажете, тем более прозрачно оно будет для пользователей. Они будут знать, какой именно программе разрешают доступ к своему аккаунту.

В блоке «Платформы» отметьте галочкой «Веб-сервисы»:

Появится поле адреса. В нем вы указываете, куда направлять пользователя после того, как он разрешил или отказал приложению в доступе. Адресов Callback URI может быть несколько, например, для тестового и боевого режима.

На этапе создания приложения нажмите ссылку «Подставить URL для разработки».

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

В блоке «Доступы» выберите «Яндекс.Директ» и отметьте «Использование API Яндекс.Директа»:

Завершите создание приложения:

На этом регистрация закончена. При этом OAuth-сервер Яндекса сразу же генерирует и показывает на странице идентификатор и пароль приложения.

Они понадобятся вам далее.

Шаг 2: создание заявки на доступ

В аккаунте Яндекс.Директа долистайте до нижнего меню и перейдите по ссылке «API»:

Далее нажмите «Получить доступ к API»:

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

При первом входе нужно принять пользовательское соглашение:

На странице «Настройки API» перейдите на вкладку «Мои заявки», чтобы создать и отправить заявку на доступ к API. Нажмите кнопку «Новая заявка» и выберите её тип.

Тестовый доступ – это ограниченный доступ к API, то есть только к Песочнице – тестовой среде для отладки приложений. Она имитирует работающие рекламные кампании, их достаточно для того, чтобы протестировать и отладить приложение. Полный доступ (боевой) дает возможность управлять реальными рекламными кампаниями клиентов.

Так как приложение еще не разработано, создайте заявку на тестовый доступ. Для этого:

1) Из выпадающего списка выберите идентификатор, который получили после регистрации приложения на OAuth-сервере:

2) Укажите email для связи со службой поддержки;

3) Заполните остальные данные о приложении по максимуму – укажите, для чего оно предназначено, его основные функции и возможности и т.д.:

4) Подтвердите согласие с пользовательским соглашением и отправьте заявку.

Статус заявки отслеживайте здесь же – на вкладке «Мои заявки» в настройках. Дождитесь её одобрения – это может занять до 7 дней. Только после этого можно начинать разрабатывать приложение. В случае отклонения – узнайте причины и исправьте ошибки.

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

На вкладке «Мои приложения» можно увидеть, какие приложения уже имеют доступ к аккаунту Яндекс.Директ через API. В том числе, если вы использовали Директ.Коммандер, он появится в этом списке:

Шаг 3: создание тестового пользователя и тестовых данных для него

1) Зарегистрируйте аккаунт тестового пользователя в Яндекс.Директе;

2) Создайте от его имени рекламную кампанию в интерфейсе Яндекс.Директа – достаточно одного объявления с одним ключевиком, чтобы получить доступ к API;

3) В разделе API интерфейса Директа нажмите ссылку «Получить доступ к API» и примите пользовательское соглашение;

4) Включите песочницу – среду для отладки приложения, где можно управлять тестовыми кампаниями без реальных показов и внесения средств.

Для этого откройте вкладку «Песочница» на странице настроек API и начните ею пользоваться:

В следующем окне задайте параметры песочницы:

Поставьте галочку «Создать тестовые кампании». Если вы выбрали роль «Клиент» создаются три кампании. Для роли «Агентство» – 3 клиента с 3 кампаниями, их логины формируются автоматически. На одну кампанию каждого клиента зачисляется некоторая сумма.

Включение флажка «Общий счет» создает клиента с подключенным общим счетом. Для агентства опция недоступна.

Нажмите «Продолжить», чтобы начать управлять песочницей.

Внимание! Если сменить параметры, все данные удаляются. Нужно создавать песочницу заново.

5) От имени тестового пользователя получите отладочный токен. С помощью него можно проверять работу приложений.

Когда пользователь авторизуется в Яндекс.Директе и нажимает кнопку «Подтвердить», то есть дает доступ к своим данным приложения, сервер Яндекса генерирует токен и передает его приложению.

Как всё происходит:

• Приложение направляет пользователя на страницу Яндекс.OAuth;
• На этой странице пользователь разрешает доступ к своим данным приложению;
• Яндекс.OAuth перенаправляет пользователя на адрес, указанный в поле Callback URL. Код подтверждения или описание ошибки передается в параметре URL перенаправления;
• Приложение получает адрес перенаправления и извлекает код подтверждения;
• Приложение отправляет POST-запрос с этим кодом;
• Яндекс.OAuth возвращает токен в теле ответа.

Если объяснять с технической стороны, запрос к API выполняется по протоколу HTTPS методом POST (отправление данных). В этом запросе содержится HTTP-заголовок с токеном пользователя, от имени которого осуществляется запрос. Ответ содержит заголовок RequestId – это уникальный идентификатор запроса.

Некоторые приложения (например, консольные или установленные на телевизорах Smart TV) не могут получить код подтверждения из URL. В этом случае пользователь самостоятельно его получает от Яндекс.OAuth и вводит в приложении или на странице авторизации.

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

Далее вы выполняйте запросы к песочнице. Вот пример запроса:

Практика использования API Яндекс.Директ

В инструменте API множество методов для разных объектов, многие из них дорабатываются и улучшаются со временем. Рассмотрим подробно, как их применять на практике.

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

Отчет содержит ту же статистику, которая доступна в сервисе Яндекс Wordstat за прошедший месяц.

Ограничения:

• За сутки можно получить статистику для тысячи фраз;
• На сервере хранится максимум 5 отчетов по всем кампаниям;
• Отчеты хранятся на сервере в течение 5 часов, а затем автоматически удаляются.

Так выглядит структура входных данных в формате JSON:

{

   «method»: «CreateNewWordstatReport»,

   «param»: {

      /* NewWordstatReportInfo */

      «Phrases«: [

         (string)

         …

      ],

      «GeoID«: [

         (int)

         …

      ]

   }

}

Phrases – это массив ключевых фраз, по которым нужно получить статистику поисковых запросов (добавить можно не более 10). минус-фразы из нескольких слов пишите в скобках, например: холодильник -морозильник -(морозильная камера) -ремонт.

GeoID – идентификаторы регионов, по которым нужно получить статистику поисковых запросов. Можно исключить регион, поставив минус. Если вы не указали этот параметр, либо указали только минус-регионы, либо минус-регионы совпадают c плюс-регионами, статистика выдается по всем регионам.