Получаем Метки (Теги) кампаний Яндекс Директа по API v4

Получаем Метки (Теги) кампаний Яндекс Директа по API v4

Недавно мне поступил интересный вопрос: как получить метки (теги) кампаний из Яндекс.Директа в отчёт Power BI? Это именно те метки, которые проставляются рядом с каждой кампанией в кабинете Директа, чтобы категоризировать РК. 

Сначала я затруднился ответить - получения меток кампаний нет в нашем коннекторе. Но потом я вспомнил, что у меня есть прекрасный инструмент для тестирования GET и POST-запросов. В общем, решил помочь.

Читаем справку API и авторизуемся в Яндекс.Директе

Что приятно, мне сразу же прислали ссылку на справку API Директа: https://yandex.ru/dev/direct/doc/dg-v4/live/GetCampaignsTags.html. Прочитав её, я понял, что для получения меток кампаний нужно отправить в Яндекс Директ вот такой JSON:

{
   "method": "GetCampaignsTags",
   "param": { "CampaignIDS": [ 12345123, 67890123, ... ] }
}

Номера кампаний передаются в списке, который идёт внутри словаря. 
В целом структура файлика простая.

Для получения токена я воспользовался ссылкой из своего стандартного коннектора к Яндекс.Директу (ссылка на получение токена в самом низу): https://github.com/morinad/yandex_direct_pq.

Токен конечно я получил, но всё оказалось не так просто. Авторизация в старом API Яндекс.Директа работает по-другому. В 5-й версии нужно указать Header с именем "Authorization" и значением "Bearer TOKEN", где TOKEN - это полученный по ссылке токен. В 4-й версии токен отправляется прямо внутри тела запроса, например так:

{
    "method": "GetClientInfo",
    "param": ["agrom"],
    "locale": "ru",
    "token": "0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f"
}

Всё это уже нашлось в справке 4-й версии API: https://yandex.ru/dev/direct/doc/dg-v4/concepts/JSON.html. Если взять такой способ авторизации и добавить в наш запрос с метками кампаний, получим вот что:

{
   "method": "GetCampaignsTags",
   "param": { "CampaignIDS": [ 12345123, 67890123, ... ] },
   "token": "0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f"
}

Всё это нам нужно отправить на https://api.direct.yandex.ru/live/v4/json/, чтобы получить наши метки, ну или теги.

Коннектор для получения меток (тегов) кампаний Яндекс.Директа

Не так давно я начал разрабатывать сервис http://directprotools.ru/, добавив специальный модуль для тестирования запросов http://directprotools.ru/requests. 
Модуль помогает писать простые POST и GET-запросы на Power Query и Python. Давайте попробуем им воспользоваться.

Указываю тип запроса POST JSON (так как отправляем JSON), вводим ссылку. Справка говорит, что в ответ нам придёт JSON - выставляем формат ответа JSON. Остаётся задать сам JSON - тело запроса, которое мы будем отправлять:

Жму на кнопку "PQ" и получаю вот такой кусок кода:

Коннектор готов, а мне даже делать ничего не пришлось;) Но есть нюанс - токен и ID кампаний придётся всё время подставлять руками в код, что не совсем удобно. 

Обратим внимание на следующую часть http://directprotools.ru/requests, где можно добавлять заголовки, переменные и параметры:

Сейчас самое важное - параметры. С помощью параметров мы можем создать функцию, которая будет забирать метки в зависимости от заданных ID кампаний и токена. Уже не придётся каждый раз залезать в код - мы сможем задавать всё в параметрах функции. Добавляем 2 параметра - придумываем каждому уникальное название и задаём актуальные значения:

Сами по себе параметры ничего не дадут, теперь нужно использовать их в JSON вместо тестовых значений:

Остаётся нажать на кнопку "PQ" и получить готовый запрос, в котором отдельно вынесены переменные accesstoken и campaignids:

Самое время проверить как работает этот запрос в самом Power Query (можно тестировать в Excel или в Power BI). Загружаю его в Power Query в Excel и получаю вот что:

Немного ручных преобразований и мы получаем список ID кампаний Яндекс.Директа и их тегов в Power Query:

Важно помнить, что наши ручные преобразования придётся вручную копировать в функцию. Это мы сделаем чуть позже. 

Вернёмся к созданию функции - для этого нажмём на "Функция PQ" и получим код функции:

Как вы помните, мы вручную добавили несколько шагов преобразования, которые нельзя сгенерировать автоматом. Я обвёл их код на скриншоте:

Копируем их код и добавляем в конец нашей функции, не забыв удалить "in result":

(accesstoken, campaignids)=>
let
	headers=[],
	querydata = [],
	jsondata = Json.FromValue( Json.Document(Text.ToBinary("{
   	""method"": ""GetCampaignsTags"",
   	""param"": { ""CampaignIDS"": [ "&campaignids&" ] },
   	""token"": """&accesstoken&"""
	}"))),
	web = Web.Contents("https://api.direct.yandex.ru/live/v4/json/", [Headers = headers, ManualStatusHandling = {404, 400}, Query =querydata, Content = jsondata]),
	result = Json.Document(web),
	
	
	data = result[data],
    #"Преобразовано в таблицу" = Table.FromList(data, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    #"Развернутый элемент Column1" = Table.ExpandRecordColumn(#"Преобразовано в таблицу", "Column1", {"Tags", "CampaignID"}, {"Tags", "CampaignID"})
in
    #"Развернутый элемент Column1"

Теперь проверим работу функции в Power Query:

Как использовать эту функцию?

Я вижу 2 варианта получение меток (или тегов): 

  • добавлять столбец с метками к текущей таблице рекламных кампаний
  • отдельно запрашивать все метки и привязывать их к списку кампаний с помощью join

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

У второго способа есть и минус - для получения всех тегов сразу нужно сначала получить список всех ID кампаний. Давайте разберёмся как это проще всего сделать. Выше я давал ссылку на коннектор к Яндекс.Директу для Power BI. Можно воспользоваться им. У меня коннектор эксельный, так что выглядит чуть-чуть по-другому, но суть та же:

После получения данных, разворачиваем код шага и добавляем ссылку на столбец "ID кампании":

 Добавим к этому простой Text.Combine, чтобы получить список кампаний через запятую в тексте:

Остаётся подставить в функцию полученный список кампаний:

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

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

Комментарии