Миграция с 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 — ваш токен разработчика

При настройке конфигурации важно учитывать:

1. У компании, то есть юридического лица, может быть только один токен разработчика;
2. При первом использовании 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 вам помогут:

1. Официальный сайт пакета с документацией
2. Страница пакета на CRAN

Заключение

Если вы используете для загрузки данных из рекламных кабинетов RAdwords, то уже сейчас стоит начать перевод своих скриптов на пакет rgoogleads. В противном случае сбор данных из ваших аккаунтов скорее всего перестанет работать с 27 апреля 2022 года.

Материал изложенный в статье может быть использован даже тем, кто ранее не сталкивался с запросом данных из Google AdWords API или Google Ads API. Вам достаточно установить язык R и среду разработки RStudio, скопировать из статьи примеры кода, и подставить свои идентификаторы аккаунтов. Если вам нужна помощь в установке необходимого программного обеспечения посмотрите этот видео урок. Также начать изучения языка R можно с бесплатного курса «Язык R для пользователей Excel».

Если вы интересуетесь или планируете начать изучение языка R? вам наверняка будет полезен мой telegram и youtube канал R4marketing.

Буду рад ответить на ваши вопросы в комментариях.