Разработка
Alexey Lukyanchuk

Как работает библиотека tapi_yandex_direct?

Понадобилось мне выгрузить картинки из рекламных кампаний Яндекс. Директ. В библиотеке, дается довольно поверхностная инструкция рассчитанная на уровень программирования выше-среднего, где ссылка на ноутбук с примерами не очень рабочая (открывать надо в PyCharm), а документация АПИ Яндекс.Директ очень большая по объему, где заблудиться и потеряться очень легко. Моя статья призвана немного заполнить этот пробел.

Что такое Tapi?

Tapi (также известный как «Transport Agnostic API») — это библиотека в Python, предназначенная для упрощения взаимодействия с REST API. Она обеспечивает унифицированный подход к различным API, предоставляя обобщенный интерфейс для выполнения запросов и обработки ответов.

Библиотека `tapi_yandex_direct` является специализированной реализацией для API Яндекс. Директ, использующей функциональность Tapi. О чем как бы намекает префикс в названии библиотеки.

Структура использования библиотеки:

1. Инициализация клиента: Сначала создается объект, который настраивается для доступа к API с использованием вашего токена доступа и других параметров аутентификации. В интернете миллион документов на эту тему, я тут еще раз описывать процедуру получения токена не буду.

from tapi_yandex_direct import YandexDirect client = YandexDirect(access_token='YOUR_ACCESS_TOKEN', language='ru', # Язык ответов API # другие параметры)

2. Доступ к функциональности API через клиент: Клиент , соответствующие различным разделам API. Например, для работы с кампаниями используется метод `client. campaigns() `, который возвращает объект для выполнения запросов.

campaigns = client.campaigns()

3. Выполнение запросов: С помощью возвращенного объекта можно выполнять запросы:

response = campaigns.post(data=body) # Отправка запроса для получения или обновления данных кампании

или все одной строкой (как написано в документации):

response ​= client.campaigns().post(data=body)

Чтобы вывести результат:

print(response.data)

и вы получите список кампаний, т.к. это сервис Campaigns для управления кампаниями.

Проверим тип объекта:

type(response.data)​ # dict

Если вы хотите получить отчет аналогичный "Мастеру отчетов" из раздела "Статистика" в веб-интерфейсе Яндекс.Директ, то вам нужен другой метод ресурса - cервис Reports для получения статистики из раздела "Статистика" документации АПИ:

response ​= client.reports().post(data=body)

Проверим тип объекта:

type(​response.data)​ # str

Код одинаковый, но т.к. сервисы АПИ разные, а именно Кампании (Campaigns) и Отчеты (Reports), и наверное писали их скорее всего разные люди, то и результаты выполнения отличаются.

Получить все эти методы (различные сервисы АПИ) можно:

print(dir(client)) # [ # "adextensions", # операции с расширениями объявлений # "adgroups", # операции с группами объявлений # "adimages", # операции с изображениями # "ads", # операции с объявлениями # "agencyclients", # управление клиентами агентства # "audiencetargets", # управление условиями нацеливания на аудиторию # "bidmodifiers", # управление корректировками ставок # "bids", # управление ставками # "businesses", # получение профилей организаций # "campaigns", # управление кампаниями # "changes", # проверка наличия изменений # "clients", # управление параметрами рекламодателя и настройками пользователя # "creatives", # получение креативов # "debugtoken", # авторизационные токены # "dictionaries", # получение справочных данных # "dynamicads", # управление условиями нацеливания для динамических объявлений # "feeds", # операции с фидами # "keywordbids", # управление ставками # "keywords", # управление ключевыми фразами и автотаргетингами # "keywordsresearch", # предобработка ключевых фраз # "leads", # получение данных из форм на Турбо-страницах # "negativekeywordsharedsets", # управление наборами минус-фраз # "reports", # Сервис Отчеты # "retargeting", # управление условиями ретаргетинга и подбора аудитории # "sitelinks", # операции с быстрыми ссылками # "smartadtargets", # управление фильтрами — условиями нацеливания для смарт-баннеров # "turbopages", # получение параметров Турбо-страниц # "vcards", # операции с визитками # ]

или в исходном коде resource mapping. По каждому ресурсу можно воспользоваться встроеным хелпом:

client.campaigns().help(); # Documentation: https://tech.yandex.ru/direct/doc/ref-v5/campaigns/campaigns-docpage/ Resource path: json/v5/campaigns

4. Обработка ответов: После выполнения запроса объект ответа можно использовать для доступа к данным или статусу ответа. Объект ответа для извлечения и трансформации данных, такие как .data, .extract(), .to_values() и другие.

Полный список этих объектов и методов можно получить:

dir(response) # ['columns', 'data', 'response', 'store']
dir(response()) # ['data', 'delete', 'extract', 'get', 'help', 'items', 'iter_dicts', 'iter_items', 'iter_lines', 'iter_values', 'open_docs', 'open_in_browser', 'options', 'pages', 'patch', 'post', 'put', 'refresh_data', 'request_kwargs', 'response', 'status_code', 'to_columns', 'to_decimal', 'to_dict', 'to_dicts', 'to_lines', 'to_values', 'transform']

Насколько я понимаю, это не типично для объектов в Python и может вводить в заблуждение, а в документации об этом ничего не сказано. Возможно, это стандартное поведение для библиотеки Transport Agnostic API, что требует более глубокого погружения в документацию, а мы еще даже 2 сервиса до конца не рассмотрели, так что продолжим.

Ответ сервера можно вывести разными методами:

  • .data - выводит в типичном для запрошенного сервиса формате (словарь или строка)
  • .extract() - конвертирует в формат списка словарей. В Reports работать не будет. Сервис Отчеты по умолчанию выводит формат TSV.
  • .to_values() - конвертирует в формат списка списков строк. Работает только в Сервисе Отчетов (Reports).

Описание всех этих методов есть в документации (ниже ссылки с примерами)

Чего еще в супе не хватает? Параметров data= для функции .post(). Примеры всех этих параметров есть в документации.

body = { "method": "get", # не забывайте указывать метод "params": { "SelectionCriteria": {}, "FieldNames": ["Date", "CampaignId", "Clicks", "Cost"], "OrderBy": [{ "Field": "Date" }], "ReportName": "Actual Data", "ReportType": "CAMPAIGN_PERFORMANCE_REPORT", "DateRangeType": "LAST_WEEK", "Format": "TSV", "IncludeVAT": "YES", "IncludeDiscount": "YES" } }

Как работает АПИ Директа? При запросе отчета, вам надо указать "ReportName". А если вы запросили какой-то очень большой отчет. Насколько я знаю, Яндекс прямо не ограничивает размер данных, которые вы можете запросить, и в этом случае, формирование отчета требует времени. Это ведет к том, что скрипт будет запрашивать отчет по имени до тех пор, пока сервер не отдаст ответ "200" и не передаст данные отчета или не выдаст ошибку таймаут, что значит, вы запросили слишком большой отчет. Так же, вы можете запросить до 5 отчетов параллельно.
"method": "get" # не забывайте указывать метод. Сервис отчетов прекрасно работает и без указания метода, но остальные Сервисы без указания метод работать не будут. Ошибку, что метод не указан библиотека не выдает.

Доработаем наш код:

from datetime import datetime report_name = str(datetime.now()) + 'report name'

В 'report name' укажите свой логин, название отчета, все на что фантазии хватит, datetime.now() сделает название отчета уникальным. Имя отчета можно запросить из report_name если это потребуется. Мне лично ни разу не потребовалось.

Пример полного запроса

Допустим, мы хотим получить стандартный отчет "Даты" - "Показы" - "Клики" - "Конверсии". Для этого надо указать правильный тип отчета:

'ReportType': 'CUSTOM_REPORT' # Выбираем произвольную форму отчета

Описание всех возможных полей и типов отчетов - а кто говорил, что будет легко? Таким образом финальный код приобретает вид:

from datetime import datetime # Параметры для отчета report_params = { 'method': 'get', 'params': { 'SelectionCriteria': {}, # Пустые критерии означают выборку всех данных 'FieldNames': ['Date', 'Impressions', 'Clicks', 'Conversions'], 'ReportName': report_name, 'ReportType': 'CUSTOM_REPORT', 'DateRangeType': 'LAST_7_DAYS', # Выборка данных за последние 7 дней 'Format': 'TSV', # Формат отчета, можно выбрать CSV или XLSX 'IncludeVAT': 'YES', 'IncludeDiscount': 'NO' } } # Отправка запроса на создание отчета response = client.reports().post(data=report_params) # Проверка и вывод результатов print(response.data) # Date Impressions Clicks Conversions # 2024-04-06 58359 648 41 # 2024-04-07 71716 776 52 # 2024-04-08 81964 772 56 # 2024-04-09 60596 623 48

Весь код я протестировал на работоспособность, все должно работать.

Теперь надо создать датафрейм для Пандас или обработать данные иным способом:

... тут я планирую немного дописать код для обработки ответа.

Вот мы и разобрались с двумя сервисами АПИ Яндекс.Директа.

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

  • Сначала запросить id кампаний: .campaigns() или .reports()
  • Потом запросить статусы хеши изображений: .ads()
  • По списку хешей уже можно запросить url картинок: .adimages()

Но это уже совсем другая статья.

102 показа
70 открытий
0
Комментарии
Написать комментарий...
-3 комментариев
Раскрывать всегда