Миграция с 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

Работа практически с любым API начинается с авторизации. Здесь используется функционал пакета gargle. В связи с чем, процесс авторизации будет хорошо знаком пользователям таких пакетов как googlesheets4, googledrive, bigrquery, googleAnalyticsR.

Самый простой способ пройти авторизацию — использовать функцию 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 Analytics в 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.

Бывшие в Google AdWords типы отчётов, в Google Ads стали ресурсами. Ниже — таблица сопоставления из официальной справки:

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

Ниже приведу пример запроса отчёта по эффективности рекламных кампаний с одним и тем же набором полей, с помощью пакета 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.

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