Миграция с Google AdWords API на Google Ads API: подробный мануал
Я неоднократно рассказывал о том, как с помощью языка R и пакета RAdwords запрашивать данные из рекламных аккаунтов одной из наиболее популярных в мире рекламных платформ Google Ads (ex Google AdWords).
Проблема в том, что пакет RAdwords работает с Google AdWords API версии 201809. Данный API давно не обновляется и прекратит работу 27 апреля 2022 года.
В этой статье я расскажу о новом пакете — rgoogleads, работу над котором я начал в июне 2021 года. На данный момент в пакете реализованы все необходимые для запроса данных функции. Далее мы подробно разберёмся с тем, как перейти с RAdwords на rgoogleads, для того, чтобы с апреля 2022 года ваши скрипты по прежнему корректно собирали необходимые данные из рекламных аккаунтов в Google Ads.
Эта статья полезна тем, у кого есть некоторые навыки написания кода на языке R и работы с пакетом RAdwords. Но даже если вы впервые слышите про этот язык и RAdwords, в статье будут примеры кода. Вам необходимо подставить идентификаторы ваших Google Ads аккаунтов и запросить нужные данные.
Возможности пакета rgoogleads
На данный момент пакет rgoogleads включает в себя весь необходимый функционал для запроса данных из Google Ads API:
- авторизация в API Google Ads;
- загрузка списка аккаунтов верхнего уровня;
- загрузка всей иерархии аккаунтов из управляющих аккаунтов;
- загрузка объектов рекламного кабинета: кампании, группы объявлений, объявления и другое;
- загрузка статистических данных из рекламных аккаунтов;
- загрузка метаданных ресурсов, полей ресурсов, сегментов и метрик;
- загрузка прогноза и исторических данных из планировщика ключевых слов.
Преимущества пакета rgoogleads
Теперь давайте разберёмся, какие преимущества дает переход на новый пакет rgoogleads:
- rgoogleads работает с Google Ads API v8 (релиз от 09.06.2021), RAdwords работает с Google AdWords API v201809. Google AdWords API прекратит работу 27.04.2022;
- для авторизации rgoogleads использует пакет gargle, что даёт гораздо больше гибкости по сравнению с тем, как устроен процесс авторизации в RAdwords;
- в rgoogleads есть вшитый токен разработчика Google Ads и OAuth клиент для авторизации. Это избавит большинство пользователей от необходимости запрашивать у поддержки Google базовый доступ к API Google Ads и тратить время на создание проекта и OAuth клиента в Google Cloud Console;
- у большинства функций rgoogleads аргумент cl, который позволяет осуществлять загрузку данных в многопоточном режиме;
- в отличие от RAdwords, у rgoogleads есть функции для загрузки списков и иерархии аккаунтов;
- у rgoogleads есть отдельные функции для загрузки основных объектов рекламных кабинетов, таких как рекламные кампании, группы объявлений, ключевые слова и объявления;
- за счёт того, что запрос данных не разделён на отдельные функции, синтаксис rgoogleads более понятный и лаконичный. В RAdwords вам необходимо было изначально создать запрос функцией statement(), после чего использовать его для запроса данных в функции getData() ;
- у rgoogleads нет проблем при загрузке названий, содержащих кириллицу;
- если запрос к API столкнулся со сбоем на сервере (статус ответа 429 или выше), пакет rgoogleads автоматически выждет паузу в 100 секунд и повторит попытку запросить данные. За счёт этого работа данного пакета более стабильна и устойчива к сбоям на сервере Google Ads API;
- rgoogleads выводит подробное сообщение об ошибке. Для сравнения, если пользователь допустил ошибку в составлении запроса, RAdwords не выводит никакие сообщения;
- rgoogleads позволяет запрашивать данные из планировщика ключевых слов.
Основные различия между Google AdWords API и Google AdsAPI
К счастью, ключевых различий между устаревшим и новым API не так много, и процесс миграции не должен вызвать у вас особых сложностей. Ниже я перечислю ключевые моменты миграции.
- нет необходимости менять автоионизационные данные, токен разработчика, id и secret OAuth клиента будут работать также и с новым Google Ads API;
- в AdWords API отчёты были выделены в отдельную службу, в Google Ads API отчёты являются частью одного сервиса. Вам достаточно включить в отчёты необходимые поля с метриками, которые нужно получить;
- В AdWords API существовали типы отчётов, например, CAMPAINGN_PERFORMANCE_REPORT. В Google Ads API их нет, вместо типов отчётов представлен огромный набор ресурсов;
- у AdWords API и Google Ads API разный формат ответа от API;
- в Google Ads API отсутствует параметр includeZeroImpressions, вместо него вы можете использовать фильтр metrics.impressions > 0.
Установка rgoogleads
Пакет уже доступен для скачивания из CRAN, но в связи с тем, что сейчас он находится в активной стадии разработки, я рекомендую устанавливать наиболее актуальную версию из GitHub.
# установка из github devtools::install_github(\\\'selesnow/rgoogleads\\\')
В течение нескольких месяцев окончательно сформируется функционал пакета, после чего рекомендовую установку именно из CRAN.
# установка из CRAN install.packages(\\\'rgoogleads\\\')
Как устроена авторизация в rgoogleads
Работа пpaктически с любым API начинается с авторизации. Здесь используется функционал пакета gargle. В связи с чем, процесс авторизации будет хорошо знаком пользователям таких пакетов как googlesheets4, googledrive, bigrquery, google***yticsR.
Самый простой способ пройти авторизацию — использовать функцию gads_auth(), передав в неё логин, под которым вам необходимо авторизоваться. Наверняка именно этот способ выберет большинство пользователей пакета:
gads_auth(email = \\\'me@gmail.com\\\')
После запуска функции gads_auth() вы будете перенаправлены в браузер, где необходимо предоставить пакету все необходимые разрешения.
Если вы всё сделали правильно, появится сообщение «Authentication complete. Please close this page and return to R».
Для более продвинутых пользователей существует возможность настройки конфигурации авторизации. То есть, если есть свой токен разработчика Google Ads и / или OAuth клиент, вы можете пройти авторизацию, используя свои учётные данные. Настроить конфигурации авторизации можно с помощью функции gads_auth_configure().
Основные аргументы функции gads_auth_configure():
- path — путь к JSON файлу с данными OAuth клиента;
- app — данные OAuth клиента, созданные через функцию httr::oauth_app() ;
- developer_token — ваш токен разработчика
При настройке конфигурации важно учитывать:
- У компании, то есть юридического лица, может быть только один токен разработчика;
- При первом использовании OAuth клиент из проекта Google Cloud с токеном разработчика, идентификатор клиента привязывается к токену разработчика и не может использоваться с другим токеном разработчика. Другими словами:
- токен разработчика можно использовать с несколькими идентификаторами клиентов;
- идентификатор OAuth клиента можно использовать только с одним токеном разработчика.
Если вы используете собственный токен разработчика, необходимо использовать созданный вами OAuth клиент. Если используете встроенный токен разработчика, можете использовать либо встроенный OAuth клиент, либо свой OAuth клиент.
О том как создать и настроить OAuth клиент (приложение в Google Cloud) читайте в статье «Как загрузить данные из API Google ***ytics в R: часть 2».
Собственный токен разработчика можно запросить только из управляющего аккаунта, меню Инструменты — Центр API.
Если вам необходимо пройти авторизацию, используя свой токен разработчика, и/или собственный OAuth клиент, воспользуйтесь следующим примером кода:
# конфигурация авторизации gads_auth_configure( path = \\\'C:/auth/app.json\\\', developer_token = \"own developer token\" ) # авторизация gads_auth(email = \\\'me@gmail.com\\\')
Опции пакета rgoogleads
Для более удобной работы и исключения необходимости установки одних и тех же аргументов в каждой функции пакета, в rgoogleads добавлены функции установки опций. Установленные опции действуют в ходе текущей R сессии.
- gads_set_customer_id() — установить идентификатор клиентского аккаунта, из которого вы будете запрашивать данные в течении сессии. Также можно установить сразу несколько аккаунтов с помощью с (“111-111-1111”, “222-222-2222”).
- gads_set_login_customer_id() — установка идентификатора управляющего аккаунта. Используйте опцию только, если работаете с рекламными аккаунтами, подчинёнными в управляющем аккаунте.
# идентификатор управляющего аккаунта gads_set_login_customer_id(\"xxx-xxx-xxxx\") # установка клиентского аккаунта gads_set_customer_id(\"yyy-yyy-yyyy\")
Загрузка отчётов из Google Ads с помощью rgoogleads
Теперь можно запросить отчёты по рекламным кампаниям, группам объявлений или любым другим ресурсам:
group_report <- gads_get_report( resource = \"ad_group\", fields = c(\"ad_group.campaign\", \"ad_group.id\", \"ad_group.name\", \"ad_group.status\", \"metrics.clicks\", \"metrics.cost_micros\"), date_from = \"2021-06-10\", date_to = \"2021-06-17\", where = \"ad_group.status = \\\'ENABLED\\\'\", order_by = c(\"metrics.clicks DESC\", \"metrics.cost_micros\"), limit = 30000 )
В Google Ads API есть огромное количество ресурсов, по которым вы можете запрашивать информацию с помощью функции gads_get_report().
Список и описание всех доступных ресурсов можно найти в официальной документации Google Ads API или запросить функцией gads_get_metadata().
resources <- gads_get_metadata(\"RESOURCE\")
У каждого ресурса есть собственный набор доступных полей. Посмотреть набор полей можно либо в документации, либо запросить с помощью функции gads_get_fields().
ad_group_fields <- gads_get_fields(\"ad_group\")
Миграция с RAdwords на rgoogleads
Ниже приведу таблицу соответствия функций в пакетах RAdwords и rgoogleads.
Операция | RAdwords | rgoogleads |
Авторизация | doAuth() | gads_auth_configure() + gads_auth() |
Запрос метаданных | reports(), metrics() | gads_get_metadata(), gads_get_fields() |
Запрос отчётов | statement() + getData() | gads_get_report() |
Бывшие в Google AdWords типы отчётов, в Google Ads стали ресурсами. Ниже — таблица сопоставления из официальной справки:
Тип отчёта в Google AdWords API | Ресурс в Google Ads API |
ACCOUNT_PERFORMANCE_REPORT | customer |
AD_PERFORMANCE_REPORT | ad_group_ad |
ADGROUP_PERFORMANCE_REPORT | ad_group |
AGE_RANGE_PERFORMANCE_REPORT | age_range_view |
AUDIENCE_PERFORMANCE_REPORT | campaign_audience_view, ad_group_audience_view |
AUTOMATIC_PLACEMENTS_PERFORMANCE_REPORT | group_placement_view |
BID_GOAL_PERFORMANCE_REPORT | bidding_strategy |
BUDGET_PERFORMANCE_REPORT | campaign_budget |
CALL_METRICS_CALL_DETAILS_REPORT | call_view |
CAMPAIGN_AD_SCHEDULE_TARGET_REPORT | ad_schedule_view |
CAMPAIGN_CRITERIA_REPORT | campaign_criterion |
CAMPAIGN_PERFORMANCE_REPORT | campaign |
CAMPAIGN_SHARED_SET_REPORT | campaign_shared_set |
CAMPAIGN_LOCATION_TARGET_REPORT | location_view |
CLICK_PERFORMANCE_REPORT | click_view |
DISPLAY_KEYWORD_PERFORMANCE_REPORT | display_keyword_view |
DISPLAY_TOPICS_PERFORMANCE_REPORT | topic_view |
GENDER_PERFORMANCE_REPORT | gender_view |
GEO_PERFORMANCE_REPORT | geographic_view, user_location_view |
KEYWORDLESS_QUERY_REPORT | dynamic_search_ads_search_term_view |
KEYWORDS_PERFORMANCE_REPORT | keyword_view |
LABEL_REPORT | label |
LANDING_PAGE_REPORT | landing_page_view, expanded_landing_page_view |
PAID_ORGANIC_QUERY_REPORT | paid_organic_search_term_view |
PARENTAL_STATUS_PERFORMANCE_REPORT | parental_status_view |
PLACEHOLDER_FEED_ITEM_REPORT | feed_item, feed_item_target |
PLACEHOLDER_REPORT | feed_placeholder_view |
PLACEMENT_PERFORMANCE_REPORT | managed_placement_view |
PRODUCT_PARTITION_REPORT | product_group_view |
SEARCH_QUERY_PERFORMANCE_REPORT | search_term_view |
SHARED_SET_CRITERIA_REPORT | shared_criterion |
SHARED_SET_REPORT | shared_set |
SHOPPING_PERFORMANCE_REPORT | shopping_performance_view |
URL_PERFORMANCE_REPORT | detail_placement_view |
USER_AD_DISTANCE_REPORT | distance_view |
VIDEO_PERFORMANCE_REPORT | video |
Соответствие полей «Отчёт» и полей ресурсов можно найти в официальной справке. Таблица очень большая, поэтому не вижу смысла дублировать её здесь.
Ниже приведу пример запроса отчёта по эффективности рекламных кампаний с одним и тем же набором полей, с помощью пакета RAdwords и rgoogleads.
Запрос отчёта по эффективности рекламных кампаний с помощью RAdwords
library(RAdwords) # авторизация adwords_auth <- doAuth() # составляем запрос query <- statement( select = c(\\\'CampaignName\\\', \\\'Date\\\', \\\'Clicks\\\'), report = \\\'CAMPAIGN_PERFORMANCE_REPORT\\\', start = \\\'2021-06-01\\\', end = \\\'2021-06-30\\\' ) # загрузка данных data1 <- getData( clientCustomerId = \\\'xxx-xxx-xxxx\\\', statement = query, google_auth = adwords_auth )
Запрос отчёта по эффективности рекламных кампаний с помощью rgoogleads
library(rgoogleads) # авторизация gads_auth_configure(path = \\\'D:/ga_auth/app.json\\\') gads_auth(email = \\\'me@gmail.com\\\') # загрузка данных data2 <- gads_get_report( resource = \\\'campaign\\\', fields = c(\\\'campaign.name\\\', \\\'segments.date\\\', \\\'metrics.clicks\\\'), date_from = \\\'2021-06-01\\\', date_to = \\\'2021-06-30\\\', customer_id = \\\'676-642-7440\\\', login_customer_id = \\\'xxx-xxx-xxxx\\\' )
Полезные ссылки
На данный момент в освоении rgoogleads вам помогут:
Заключение
Если вы используете для загрузки данных из рекламных кабинетов RAdwords, то уже сейчас стоит начать перевод своих скриптов на пакет rgoogleads. В противном случае сбор данных из ваших аккаунтов скорее всего перестанет работать с 27 апреля 2022 года.
Материал изложенный в статье может быть использован даже тем, кто ранее не сталкивался с запросом данных из Google AdWords API или Google Ads API. Вам достаточно установить язык R и среду разработки RStudio, скопировать из статьи примеры кода, и подставить свои идентификаторы аккаунтов. Если вам нужна помощь в установке необходимого программного обеспечения посмотрите этот видео урок. Также начать изучения языка R можно с бесплатного курса «Язык R для пользователей Excel».
Если вы интересуетесь или планируете начать изучение языка R? вам наверняка будет полезен мой telegram и youtube канал R4marketing.
Буду рад ответить на ваши вопросы в комментариях.
Комментарии:
Если вы не можете улучшить свой уровень конверсий и поднять ставки, оптимизация показателя качества может быть вашим единственным выходом, чтобы сохранить высокий рейтинг без больших затрат. Статья, которая расставляет точки над «i»....
22 03 2023 20:55:44
После того, как мы разобрали виды мобильных версий сайтов, их плюсы и минусы — стоит поговорить о сервисах, которые облегчают аудит....
21 03 2023 22:43:11
Как понять, что проект нуждается в новых текстах и сделать читателя счастливым...
20 03 2023 3:41:12
Есть восхитительная возможность продвинуть видео на YouTube с минимальными финансовыми потерями!...
19 03 2023 12:18:12
Конкректная цель — конкретные результаты трудоустройства...
18 03 2023 0:27:12
Словарь, которым пользуются SEO-специалисты агентства Netpeak...
17 03 2023 23:51:20
Откуда берутся установки и стоит ли тратить деньги на покупку мотивов...
16 03 2023 20:12:22
Как с помощью Google Tag Manager отслеживать исходящие ссылки на сайте и загрузки файлов с него...
15 03 2023 7:41:57
Понятные людям и роботам URL. Это уникальный набор символов, который дает возможность идентифицировать всевозможные ресурсы в интернете (страницы сайтов, файлы, изображения, видео и так далее). Чтобы узнать больше, читайте далее!...
14 03 2023 19:19:55
Узнайте, как пользоваться Инспектором и внутренними диаграммами Facebook, чтобы быть в лидерах своей ниши!...
13 03 2023 5:29:35
Инструменты интернет-маркетинга, которые вы не используете или используете не на сто процентов....
12 03 2023 18:43:48
От идеи для стартапа до плана развития и масштабирования бизнеса. Познавательные, полезные каналы, которые помогут реализовать смелые бизнес-цели. Узнать больше!...
11 03 2023 20:48:59
кмс Google: как достичь поставленной цели с помощью рекламы? Делимся советам по настройке КМС-кампаний....
10 03 2023 6:15:53
Ноу-хау, интересные для бизнеса, которые вошли в ежегодный рейтинг журнала Time....
09 03 2023 17:27:45
7 советов для оптимизации вашего профиля в Google Мой Бизнес....
08 03 2023 0:24:19
Многие специалисты недооценивают эффективность отчетов Яндекс.Метрики. Очень зря. Вот чем они могут быть полезны....
07 03 2023 10:22:22
Аккаунт менеджеры это... Быть лицом компании, проводником между заказчиком и комaндой агентства, ментором для коллег и суперменом, готовым прийти на помощь клиенту в любой час дня и ночи… Эти задачи по плечу аккаунт-менеджерам Netpeak...
06 03 2023 1:29:23
Анализ пути — это как многокaнaльные последовательности в Universal ***ytics, только лучше....
05 03 2023 14:12:44
Быстрые ссылки и другие советы на тему того, как эффективно работать в Директ Коммaндере....
04 03 2023 16:29:29
На скорость и полноту результатов продвижения влияют конкретные риски. И некоторые из них можно выделить еще до начала сотрудничества. Рассказываем, какие именно....
03 03 2023 3:59:50
Как упростить работу со скриптами на языке R? Программирование удобного интерфейса с помощью пакета «gWidgets»...
02 03 2023 16:13:21
Импорт из Google ***ytics в Excel — manual по ***ytics Edge....
01 03 2023 8:44:45
Почему популярность электромобилей растет и как это связан с продажей углеродных квот...
28 02 2023 6:57:47
Как протестировать MVP мобильного приложения, получить обратную связь и сформировать гипотезы...
27 02 2023 8:25:22
Обзор ресурса по подбору ключевых запросов www.SEMRUSH.com на Netpeak.ua...
26 02 2023 12:20:51
Советы специалистов по продвижению интернет-магазинов в сверхконкурентной нише одежды и обуви...
25 02 2023 22:45:14
Не можете найти нужны отчёт в Google ***ytics? Или хотите ускорить поиск нужных данных и отчётов. В помощь ⏩ Обзор к Google ***ytics Intelligence....
24 02 2023 8:14:59
Что же такое эти authority и чем они лучше и полезнее, к примеру, чем Page Rank?...
23 02 2023 10:26:15
Одно из фундаментальных обновлений Universal ***ytics...
22 02 2023 17:35:25
Разработка, вёрстка и оптимизация мобильных версий сайтов — популярные темы последнего времени. Мы расскажем, что стоит и что не стоит делать в мобильном SEO....
21 02 2023 14:56:32
История Affise от фаундера компании, рассказанная на SaaS Nation....
20 02 2023 6:54:35
Как перенести сайт с http на https и сохранить трафик, потратив минимум времени....
19 02 2023 12:14:37
Дайджест-путеводитель по серии постов о работе с редакторами электронных таблиц для PPC-специалистов....
18 02 2023 16:21:16
Контент может информировать, вовлекать и продавать, при этом для каждой цели нужен свой тип контента...
17 02 2023 10:48:25
Будь мобильным — заливай видео на Youtube с телефона...
16 02 2023 17:45:33
Пост по мотивам видео Мэтта Каттса из Google. Из первых рук, как говорится....
15 02 2023 20:55:30
Такое обозрение очередной новинки Google от Сергея Бахаря...
14 02 2023 21:58:26
Как увеличить охват целевой аудитории ресторана или магазина с помощью рекламы на мобильных и сверхточного геотаргетинга...
13 02 2023 7:58:25
В 2019 году в цикл зрелости вошли 28 технологий и инструментов...
12 02 2023 0:36:31
Почему нельзя просто взять и перевести. В худшем случае специализированный текст на иностранном языке должен стать для переводчика дорожной картой, в лучшем — источником вдохновения. Почему? Читайте об этом!...
11 02 2023 21:44:37
Стратегия продвижения, благодаря которой удалось снизить стоимость заявки от покупателей. Рассказываем об особенностях проведения акций в нише. Узнать больше!...
10 02 2023 13:44:31
Как с помощью рекламы в Apple Search Ads получить дешевые установки и привлечь релевантных пользователей среди владельцев айфонов...
09 02 2023 8:11:23
Используем маску ввода для оптимизации сбора телефонных номеров в формах на сайте: кейсы агентства Netpeak...
08 02 2023 4:49:36
Новости агентства Netpeak за предыдущий квартал. Появление отдела веб-аналитики. Открыли услугу «Создание и ведение блогов». Добавили мультивалютность. Глобально изменили скрипт Netpeak X-Reference. Запустили серию писем. Что еще?...
07 02 2023 0:31:47
Николь Лаззаро из XEODesign провела исследование о том, почему мы играем или не играем в игры....
06 02 2023 16:48:36
Как узнать особенности бизнеса в нише и что позаимствовать у конкурентов для SEO...
05 02 2023 5:38:41
Всё о вебхуках. Как настроить механизм получения уведомлений о событиях с помощью функций обратных вызовов....
04 02 2023 23:11:40
Когда на сайт добавляют новый контент, он тут же трaнcлируется в RSS-ленту и отображается в специальных программах для чтения, либо в email подписчиков. Как это работает?...
03 02 2023 23:36:20
На вопрос «как все успеть?» хочется ответить что-то вроде «никак». Особенно, если дело касается задач, связанных с творчеством. Но можно и не срывать дедлайны. Читать дальше....
02 02 2023 1:23:48
Популярные скрипты Google Рекламы позволяют автоматизировать рутинные и монотонные процессы. Каждый скрипт состоит из функций, переменных, объектов, сущностей, селекторов, итераторов...
01 02 2023 3:58:43
Еще:
понять и запомнить -1 :: понять и запомнить -2 :: понять и запомнить -3 :: понять и запомнить -4 :: понять и запомнить -5 :: понять и запомнить -6 :: понять и запомнить -7 ::