Интеграция Яндекс Директа с Google Sheets: автоматизируем отчёты

Интеграция Яндекс Директа с Google Sheets заменяет еженедельный ручной экспорт: скрипт или надстройка забирает статистику через API Директа, кладёт её на лист с сырыми данными, а триггер по расписанию обновляет лист сам. Способов три — надстройка, Google Apps Script и свой скрипт. У всех трёх одно узкое место: данные Директа нужно почистить до сводной таблицы.

Пока выгрузка ручная, неделя выглядит так: кабинет, отчёт, вставка в таблицу руками. Файлы множатся, версии расходятся. К концу статьи вы выберете способ выгрузки, соберёте поток «Директ → таблица» с обновлением по расписанию и узнаете, что почистить в данных до сводной.

Что выгружаем из Директа и зачем

В таблицу выгружают показы, клики, расход и конверсии по выбранным целям в разрезе «дата × кампания». Зачем: отчёт за неделю открывается одним кликом, а не собирается руками из кабинета, и у команды остаётся одна версия цифр вместо нескольких файлов с разными числами.

Сначала решите, что значит одна строка, — это зерно таблицы: например, один день по одной кампании. От зерна зависят формулы и защита от дублей, поэтому менять его после запуска придётся вместе с ними.

Расход и клики даёт Директ, визиты и цели — Метрика. Конверсии в отчёте Директа зависят от выбранных целей и модели атрибуции, поэтому с Метрикой они могут не совпасть.

Храните данные на двух листах: сырые, в которые никто не лезет руками, и витрина со сводной таблицей и формулами. Клиентский отчёт строится поверх сырых данных — как его оформить, разобрано в отдельной статье. Если вам хватает встроенных отчётов кабинета, настройте их один раз.

Клиент в понедельник спрашивает про расход и заявки за прошлую неделю: раньше вы шли в кабинет и вставляли выгрузку в таблицу, теперь открываете лист.

Три способа интеграции Яндекс Директа с Google Sheets

Офисное рабочее место с компьютером для работы с данными. Фото: Dai Lygad · CC BY 4.0

Выгрузить Директ в таблицу можно тремя способами: надстройкой или коннектором стороннего сервиса, скриптом Google Apps Script внутри таблицы или своим скриптом вне неё. Выбирайте по четырём условиям: число кабинетов, кто поддерживает поток, кому вы доверяете токен доступа и нужна ли зачистка данных до записи.

Надстройку проверьте до подключения: какие поля она отдаёт, какие условия ставит и где хранит ваш токен. Каким бы способом вы ни пошли, первую выгрузку сверьте с кабинетом.

Мнение. Если кабинетов немного и вы готовы писать код, начинайте с Apps Script: он живёт в самой таблице, и сервер, который кто-то должен поддерживать, не нужен. Внешний скрипт оправдан, когда кабинетов много и данные нужно чистить до записи.

Как запросить отчёт через API Директа

Отчёт запрашивают у сервиса Reports в API Директа версии 5 — это не «Мастер отчётов» из кабинета. Вы отправляете POST-запрос с OAuth-токеном приложения Яндекса, у которого есть право на API Директа, и получаете таблицу в формате TSV. Токен открывает доступ к кабинету, поэтому храните его как секрет.

Порядок получения токена и доступа описан в документации Директа. Тип отчёта зависит от задачи: CAMPAIGN_PERFORMANCE_REPORT — кампании, CUSTOM_REPORT — свой набор полей, SEARCH_QUERY_PERFORMANCE_REPORT — поисковые запросы. Конверсии берут полем Conversions с параметрами Goals и AttributionModels. Пример запроса по кампаниям:

POST https://api.direct.yandex.com/json/v5/reports
Authorization: Bearer <TOKEN>
Client-Login: <LOGIN>
Accept-Language: ru
processingMode: auto
returnMoneyInMicros: false
skipReportHeader: true
skipReportSummary: true

{
  "params": {
    "SelectionCriteria": { "DateFrom": "ГГГГ-ММ-ДД", "DateTo": "ГГГГ-ММ-ДД" },
    "FieldNames": ["Date", "CampaignId", "CampaignName", "Impressions", "Clicks", "Cost"],
    "ReportName": "имя-отчёта",
    "ReportType": "CAMPAIGN_PERFORMANCE_REPORT",
    "DateRangeType": "CUSTOM_DATE",
    "Format": "TSV",
    "IncludeVAT": "YES",
    "IncludeDiscount": "NO"
  }
}

Client-Login нужен только при агентском доступе.

Режим формирования задаёт processingMode: online, offline или auto. Скрипт шлёт запрос, получает 201, ждёт время из retryIn, повторяет запрос без единой правки — имя отчёта и параметры служат ключом — и получает TSV.

Факт. Сервис Reports отвечает кодом 200, когда отчёт готов, 201 — когда он поставлен в очередь офлайн, и 202 — когда формируется; заголовок retryIn подсказывает, когда переспросить.

Как записать данные через Google Sheets API или Apps Script

Данные записывают двумя путями: снаружи через Google Sheets API по HTTP или изнутри таблицы через Apps Script. Для API включите его в проекте Google Cloud и выберите авторизацию — сервисный аккаунт или OAuth пользователя. Сервисному аккаунту откройте таблицу на редактирование по его e-mail, иначе получите ошибку доступа.

Для окна последних дней подходят update и clear; append при повторной выгрузке даёт дубли. Параметр valueInputOption задаёт разбор значений: RAW записывает как есть, USER_ENTERED — как ввод руками, с учётом локали и форматов. Числа отправляйте числами, даты — единым форматом: строка с запятой вместо числа ломает формулы.

В Apps Script запрос к Директу делает UrlFetchApp.fetch, TSV разбирает Utilities.parseCsv с табуляцией в роли разделителя, а записывает getRange().setValues() — пачкой, а не по ячейке, из-за скорости и лимитов вызовов. Токен храните в PropertiesService, не в коде и не в ячейке.

Типичная поломка на старте: сервисный аккаунт создан, а доступ к таблице не выдан — скрипт получает ошибку. Вы открыли доступ, и строки пошли.

Зачистка данных: что исправить до сводной таблицы

Перед сводной таблицей уберите из сырых данных служебные строки, приведите деньги и типы к рабочему виду и закрепите единые настройки выгрузки. Иначе сумма удвоится, формулы деления упадут, а расход не сойдётся с кабинетом. Большинство проблем лечится параметрами запроса, а не формулами в таблице.

Даты передавайте датой, числа — числом, а локаль таблицы и разделитель дробной части проверьте на тестовой выгрузке. Повторная выгрузка даёт дубли: ключ дедупликации — дата плюс CampaignId, но надёжнее перезаписывать окно, чем дописывать. Связывайте данные по CampaignId, а не по названию: названия меняют.

Конверсии зависят от целей и модели атрибуции из запроса. Если цифры расходятся с Метрикой, сначала сверьте эти настройки, а затем — путь клиента в Метрике.

Странные цифры в сводной чаще идут не от формул, а от служебных строк, микро-единиц и «--» в сырых данных: расход в миллионах — типичный след микро-единиц.

Расписание и контроль: как таблица обновляется сама

Обновление запускает триггер по времени в Apps Script или cron на сервере. Скрипт при каждом запуске перезаписывает окно последних дней, а не дописывает строки: данные дорабатываются задним числом, конверсии приходят с задержкой. Ширину окна определяете вы — она зависит от вашей модели атрибуции.

Не дописывайте новые строки, а перезаписывайте окно последних дней: данные Директа дорабатываются задним числом, и вчерашняя цифра сегодня может измениться.

Контроль держится на трёх вещах: сверке расхода и кликов за один закрытый день с кабинетом, дате последнего успешного обновления в отдельной ячейке листа и уведомлении при ошибке — чтобы о поломке вы узнавали от скрипта, а не от клиента.

Поломки повторяются: истёк токен, сменился ID кампании, превышены квота или время выполнения, таблицу переименовали или перенесли. Устаревшая дата обновления выдаёт любую из них.

Скрипт отработал ночью. Утром в ячейке стоит дата обновления, сверка одного дня с кабинетом сошлась — цифрам можно верить. Следующий шаг после отчёта — правила управления бюджетом.

Когда таблицы уже не хватает

Таблицы не хватает, когда она тормозит, кабинетов становится больше, чем вы успеваете вести, в отчёте нужны сквозные данные — заявки и продажи, а не только клики и расход, или формулы правят несколько человек. У Google Sheets есть предел размера таблицы и квоты API: порядок устанавливает Google, актуальные значения смотрите в его документации.

У каждого признака своя причина. Тормоза и рост числа кабинетов упираются в размер таблицы и квоты. Сквозные данные требуют соединять расход Директа с заявками и продажами — это уже задача для базы данных, а не для формул. Когда формулы правят несколько человек, случайная правка одной ячейки портит отчёт всем.

Следующий шаг — база данных, где лежат выгрузки, и витрина поверх неё либо специализированный сервис сквозной аналитики. Логика остаётся прежней: зерно строки, ключ дедупликации и правила зачистки вы уже определили на таблице.

Что подготовить до старта

Перед первой выгрузкой подготовьте шесть вещей: доступ и токен, зерно таблицы, список целей с моделью атрибуции, единый режим НДС и скидок, два листа и день для сверки. Каждая закрывает одну из поломок, описанных выше, и проверяется до запуска, а не после первых расхождений.

• Доступ и токен. OAuth-токен приложения Яндекса с правом на API Директа и, при агентском доступе, логин клиента для Client-Login.
• Зерно таблицы. Что значит одна строка: от этого зависят формулы и ключ дедупликации.
• Цели и модель атрибуции. Их вы передаёте в запросе, и от них зависят конверсии.
• Режим НДС и скидок. Один набор IncludeVAT и IncludeDiscount для всех выгрузок.
• Два листа. Сырые данные, которые не правят руками, и витрина со сводной таблицей.
• День для сверки. Закрытый день, расход и клики которого вы сравните с кабинетом.

Если сначала нужно понять, в каком состоянии сам кабинет, проверьте его в диагностике Директа. Типичные ошибки кампаний разобраны в чек-листе.

Источники

• Reports — сервис отчётов в API Директа — Яндекс
• API Яндекс Директа: документация — Яндекс
• Google Sheets API: методы spreadsheets.values — Google
• Google Apps Script: документация — Google

Если хотите, чтобы такой поток собрали под ваши кабинеты вместе со сквозной аналитикой, оставьте заявку — разберём, какой из трёх способов вам подходит.