Сервер авторизован в нужном аккаунте, выполняет проверенное чтение и имеет правила контроля повторов, ошибок и будущих изменений.
Что подготовить перед началом
- Опишите конкретную операцию, владельца интеграции, список аккаунтов и требуемые поля; начните с чтения кампаний или отчёта расходов.
- Подготовьте серверную среду, хранилище секретов, доступ владельца рекламного аккаунта и отдельную тестовую конфигурацию.
- Для Google Ads подготовьте manager account, developer token и OAuth; для Директа зарегистрируйте приложение OAuth и пройдите процедуру доступа к API.
Учебная схема процесса; не скриншот рекламного кабинета.
01Определите первый безопасный сценарий
Для первого подключения выберите конкретный отчёт или список объектов. Запишите аккаунт, даты, часовой пояс, валюту и ожидаемый результат. API Директа, Метрики и AppMetrica решают разные задачи; доступ к одному продукту не даёт автоматически административный доступ к другому. Не начинайте с массового изменения бюджета, если ещё не проверено чтение правильного клиента.
- Выберите список кампаний либо ежедневный отчёт расходов.
- Запишите customer_id Google Ads или client-login Директа, проверив его с владельцем.
- Составьте контрольный набор нескольких кампаний для сравнения ответа с интерфейсом.
Первый скрипт получает ID, имя и состояние кампаний, сохраняя рекламные настройки.
Задача имеет проверяемый выход и известный рекламный аккаунт.
02Подготовьте developer token Google Ads
Токен разработчика относится к приложению и уровню доступа API; OAuth относится к правам пользователя или поддерживаемой схемы авторизации. Это разные составляющие. Пройдите заявку/доступ по текущей документации и проверьте ограничения тестового и рабочего режима. ID управляющего аккаунта и ID клиента также отличаются.
- В аккаунте менеджера откройте API Center и оформите developer token.
- Проверьте статус доступа и разрешённые аккаунты среды теста.
- Запишите клиентский customer_id без дефисов; login_customer_id укажите, когда запрос проходит через менеджера.
developer token получен у менеджера, а данные запрашиваются у конкретного рекламодателя.
Developer token и customer_id не перепутаны; уровень доступа допускает выбранный сценарий.
03Настройте OAuth Google
Создайте подходящий OAuth client и согласованный redirect URI. Разрешение Google Ads API использует scope https://www.googleapis.com/auth/adwords; доступ пользователя к рекламному аккаунту проверяется отдельно. Для серверного приложения получайте и храните refresh token по документированному OAuth-процессу; не копируйте его в код браузера. Проверяйте состояние приложения и условия тестовых пользователей.
- Настройте согласие и клиент OAuth по типу приложения.
- Авторизуйте пользователя с правами нужного аккаунта; проверьте возвращённые разрешения.
- Сохраните client secret и refresh token в серверном хранилище; обеспечьте обновление access token через официальную библиотеку.
Пользователь дал OAuth-разрешение, но не имеет доступа к customer_id: исправьте права, а не повторяйте запрос бесконечно.
Авторизация работает под нужной учётной записью, секреты не попадают в интерфейс сайта.
04Выполните первый Google Ads запрос
Загрузите параметры доступа из переменных окружения либо защищённого файла вне публичного сайта. Для первого чтения используйте короткий GAQL-запрос с ограниченным числом результатов. Версию API и клиентской библиотеки сверяйте с актуальной документацией: фиксировать случайную устаревшую версию из статьи не следует. При финансовом отчёте учитывайте, что cost_micros требует деления на миллион.
- Установите официальную библиотеку поддерживаемой версии.
- В серверной среде задайте GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_REFRESH_TOKEN, GOOGLE_ADS_USE_PROTO_PLUS=true; при работе через менеджера также GOOGLE_ADS_LOGIN_CUSTOMER_ID.
- Выполните чтение, сравните ID и состояния с кабинетом, запишите request ID ошибок без секретов.
Пример Python читает список кампаний; load_from_env ожидает корректную серверную конфигурацию официальной библиотеки.
import os
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()
service = client.get_service('GoogleAdsService')
query = 'SELECT campaign.id, campaign.name, campaign.status FROM campaign LIMIT 10'
for row in service.search(customer_id=os.environ['ADS_CUSTOMER_ID'], query=query):
print(row.campaign.id, row.campaign.name, row.campaign.status)Замените демонстрационные идентификаторы на значения своего проекта.Ответ содержит ожидаемые кампании выбранного клиента, а не аккаунт менеджера.
05Оформите доступ Директа
Зарегистрируйте приложение с нужным разрешением Директа, затем подайте заявку на доступ по документации. OAuth-токен выдаётся пользователем с соответствующими правами. Для агентской работы заголовок Client-Login выбирает рекламодателя; он не заменяет доступ пользователя к клиенту. Используйте песочницу для операций, которым не нужны рабочие данные.
- Зарегистрируйте приложение и сохраните Client ID/секрет в серверной конфигурации.
- Получите пользовательский OAuth-токен через документированный поток и проверьте доступ API.
- Запишите допустимые клиентские логины и отдельную конфигурацию песочницы/продакшена.
Один агентский токен может работать только с доступными клиентами; указание чужого логина не создаёт права.
Авторизация и выбранный рекламодатель проверены до выполнения рабочих операций.
06Проверьте campaigns.get Директа
Передавайте Authorization: Bearer и JSON тела, а не токен в URL. Код ниже выполняет чтение с явным клиентским логином из серверной среды. Транспортный HTTP-успех не гарантирует успех операции: API может вернуть объект error. Для ЕПК специальные возможности могут использовать v501; выбирайте адрес по документации конкретной операции, не заменяйте все URL вслепую.
- Сначала вызовите get с минимальными общими FieldNames.
- Проверьте result, error, request ID и список объектов.
- Обработайте пагинацию и ограничения выбранного метода; сопоставьте несколько ID с интерфейсом.
Campaigns.get возвращает существующие имена и состояния; токен не выводится в журнал.
import os, requests
response = requests.post(
'https://api.direct.yandex.com/json/v5/campaigns',
headers={
'Authorization': 'Bearer ' + os.environ['YANDEX_DIRECT_TOKEN'],
'Client-Login': os.environ['YANDEX_DIRECT_CLIENT_LOGIN'],
'Accept-Language': 'ru'
},
json={'method': 'get', 'params': {
'SelectionCriteria': {},
'FieldNames': ['Id', 'Name', 'State'],
'Page': {'Limit': 100, 'Offset': 0}
}}, timeout=30
)
response.raise_for_status()
data = response.json()
if 'error' in data:
raise RuntimeError('Direct API error: ' + str(data['error'].get('error_code')))
for campaign in data['result']['Campaigns']:
print(campaign['Id'], campaign['Name'], campaign['State'])Замените демонстрационные идентификаторы на значения своего проекта.Чтение успешное, клиент правильный, ответ ошибки не принят за пустой рекламный аккаунт.
07Добавьте контроль интеграции
Храните секреты в менеджере секретов или защищённых переменных и закрывайте их в логах. Разделяйте запросы чтения и изменения. Повторы чтения с backoff допустимы по документированным ошибкам; перед повтором изменения проверяйте, не применилось ли оно уже. Для будущего управления бюджетом выводите конкретное «до/после», лимит изменения и список ID.
- Добавьте таймауты, обработку квот/лимитов и ограниченное число повторов.
- Логируйте метод, аккаунт, объект, результат и request ID без Authorization/refresh token.
- Для изменений используйте тестовые аккаунты, песочницу или validate_only там, где поддерживается; затем проверяйте реальные результаты чтением.
После сетевого обрыва бюджет мог измениться: сначала перечитайте объект, затем решайте, нужен ли повтор.
Интеграция управляет только разрешёнными аккаунтами, позволяет объяснить каждый результат и остановить повторяющуюся ошибку.
Пример для бизнеса
Автоматический отчёт о расходах — хороший первый сценарий. Автоматическое увеличение бюджета требует дополнительных правил и проверки экономики.
Частые ошибки
- Токен встроен в код сайта.
- Повтор запроса повторяет нежелательное изменение.
- Автоматизация управляет не тем клиентским аккаунтом.
Вопросы по настройке
Можно ли хранить токен в JavaScript сайта?
Нет: посетители получают этот код. Авторизацию и API-запросы выполняйте на сервере, секреты храните вне публичных файлов и журналов.
Песочница показывает реальные расходы?
Тестовая среда предназначена для проверки операций и не заменяет рабочий финансовый отчёт. Сначала проверьте запросы тестом, затем выполните разрешённое чтение рабочего аккаунта.
Официальные источники
- Google Ads API: начало работы ↗
- Developer token · Google ↗
- OAuth Google Ads API ↗
- Начало работы с Директ API · Яндекс ↗
- OAuth-токен Директа · Яндекс ↗
- campaigns.get · Директ API ↗
Материал написан своими словами по указанным справкам. Примеры и рекомендации so-agency адаптированы к задачам бизнеса; доступность функций и интерфейс могут отличаться.
Нужна помощь с настройкой?
Опишите сайт, платформу и проблему. Обсудим конкретный состав работ.