Автоматизация выгрузки данных по рекламным кампаниям Яндекс Директа с API Яндекс Метрики

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

В этой статье я расскажу, как автоматизировать выгрузку данных по рекламным кампаниям Яндекс Директа с помощью API Яндекс Метрики. На первый взгляд, задача может показаться довольно сложной, но с правильным подходом и инструментами она становится вполне решаемой. Мы разберем, как можно справиться с ней, имея минимальные навыки программирования и код на языке JavaScript, сгенерированный и оптимизированный ИИ-чатом chat.deepseek.com под мой запрос.

Доступы

Прежде всего, убедитесь, что у вас есть необходимые доступы к счетчику Яндекс Метрики и отчету Директ, расходы.

В Яндекс Метрике ваш логин должен иметь доступ к счетчику с уровнем прав Просмотр или выше. Данные из отчета Директ, расходы можно выгрузить, если вы являетесь владельцем кампаний, имеете доступ управляющего аккаунта, являетесь представителем владельца или представителем агентства.

Создание приложения

Далее необходимо создать приложение для работы с API. Для этого:

• перейдите по ссылке: https://oauth.yandex.ru/client/new
• введите название вашего приложения:

• при желании загрузите иконку. Это необязательный шаг, но он поможет сделать приложение более узнаваемым
• в качестве платформы выберите Веб-сервисы. Затем укажите URL для отладки. Чтобы быстро заполнить поле, кликните на него и выберите опцию Подставить URL для отладки:

Добавьте необходимые доступы для вашего приложения. Для работы с API отчетов достаточно предоставить доступ metrika:read. Этот доступ позволяет читать данные из Яндекс Метрики. Если вам нужно управлять счетчиками (например, создавать или редактировать их), потребуется доступ metrika:write. Однако для выгрузки отчетов он не обязателен:

Укажите почту для связи. Это может быть ваш личный или корпоративный email, на который будут приходить уведомления, связанные с приложением. После заполнения всех полей нажмите кнопку “Создать приложение”. Теперь ваше приложение будет зарегистрировано, и вы сможете использовать его для работы с API:

Готово! На следующем шаге вы увидите данные о созданном приложении. Среди них будет ClientID — уникальный идентификатор вашего приложения. Он понадобится для дальнейшей работы с API, например, для получения OAuth-токена:

Перейдите по ссылке ниже, подставив в параметр запроса client_id идентификатор вашего приложения — ClientID: https://oauth.yandex.ru/authorize/?response_type=token&client_id=Ваш_ClientID

Пример:

После перехода по ссылке вам будет предложено предоставить доступ приложению к данным вашего аккаунта:

Вы получите OAuth-токен. Этот токен необходим для работы с API. Обязательно сохраните его в надежном месте и никому не передавайте, так как он предоставляет доступ к вашим данным. Пример ниже используется только для демонстрации и не является активным на момент публикации материала:

Apps Script

Apps Script — это облачная платформа для разработки скриптов и автоматизации задач, созданная Google. Она позволяет писать код на языке JavaScript для взаимодействия с сервисами Google, такими как Google Таблицы, Google Документы, Gmail, Google Диск, Google Календарь и другими.

Apps Script значительно упрощает автоматизацию рутинных задач, интеграцию сервисов и создание пользовательских приложений. Одним из ключевых преимуществ платформы, которое повлияло на мой выбор, является возможность создания триггеров. Триггеры позволяют запускать скрипты по расписанию без дополнительного вмешательства пользователя.

Откройте Apps Script, перейдя по ссылке https://script.google.com/. Слева в интерфейсе вы увидите панель навигации, которая позволяет легко переключаться между разделами. Нажмите на кнопку Создать проект:

После создания проекта откроется рабочая область, куда мы будем добавлять код. Для начала удалите стандартную функцию function myFunction() {}, чтобы подготовить чистую основу для вашего скрипта:

Работа с кодом

Теперь перейдем к самому интересному — добавлению скрипта и выгрузке данных. В этом примере я покажу, как выгружать данные в Google Таблицы.

1.  Задаем необходимые настройки

В начале работы нужно указать два ключевых параметра:

• COUNTER_ID — уникальный идентификатор счетчика Яндекс Метрики, из которого вы хотите получить данные
• ACCESS_TOKEN — OAuth-токен для доступа к API Яндекс Метрики, который вы получили на предыдущем этапе

Эти параметры будут использоваться для авторизации и доступа к данным.

// Настройки Яндекс Метрики
const ACCESS_TOKEN = "ваш токен"; // Замените на ваш токен
const COUNTER_ID = "ID вашего счетчика"; // Замените на ID вашего счетчика

2. Форматируем дату

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

// Функция для получения даты в формате YYYY-MM-DD
function getFormattedDate(date) {
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, '0'); // Месяцы начинаются с 0
  const day = String(date.getDate()).padStart(2, '0');
  return `${year}-${month}-${day}`;
}

• Функция getFormattedDate: Принимает объект Date и возвращает дату в формате YYYY-MM-DD:
  • date.getFullYear(): Возвращает год в формате четырех цифр (например, 2025)
  • date.getMonth() + 1: Возвращает месяц (от 1 до 12). В JavaScript месяцы начинаются с 0, поэтому добавляем 1
  • date.getDate(): Возвращает день месяца (от 1 до 31)
  • padStart(2, ‘0’): Добавляет ведущий ноль, если число меньше 10 (например, 1 становится 01)

3. Задаем параметры запроса к Яндекс Метрике

При формировании запроса к API используются группировки (dimensions) и метрики (metrics). Прежде чем приступить к работе с кодом, рекомендую вам ознакомиться с официальной документацией Яндекса. 

В данном примере в качестве группировок я буду использовать дату и название рекламной кампании с параметром атрибуции, а в качестве метрик – визиты, клики, расходы (до НДС), e-commerce покупки и доход.

// Параметры запроса к Яндекс Метрике
const today = new Date(); // Сегодняшняя дата
const yesterday = new Date(today);
yesterday.setDate(today.getDate() - 1); // Вчерашняя дата
const params = {
  ids: COUNTER_ID,
  date1: "2025-02-23",  // Фиксированная начальная дата
  date2: getFormattedDate(yesterday),  // Динамическая конечная дата (вчера)
  group: "day", // Группировка по дням
  metrics: "ym:ad:visits,ym:ad:clicks,ym:ad:RUBConvertedAdCost,ym:ad:ecommercePurchases,ym:ad:ecommerceRUBConvertedRevenue", // Метрики
  dimensions: "ym:ad:date,ym:ad:cross_device_last_significantDirectOrderName",  // Измерения
  attribution: "cross_device_last_significant",  // Модель атрибуции
  sort: "ym:ad:date", // Сортировка по дате
  lang: "ru", // Язык ответа
  direct_client_logins: "direct_client_login",  // Параметр direct_client_login
  limit: 10000,  // Лимит строк
  accuracy: "full",  // Отключение семплирования
  filters: "ym:ad:isRobot=='No' AND ym:ad:cross_device_last_significantDirectOrderName=~'^(poisk|rsya|tov).*'",  // Фильтр без роботов и по названию кампаний
};

• today: Текущая дата
• yesterday: Вчерашняя дата, вычисляется как today – 1 день
• params: Объект с параметрами запроса к API Яндекс Метрики:
  • ids: ID счетчика
  • date1: Начальная дата для запроса данных
  • date2: Конечная дата для запроса данных
  • group: Группировка данных, например, по дням
  • metrics: Метрики, которые нужно получить. Например, визиты, клики, расходы и т.д.
  • dimensions: Измерения, по которым группируются данные. Например, дата и название кампании
  • attribution: Модель атрибуции. Например, “последний значимый переход кросс-девайс”
  • sort: Поле для сортировки данных
  • lang: Язык ответа. Если вам нужно получить ответ на русском языке, укажите “ru”
  • direct_client_logins: В значении нужно указать логин, который имеет доступ к кампаниям в Директе. Обратите внимание, что этот пункт является обязательным для выгрузки данных из отчета Директ, расходы
  • limit: Максимальное количество строк в ответе
  • accuracy: Точность данных (full отключает семплирование)
  • filters: Фильтр для отбора данных. Фильтр из примера исключает роботов и отбирает кампании, название которых начинается на poisk или rsya или tov

4. Формируем заголовки для Google Таблиц

// Заголовки для Google Таблиц
const headers = [
  "Дата",  // Соответствует ym:ad:date
  "Кампании",  // Соответствует ym:ad:cross_device_last_significantDirectOrderName
  "Визиты",  // Соответствует ym:ad:visits
  "Клики",  // Соответствует ym:ad:clicks
  "Расходы",  // Соответствует ym:ad:RUBConvertedAdCost
  "Покупки",  // Соответствует ym:ad:ecommercePurchases
  "Доход",  // Соответствует ym:ad:ecommerceRUBConvertedRevenue
];

В переменную const headers записывается массив, содержащий названия столбцов для Google Таблиц. Каждый элемент этого массива соответствует метрике или измерению, полученному из запроса к API.

5. Получаем данные из Яндекс Метрики

Функция выполняет HTTP-запрос к API, проверяет код ответа и обрабатывает ошибки, преобразует ответ API в объект JavaScript и возвращает массив с данными.

// Функция для получения данных из Яндекс Метрики
function getYandexMetrikaData() {
  if (!ACCESS_TOKEN || !COUNTER_ID) {
    throw new Error("Не заданы ACCESS_TOKEN или COUNTER_ID.");
  }

  // Кодируем фильтр для корректной передачи в URL
  const encodedFilters = encodeURIComponent(params.filters);

  // Формируем URL для запроса к API Яндекс Метрики
  const url = `https://api-metrika.yandex.net/stat/v1/data?ids=${params.ids}&date1=${params.date1}&date2=${params.date2}&group=${params.group}&metrics=${params.metrics}&dimensions=${params.dimensions}&attribution=${params.attribution}&sort=${params.sort}&lang=${params.lang}&direct_client_logins=${params.direct_client_logins}&limit=${params.limit}&accuracy=${params.accuracy}&filters=${encodedFilters}`;

  try {
    // Выполняем HTTP-запрос к API
    const response = UrlFetchApp.fetch(url, {
      headers: {
        Authorization: `OAuth ${ACCESS_TOKEN}`, // Авторизация через OAuth-токен
      },
      muteHttpExceptions: true, // Включаем обработку HTTP-ошибок
    });

    // Проверяем код ответа
    if (response.getResponseCode() !== 200) {
      throw new Error(`Ошибка HTTP: ${response.getResponseCode()}, Ответ: ${response.getContentText()}`);
    }

    // Преобразуем ответ из JSON в объект JavaScript
    const data = JSON.parse(response.getContentText());

    // Логируем ответ для отладки
    console.log("Ответ от Яндекс Метрики:", JSON.stringify(data, null, 2));

    // Проверяем, что данные существуют и имеют ожидаемую структуру
    if (!data || !data.data || !Array.isArray(data.data)) {
      throw new Error("Данные от Яндекс Метрики имеют неверный формат.");
    }

    // Возвращаем массив с данными
    return data.data;
  } catch (error) {
    console.error("Ошибка при получении данных из Яндекс Метрики:", error);
    return null; // Возвращаем null в случае ошибки
  }
}

• getYandexMetrikaData: Функция для получения данных из API Яндекс Метрики:
  • encodedFilters: Фильтр кодируется с помощью encodeURIComponent, чтобы корректно передать его в URL
  • url: Формируется URL для запроса к API с учетом всех параметров
  • UrlFetchApp.fetch: Выполняет HTTP-запрос к API
  • response.getResponseCode(): Проверяет код ответа. Если он не равен 200, выбрасывается ошибка
  • JSON.parse: Преобразует ответ API в объект JavaScript
  • console.log: Логирует ответ для отладки
  • Проверка данных: Убеждается, что данные существуют и имеют правильную структуру
  • return data.data: Возвращает массив с данными
  • Обработка ошибок: В случае ошибки она логируется, и функция возвращает null

6. Записываем данные в Google Таблицы

Функция записывает данные, полученные из Яндекс Метрики, в Google Таблицы. Она открывает таблицу, очищает лист (если нужно), добавляет заголовки и записывает данные построчно.

// Функция для записи данных в Google Таблицы
function writeToGoogleSheets(data) {
  const spreadsheetId = "ID вашей таблицы";  // Замените на ID вашей таблицы
  const sheetName = "Лист1";  // Название листа

  try {
    // Открываем таблицу
    const spreadsheet = SpreadsheetApp.openById(spreadsheetId);

    if (!spreadsheet) {
      throw new Error("Таблица не найдена. Проверьте spreadsheetId.");
    }

    // Получаем лист по имени
    let sheet = spreadsheet.getSheetByName(sheetName);

    // Если лист не найден, создаем его
    if (!sheet) {
      console.warn(`Лист "${sheetName}" не найден. Создаю новый лист.`);
      sheet = spreadsheet.insertSheet(sheetName);
    }

    // Очищаем лист (если нужно)
    sheet.clear();

    // Добавляем заголовки
    sheet.appendRow(headers);

    // Проверяем, что данные существуют и являются массивом
    if (!data || !Array.isArray(data)) {
      throw new Error("Данные для записи отсутствуют или имеют неверный формат.");
    }

    // Добавляем данные
    data.forEach(row => {
      // Проверяем, что row содержит dimensions и metrics
      if (!row.dimensions || !Array.isArray(row.dimensions) || !row.metrics || !Array.isArray(row.metrics)) {
        console.warn("Пропущен некорректный элемент данных:", row);
        return;
      }

      const values = [
        row.dimensions[0].name,  // Соответствует ym:ad:date
        row.dimensions[1].name,  // Соответствует ym:ad:cross_device_last_significantDirectOrderName
        row.metrics[0],  // Соответствует ym:ad:visits
        row.metrics[1],  // Соответствует ym:ad:clicks
        row.metrics[2],  // Соответствует ym:ad:RUBConvertedAdCost
        row.metrics[3],  // Соответствует ym:ad:ecommercePurchases
        row.metrics[4],  // Соответствует ym:ad:ecommerceRUBConvertedRevenue
      ];
      sheet.appendRow(values);
    });

    console.log("Данные успешно сохранены в Google Таблицах!");
  } catch (error) {
    console.error("Ошибка при записи данных в Google Таблицы:", error);
  }
}

• writeToGoogleSheets: Функция для записи данных в Google Таблицы:
  • spreadsheetId: ID таблицы. Это часть URL вашей Google Таблицы

• • sheetName: Название листа, на который будут записаны данные
  • spreadsheet: Открывает таблицу по ID с помощью SpreadsheetApp.openById
  • sheet: Получает лист по имени с помощью getSheetByName. Если лист не найден, создаёт новый с помощью insertSheet
  • sheet.clear(): Очищает лист перед записью новых данных
  • sheet.appendRow(headers): Добавляет заголовки в первую строку
  • Проверка данных: Проверяет, что данные существуют и являются массивом
  • data.forEach: Перебирает массив данных и добавляет каждую строку в лист
  • sheet.appendRow(values): Добавляет строку с данными в лист
  • Обработка ошибок: В случае ошибки она логируется

7. Основная функция

// Основная функция
function main() {
  try {
    // Получаем данные из Яндекс Метрики
    const data = getYandexMetrikaData();

    if (!data) {
      console.error("Данные из Яндекс Метрики не получены.");
      return;
    }

    // Записываем данные в Google Таблицы
    writeToGoogleSheets(data);
  } catch (error) {
    console.error("Произошла ошибка:", error);
  }
}

• main: Основная функция, которая управляет процессом получения данных из Яндекс Метрики и их записи в Google Таблицы. Она выполняет следующие шаги:
  • Получает данные из Яндекс Метрики
  • Проверяет, что данные успешно получены
  • Записывает данные в Google Таблицы
  • Логирует ошибки, если они возникают

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

Как итог, код выполняет следующие шаги:

• Настраивает параметры для запроса к API Яндекс Метрики
• Получает данные из API
• Записывает данные в Google Таблицы

Запускаем функцию main:

При первом запуске функции Google запросит авторизацию и предоставление необходимых прав:

Выберите аккаунт, от имени которого будет выполняться скрипт:

Разрешите все и нажмите Продолжить:

Вы можете просмотреть журнал выполнения, чтобы увидеть подробный отчёт о проделанной работе и результатах:

После выполнения функции writeToGoogleSheets данные из Яндекс Метрики будут записаны в указанную вами таблицу:

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

При необходимости проверьте, совпадают ли данные в интерфейсе отчета Директ, расходы.

Триггеры

Отлично! Теперь, когда вы создали приложение и успешно выгрузили данные в Google Таблицы, можно автоматизировать процесс с помощью триггеров в Google Apps Script. Триггеры позволяют запускать вашу функцию автоматически по расписанию или в ответ на определенные события:

Добавьте триггер:

Задайте необходимые настройки активации:

Настроим триггер для ежедневного запуска функции main с 00:00 до 01:00. Сохраним наш триггер.

При настройке триггера Google Apps Script запросит повторное предоставление прав для вашего приложения:

Вы увидите список разрешений, которые запрашивает приложение. Нажмите Разрешить (Allow):

Теперь, благодаря настроенному триггеру, процесс будет выполняться по расписанию без вашего участия:

Поздравляю!  Следуя инструкции в этой статье вы можете без глубоких навыков программирования создать скрипт, который будет автоматически загружать данные по вашим рекламным кампаниям в Google Таблицы. Для меня решение этой задачи оказалось отличным примером того, как современные технологии позволяют решать сложные задачи простыми методами.

Вот ключевые преимущества:

1. Автоматизация процесса. Вы избавитесь от необходимости вручную выгружать данные каждый день. Скрипт будет выполнять эту задачу автоматически по заданному расписанию.
2. Экономия времени и ресурсов. Процесс выгрузки данных не требует вашего участия, что освобождает время для более важных задач. Данные всегда актуальны и доступны в Google Таблицах для анализа.
3. Гибкость и масштабируемость. Вы можете легко изменить параметры запроса: добавить новые группировки, метрики, изменить фильтры и другое. Скрипт можно адаптировать под другие задачи, например, выгрузку данных из других источников.
4. Простота и доступность. Используя Google Apps Script и готовые инструкции, вы можете создать работающее решение без необходимости погружаться в сложный код. 
5. Надежность. Триггеры и встроенные механизмы Google Apps Script обеспечивают стабильную работу скрипта.
6. Возможности для улучшения. В будущем вы можете расширить функциональность скрипта, например, создать визуализацию данных в Looker Studio или Yandex DataLens