Простыми словами
API позволяет программе читать или изменять рекламный кабинет без ручного открытия каждой страницы. Начинайте с чтения отчёта: ошибки массового редактирования могут повлиять на расход.
Термины простыми словами · 5
- API
- Правила обмена данными между программой и рекламной платформой.
- OAuth
- Предоставление разрешённого доступа без передачи пароля пользователя программе.
- Developer token
- Отдельное разрешение разработчика Google Ads API; оно не заменяет авторизацию клиента.
- URL
- Полный адрес страницы или файла, например https://example.com/catalog. При проверке ссылки важны также путь и параметры после знака вопроса.
- ID
- Идентификатор — код конкретного объекта. Например, номер счётчика или код товара. При настройке нужно брать ID нужного объекта, а не любой похожий номер.
Сервер авторизован в нужном аккаунте, выполняет проверенное чтение и имеет правила контроля повторов, ошибок и будущих изменений.
Что подготовить перед началом
- Опишите конкретную операцию, владельца интеграции, список аккаунтов и требуемые поля; начните с чтения кампаний или отчёта расходов.
- Подготовьте серверную среду, хранилище секретов, доступ владельца рекламного аккаунта и отдельную тестовую конфигурацию.
- Для Google Ads подготовьте manager account, developer token и OAuth; для Директа зарегистрируйте приложение OAuth и пройдите процедуру доступа к API.
01Определите первый безопасный сценарий
Сначала автоматизируйте чтение, которое можно сверить вручную. Массовое изменение ставок и публикация объявлений требуют отдельного контроля прав и пределов. API нужен для конкретной рутины, а не вместо любого интерфейса.
- Выберите один аккаунт и один запрос: расходы за закрытый день без изменений.
- Опишите проверку результата: аккаунт, дата, валюта и итог должны совпасть с кабинетом.
- Храните секреты на сервере, ограничьте доступ и добавьте журнал ошибок и повторов.
Первый скрипт читает расходы одной компании. Он не удаляет кампании и не меняет ставки.
Результат чтения сверен с кабинетом, а у интеграции есть ответственный и понятная область доступа.
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 там, где поддерживается; затем проверяйте реальные результаты чтением.
После сетевого обрыва бюджет мог измениться: сначала перечитайте объект, затем решайте, нужен ли повтор.
Интеграция управляет только разрешёнными аккаунтами, позволяет объяснить каждый результат и остановить повторяющуюся ошибку.
Автоматический отчёт по расходам
Учебный пример: цифры и названия показывают способ работы, а не результаты клиента.
Доступ только к нужной компании
Расходы за выбранный день
Аккаунт, валюта и итог
Ошибка записана, повтор ограничен
Схема работы интеграции. Секретные токены не публикуют в примерах.
Авторская учебная схема SOAgency- Запишите задачу: только прочитать расходы выбранного аккаунта за закрытый день.
- Получите разрешённый доступ API и храните токены на сервере, не в публичной странице.
- Сделайте один запрос чтения и сравните аккаунт, даты, валюту и сумму с кабинетом.
- Добавьте журнал ошибок и лимиты повторов, прежде чем автоматизировать расписание.
Программа возвращает сверенный отчёт нужной компании. Никакие ставки и объявления при учебной проверке не меняются.
Выполните и проверьте
Отмечайте шаг после проверки результата. Отметки действуют до перезагрузки страницы; они не подтверждают, что настройка выполнена правильно.
Чек-лист по шагам · 7
Рекламные API: когда нужны и как подключать безопасно
- Выберите один аккаунт и один запрос: расходы за закрытый день без изменений.
- Опишите проверку результата: аккаунт, дата, валюта и итог должны совпасть с кабинетом.
- Храните секреты на сервере, ограничьте доступ и добавьте журнал ошибок и повторов.
Проверка: Результат чтения сверен с кабинетом, а у интеграции есть ответственный и понятная область доступа.
- В аккаунте менеджера откройте API Center и оформите developer token.
- Проверьте статус доступа и разрешённые аккаунты среды теста.
- Запишите клиентский customer_id без дефисов; login_customer_id укажите, когда запрос проходит через менеджера.
Проверка: Developer token и customer_id не перепутаны; уровень доступа допускает выбранный сценарий.
- Настройте согласие и клиент OAuth по типу приложения.
- Авторизуйте пользователя с правами нужного аккаунта; проверьте возвращённые разрешения.
- Сохраните client secret и refresh token в серверном хранилище; обеспечьте обновление access token через официальную библиотеку.
Проверка: Авторизация работает под нужной учётной записью, секреты не попадают в интерфейс сайта.
- Установите официальную библиотеку поддерживаемой версии.
- В серверной среде задайте 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 ошибок без секретов.
Проверка: Ответ содержит ожидаемые кампании выбранного клиента, а не аккаунт менеджера.
- Зарегистрируйте приложение и сохраните Client ID/секрет в серверной конфигурации.
- Получите пользовательский OAuth-токен через документированный поток и проверьте доступ API.
- Запишите допустимые клиентские логины и отдельную конфигурацию песочницы/продакшена.
Проверка: Авторизация и выбранный рекламодатель проверены до выполнения рабочих операций.
- Сначала вызовите get с минимальными общими FieldNames.
- Проверьте result, error, request ID и список объектов.
- Обработайте пагинацию и ограничения выбранного метода; сопоставьте несколько ID с интерфейсом.
Проверка: Чтение успешное, клиент правильный, ответ ошибки не принят за пустой рекламный аккаунт.
- Добавьте таймауты, обработку квот/лимитов и ограниченное число повторов.
- Логируйте метод, аккаунт, объект, результат и request ID без Authorization/refresh token.
- Для изменений используйте тестовые аккаунты, песочницу или validate_only там, где поддерживается; затем проверяйте реальные результаты чтением.
Проверка: Интеграция управляет только разрешёнными аккаунтами, позволяет объяснить каждый результат и остановить повторяющуюся ошибку.
TSV открывается в таблицах с разделителем «табуляция». В файле сохранены шаги, действия и критерии проверки этой статьи.
Частые ошибки
- Токен встроен в код сайта.
- Повтор запроса повторяет нежелательное изменение.
- Автоматизация управляет не тем клиентским аккаунтом.
Вопросы и ответы
Можно ли хранить токен в JavaScript сайта?
Нет: посетители получают этот код. Авторизацию и API-запросы выполняйте на сервере, секреты храните вне публичных файлов и журналов.
Песочница показывает реальные расходы?
Тестовая среда предназначена для проверки операций и не заменяет рабочий финансовый отчёт. Сначала проверьте запросы тестом, затем выполните разрешённое чтение рабочего аккаунта.
С какой операции начать подключение рекламного API?
Начните с чтения списка кампаний или небольшого отчёта. Сверьте аккаунт, ID кампаний, период, валюту и часовой пояс с интерфейсом. Изменение бюджетов добавляйте отдельно, когда чтение и права доступа уже проверены.
Официальные источники
- Google Ads API: начало работы ↗
- Developer token · Google ↗
- OAuth Google Ads API ↗
- Начало работы с Директ API · Яндекс ↗
- OAuth-токен Директа · Яндекс ↗
- campaigns.get · Директ API ↗
Материал написан своими словами по указанным справкам. Примеры и рекомендации so-agency адаптированы к задачам бизнеса; доступность функций и интерфейс могут отличаться.
Связанные инструкции
Автоматизированные правила Google Ads: как убрать рутину и сохранить контроль
Правило выполняет заранее описанное действие: присылает уведомление, приостанавливает выбранную рекламу или меняет доступный параметр. Разбираем создание, условия, предварительный просмотр и журнал, чтобы автоматизация помогала работе, а не управляла всем аккаунтом вслепую.
Читать инструкцию ↗Google AdsGoogle Ads Editor: массовые изменения, импорт CSV и проверка перед публикацией
Если нужно обновить много объявлений или ключевых слов, настольный Editor помогает подготовить изменения в одном месте. Показываем, как получить актуальные данные, сохранить исходное состояние, импортировать таблицу и опубликовать только проверенные кампании.
Читать инструкцию ↗Аналитика / UTMЗаявки в CRM, Google Sheets и Telegram: сайт и лид-формы без потерь
Свяжите сайт и рекламные лид-формы с рабочей очередью заявок. Разбираем Tilda → Google Sheets, Google Ads → CRM и формы Meta → CRM или таблицу через реальный коннектор; проверяем поля, доставку и повторы.
Читать инструкцию ↗