Google Ads API открывает широкие возможности для автоматизации и глубокого анализа рекламных кампаний, выходя далеко за рамки стандартного веб-интерфейса. Создание кастомизированных отчетов — одна из ключевых задач, которую эффективно решает API.
Что такое Google Ads API и зачем он нужен?
Google Ads API — это программный интерфейс, позволяющий разработчикам взаимодействовать непосредственно с данными аккаунтов Google Ads. Он предоставляет доступ к функционалу Google Рекламы, включая управление кампаниями, группами объявлений, ставками, а также, что особенно важно для нас, — получение детализированной статистики.
API незаменим, когда требуется:
Создавать сложные, нестандартные отчеты с множеством метрик и сегментов.
Автоматизировать рутинные процессы сбора данных.
Интегрировать данные Google Ads с внутренними BI-системами, CRM или базами данных.
Обрабатывать большие объемы данных по множеству аккаунтов.
Преимущества использования API для создания отчетов
Использование API для отчетности предоставляет ряд существенных преимуществ:
Гибкость и кастомизация: Возможность формировать отчеты с любым набором полей, сегментов и фильтров, недоступных в стандартном интерфейсе.
Автоматизация: Настройка регулярного сбора данных без ручного вмешательства, что экономит время и снижает риск человеческой ошибки.
Интеграция: Легкость передачи данных в другие системы аналитики и хранения (например, Google BigQuery, Tableau, Power BI).
Масштабируемость: Эффективная работа с большими объемами данных, что критично для крупных рекламодателей и агентств.
Глубина данных: Доступ к более гранулированным данным и историческим срезам.
Необходимые условия и предварительная настройка
Перед тем как приступить к созданию отчетов через API, убедитесь, что выполнены следующие условия:
Активный аккаунт Google Ads: У вас должен быть действующий рекламный аккаунт.
Базовые знания программирования: Понимание основ выбранного языка программирования (Python, Java, PHP и др.) и работы с API.
Управляющий аккаунт (MCC): Рекомендуется для работы с несколькими клиентскими аккаунтами. При этом запросы к API будут выполняться от имени MCC.
Уровень доступа к API: Необходимо получить токен разработчика и соответствующий уровень доступа (Basic или Standard). Для большинства задач по отчетности достаточно уровня Basic, но при превышении лимитов потребуется подать заявку на Standard Access.
Получение учетных данных и настройка окружения
Для взаимодействия с Google Ads API необходимы учетные данные, которые позволят вашему приложению аутентифицироваться и авторизоваться.
Создание проекта в Google Cloud Console
Перейдите в Google Cloud Console.
Создайте новый проект или выберите существующий.
Убедитесь, что для проекта включен биллинг (это требование Google Cloud, даже если сам Google Ads API используется бесплатно в рамках квот).
Включение Google Ads API
В Google Cloud Console перейдите в раздел "APIs & Services" -> "Library".
Найдите "Google Ads API" и включите его для вашего проекта.
Создание учетных данных (OAuth 2.0)
Google Ads API использует протокол OAuth 2.0 для аутентификации и авторизации.
В Google Cloud Console перейдите в "APIs & Services" -> "Credentials".
Нажмите "Create credentials" и выберите "OAuth client ID".
Выберите тип приложения. Для скриптов, запускаемых локально или на сервере для автоматизации, обычно выбирают "Desktop app" или "Web application" (если есть серверная часть с редиректом URI).
После создания вы получите Client ID и Client Secret. Сохраните их в надежном месте.
Для автоматизированных скриптов вам потребуется получить Refresh Token. Это делается путем прохождения процесса OAuth 2.0 один раз. Клиентские библиотеки обычно предоставляют утилиты для этого.
Установка клиентской библиотеки Google Ads API (Python, Java, PHP и др.)
Google предоставляет официальные клиентские библиотеки для нескольких популярных языков программирования, которые значительно упрощают работу с API.
Для Python:
pip install google-adsПосле установки библиотеки необходимо настроить конфигурационный файл (обычно google-ads.yaml), указав в нем developer_token, client_id, client_secret, refresh_token и login_customer_id (ID управляющего аккаунта, если используется, иначе ID вашего клиентского аккаунта).
Пример структуры google-ads.yaml:
developer_token: YOUR_DEVELOPER_TOKEN
client_id: YOUR_CLIENT_ID
client_secret: YOUR_CLIENT_SECRET
refresh_token: YOUR_REFRESH_TOKEN
login_customer_id: YOUR_LOGIN_CUSTOMER_ID # MCC ID, if applicable
# use_proto_plus: True # Рекомендуется для удобства работы с объектамиФормирование запроса GAQL (Google Ads Query Language)
GAQL — это мощный язык запросов, схожий с SQL, используемый для получения данных из Google Ads API. Понимание GAQL является ключом к эффективной отчетности.
Основы GAQL: синтаксис и структура запроса
Базовая структура запроса GAQL выглядит так:
SELECT
field1, field2, metrics.field3, segments.field4
FROM
resource_name
WHERE
condition1 AND condition2
ORDER BY
field1 DESC
LIMIT
100
DURING
YYYYMMDD,YYYYMMDD -- или LAST_30_DAYS, YESTERDAY и т.д.SELECT: Определяет поля (атрибуты ресурса, сегменты, метрики), которые вы хотите получить.
FROM: Указывает основной ресурс, из которого извлекаются данные (например, campaign, ad_group, keyword_view).
WHERE: Фильтрует результаты на основе условий.
ORDER BY: Сортирует результаты.
LIMIT: Ограничивает количество возвращаемых строк.
DURING: Задает период времени для отчета.
Выбор необходимых полей для отчета (Metrics & Segments)
Metrics: Количественные показатели эффективности (например, metrics.clicks, metrics.impressions, metrics.cost_micros, metrics.conversions). Метрики всегда начинаются с префикса metrics..
Segments: Атрибуты, по которым можно группировать данные метрик (например, segments.date, segments.device, segments.campaign). Сегменты начинаются с префикса segments..
Resource Fields: Атрибуты самого ресурса (например, campaign.id, campaign.name, ad_group.status).
Полный список доступных полей для каждого ресурса можно найти в официальной документации Google Ads API.
Фильтрация данных по кампаниям, датам и другим параметрам (WHERE clause)
Клауза WHERE позволяет точно указать, какие данные включать в отчет.
Фильтрация по названию кампании: campaign.name LIKE '%Brand%'
Фильтрация по статусу: campaign.status = 'ENABLED'
Фильтрация по ID: campaign.id IN (123456789, 987654321)
Комбинированные условия: campaign.status = 'ENABLED' AND metrics.impressions > 100
Клауза DURING используется для фильтрации по дате:
DURING LAST_7_DAYS
DURING YESTERDAY
DURING THIS_MONTH
DURING 20230101,20231231 (для произвольного диапазона)
Примеры GAQL запросов для популярных отчетов по кампаниям
Общая эффективность кампаний за последние 30 дней:
SELECT
campaign.id,
campaign.name,
metrics.impressions,
metrics.clicks,
metrics.cost_micros,
metrics.conversions,
metrics.ctr,
metrics.average_cpc
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
AND campaign.status = 'ENABLED'
ORDER BY metrics.cost_micros DESCЭффективность кампаний по дням и устройствам за вчерашний день:
SELECT
segments.date,
segments.device,
campaign.name,
metrics.impressions,
metrics.clicks,
metrics.cost_micros
FROM campaign
WHERE segments.date DURING YESTERDAY
ORDER BY segments.date, campaign.nameСуммарные показатели по кампаниям, содержащим ‘Search’ в названии, за текущий месяц:
SELECT
campaign.name,
SUM(metrics.impressions) AS total_impressions,
SUM(metrics.clicks) AS total_clicks,
SUM(metrics.cost_micros) AS total_cost
FROM campaign
WHERE campaign.name LIKE '%Search%'
AND segments.date DURING THIS_MONTH
GROUP BY campaign.nameПримечание: агрегатные функции типа SUM() не поддерживаются напрямую в GAQL в SELECT. Агрегацию нужно выполнять на стороне клиента после получения детализированных данных, либо использовать специальные отчеты типа campaign_budget или campaign_criterion_simulation для некоторых типов агрегированных данных.
Для получения агрегированных данных напрямую, вы обычно выбираете метрики без агрегации и суммируете их уже после получения ответа от API. GAQL возвращает строки данных, а не агрегированные результаты как SQL GROUP BY. Корректный запрос для получения данных для последующей агрегации:
SELECT
campaign.name,
metrics.impressions,
metrics.clicks,
metrics.cost_micros
FROM campaign
WHERE campaign.name LIKE '%Search%'
AND segments.date DURING THIS_MONTHОбработка и визуализация данных отчета
После формирования и выполнения запроса GAQL вы получаете данные, которые необходимо обработать и, возможно, визуализировать.
Получение данных из API (Streaming vs. Paging)
Существует два основных способа получения данных:
Streaming (GoogleAdsService.SearchStream): Рекомендуется для больших отчетов. Данные передаются потоком по мере их доступности. Это более эффективно с точки зрения использования памяти и позволяет обрабатывать очень большие наборы данных.
Paging (GoogleAdsService.Search): Данные возвращаются страницами. Подходит для небольших запросов. Необходимо управлять page_size и page_token для получения всех страниц результатов.
Пример на Python с использованием SearchStream и pandas:
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException
import pandas as pd
from typing import List, Dict, Any
# ID вашего управляющего или клиентского аккаунта
CUSTOMER_ID = "YOUR_CUSTOMER_ID"
def get_campaign_report(client: GoogleAdsClient, customer_id: str) -> pd.DataFrame:
"""
Получает отчет по кампаниям и возвращает его в виде pandas DataFrame.
Args:
client: Инициализированный клиент GoogleAdsClient.
customer_id: ID клиентского аккаунта Google Ads.
Returns:
pandas DataFrame с данными отчета.
"""
ga_service = client.get_service("GoogleAdsService")
query = """
SELECT
campaign.id,
campaign.name,
campaign.status,
segments.date,
metrics.impressions,
metrics.clicks,
metrics.cost_micros,
metrics.conversions
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
AND campaign.advertising_channel_type = 'SEARCH'
ORDER BY segments.date DESC, campaign.id
"""
stream = ga_service.search_stream(customer_id=customer_id, query=query)
report_data: List[Dict[str, Any]] = []
try:
for batch in stream:
for row in batch.results:
campaign = row.campaign
segments = row.segments
metrics = row.metrics
report_row = {
"date": segments.date,
"campaign_id": campaign.id,
"campaign_name": campaign.name,
"campaign_status": campaign.status.name, # Enum value to string
"impressions": metrics.impressions,
"clicks": metrics.clicks,
"cost": metrics.cost_micros / 1_000_000, # Конвертация из микро в обычные единицы
"conversions": metrics.conversions
}
report_data.append(report_row)
except GoogleAdsException as ex:
print(
f'Request with ID "{ex.request_id}" failed with status '
f'"{ex.error.code().name}" and includes the following errors:'
)
for error in ex.failure.errors:
print(f'\tError with message "{error.message}".')
if error.location:
for field_path_element in error.location.field_path_elements:
print(f'\t\tOn field: {field_path_element.field_name}')
return pd.DataFrame() # Возвращаем пустой DataFrame в случае ошибки
return pd.DataFrame(report_data)
if __name__ == "__main__":
# Убедитесь, что у вас есть файл google-ads.yaml или сконфигурируйте клиент программно
# googleads_client = GoogleAdsClient.load_from_storage(version="v17") # Укажите актуальную версию API
# Для примера, создадим фиктивный клиент, если нет конфигурационного файла
# В реальном приложении используйте load_from_storage()
try:
googleads_client = GoogleAdsClient.load_from_storage(version="v17")
except FileNotFoundError:
print("Файл google-ads.yaml не найден. Запустите generate_refresh_token.py или создайте его вручную.")
# Для демонстрации можно создать заглушку, но она не будет работать без реальных данных
# Это лишь для того, чтобы код не падал при отсутствии файла во время статического анализа
class MockGoogleAdsClient:
def get_service(self, service_name: str) -> Any:
class MockGaService:
def search_stream(self, customer_id: str, query: str) -> List[Any]:
print(f"Mock search_stream called for customer_id: {customer_id} with query: {query}")
return [] # Возвращаем пустой список для имитации ответа
return MockGaService()
googleads_client = MockGoogleAdsClient()
CUSTOMER_ID = "000-000-0000" # Dummy ID
if CUSTOMER_ID != "YOUR_CUSTOMER_ID" and CUSTOMER_ID != "000-000-0000":
df_report = get_campaign_report(googleads_client, CUSTOMER_ID)
if not df_report.empty:
print("Отчет по кампаниям:")
print(df_report.head())
# Сохранение в CSV
df_report.to_csv("campaign_performance_report.csv", index=False)
print("\nОтчет сохранен в campaign_performance_report.csv")
else:
print("Не удалось получить данные для отчета.")
else:
print("Пожалуйста, укажите ваш CUSTOMER_ID.")Парсинг и преобразование JSON/Protocol Buffer ответов
Клиентские библиотеки Google Ads API абстрагируют работу с форматом Protocol Buffers (protobuf), предоставляя объекты, с которыми удобно работать. Если вы не используете клиентскую библиотеку и делаете прямые HTTP запросы, вам придется самостоятельно парсить JSON или protobuf ответы.
При использовании клиентской библиотеки (как в примере выше), доступ к данным осуществляется через атрибуты объектов ответа (например, row.campaign.name, row.metrics.clicks). Важно преобразовывать некоторые значения, например, cost_micros в стандартную валюту (делением на 1,000,000) или значения enum в их строковые представления (например, campaign.status.name).
Сохранение данных в базу данных или файл (CSV, Excel)
Полученные данные часто требуется сохранить для дальнейшего анализа или архивации.
CSV/Excel: Легко реализуется с помощью библиотек типа pandas в Python (как показано в примере) или аналогичных в других языках.
Базы данных (SQL/NoSQL): Данные можно загружать в PostgreSQL, MySQL, ClickHouse, Google BigQuery и т.д. Это предпочтительный вариант для больших объемов данных и сложных аналитических запросов.
Визуализация данных с использованием графиков и диаграмм (Matplotlib, Tableau, Google Data Studio)
Визуализация помогает лучше понять данные и выявить тенденции.
Python-библиотеки: Matplotlib, Seaborn, Plotly для создания графиков непосредственно в коде.
BI-инструменты: Tableau, Microsoft Power BI, Qlik Sense. Эти инструменты могут подключаться к вашим сохраненным данным (CSV, базы данных) для создания интерактивных дашбордов.
Google Data Studio (Looker Studio): Отличный бесплатный инструмент для визуализации данных Google, включая Google Ads. Можно настроить коннектор к Google BigQuery, куда вы предварительно загрузили данные из API, или загружать данные из Google Sheets/CSV.
Оптимизация и автоматизация отчетности
Создание эффективной системы отчетности включает не только получение данных, но и ее оптимизацию и автоматизацию.
Кэширование данных для повышения производительности
Частые запросы одних и тех же исторических данных могут привести к ненужному расходу квот API и увеличению времени ответа. Рассмотрите возможность кэширования результатов запросов, особенно для данных, которые не меняются или меняются редко (например, отчеты за прошлые периоды). Кэш можно хранить в файловой системе, Redis, Memcached или базе данных.
Автоматическое планирование отчетов (Cron, Task Scheduler)
Автоматизируйте запуск скриптов для сбора отчетов с помощью системных планировщиков:
Cron (Linux, macOS)
Task Scheduler (Windows)
Облачные планировщики: Google Cloud Scheduler, AWS EventBridge (CloudWatch Events), Azure Logic Apps.
Это позволит регулярно обновлять данные без вашего участия.
Обработка ошибок и логирование
Надежные скрипты должны включать:
Обработку исключений: try-except блоки для перехвата ошибок API (например, GoogleAdsException), сетевых проблем, ошибок данных.
Логирование: Запись информации о выполнении скрипта, выполненных запросах, полученных ошибках и объеме обработанных данных. Используйте стандартные библиотеки логирования (например, logging в Python).
Повторные попытки (Retries): Реализация механизма повторных попыток с экспоненциальной задержкой для временных ошибок API (например, RATE_EXCEEDED).
Лучшие практики и советы по созданию эффективных отчетов
Запрашивайте только необходимые поля: Это уменьшает объем передаваемых данных, снижает нагрузку на API и экономит квоты.
Используйте конкретные диапазоны дат: Избегайте запросов DURING ALL_TIME, если это не абсолютно необходимо.
Учитывайте лимиты и квоты API: Ознакомьтесь с документацией по квотам и оптимизируйте запросы, чтобы не превышать их. Используйте токен разработчика с уровнем доступа Standard для больших объемов операций.
Используйте login-customer-id для MCC: Если работаете с несколькими аккаунтами через MCC, указывайте login-customer-id в конфигурации клиента. Запросы к отдельным клиентским аккаунтам (customer_id в методе search_stream или search) будут выполняться в контексте этого MCC.
Тестируйте запросы с validate_only=True: Для проверки корректности GAQL запроса без выполнения и расхода квот можно использовать параметр validate_only=True при вызове GoogleAdsService.search (не для search_stream).
Версионирование API: Google Ads API регулярно обновляется. Следите за выходом новых версий и планируйте миграцию, так как старые версии со временем перестают поддерживаться.
Асинхронные запросы: Для одновременного получения данных из нескольких аккаунтов или выполнения нескольких независимых запросов рассмотрите использование асинхронных подходов (например, asyncio в Python) для повышения общей производительности.
Создание отчетов с помощью Google Ads API — это мощный инструмент, который, при правильном подходе, может значительно повысить эффективность анализа и управления вашими рекламными кампаниями.