Как с помощью Google Apps Script записать данные в ячейку Google Sheets?

/**
 * Получает объект Spreadsheet по его уникальному ID.
 * @param {string} spreadsheetId - ID таблицы Google Sheets.
 * @returns {GoogleAppsScript.Spreadsheet.Spreadsheet | null} Объект таблицы или null при ошибке.
 */
function getSpreadsheetById(spreadsheetId: string): GoogleAppsScript.Spreadsheet.Spreadsheet | null {
  try {
    const ss = SpreadsheetApp.openById(spreadsheetId);
    Logger.log(`Успешно открыта таблица с ID: ${spreadsheetId}`);
    return ss;
  } catch (e) {
    Logger.log(`Ошибка открытия таблицы по ID ${spreadsheetId}: ${e}`);
    return null;
  }
}

// Пример использования
const SPREADSHEET_ID: string = 'YOUR_SPREADSHEET_ID'; // Замените на ID вашей таблицы
const spreadsheet = getSpreadsheetById(SPREADSHEET_ID);

/**
 * Получает *первый* найденный объект Spreadsheet по имени.
 * @param {string} name - Имя таблицы Google Sheets.
 * @returns {GoogleAppsScript.Spreadsheet.Spreadsheet | null} Объект таблицы или null, если таблица не найдена или при ошибке.
 */
function getSpreadsheetByName(name: string): GoogleAppsScript.Spreadsheet.Spreadsheet | null {
  try {
    const files = DriveApp.getFilesByName(name);
    if (files.hasNext()) {
      const file = files.next();
      if (file.getMimeType() === MimeType.GOOGLE_SHEETS) {
        const ss = SpreadsheetApp.openById(file.getId());
        Logger.log(`Найдена и открыта таблица по имени: ${name} (ID: ${file.getId()})`);
        return ss;
      } else {
        Logger.log(`Файл с именем '${name}' найден, но это не Google Sheet.`);
        return null;
      }
    } else {
      Logger.log(`Таблица с именем '${name}' не найдена.`);
      return null;
    }
  } catch (e) {
    Logger.log(`Ошибка поиска таблицы по имени ${name}: ${e}`);
    return null;
  }
}

// Пример использования
// const spreadsheetByName = getSpreadsheetByName('Имя Моей Таблицы');

/**
 * Возвращает активную (текущую) таблицу, к которой привязан скрипт.
 * @returns {GoogleAppsScript.Spreadsheet.Spreadsheet} Объект активной таблицы.
 */
function getActiveSpreadsheet(): GoogleAppsScript.Spreadsheet.Spreadsheet {
  return SpreadsheetApp.getActiveSpreadsheet();
}

// Пример использования
// const activeSS = getActiveSpreadsheet();

/**
 * Получает лист по его имени внутри таблицы.
 * @param {GoogleAppsScript.Spreadsheet.Spreadsheet} ss - Объект таблицы.
 * @param {string} sheetName - Имя листа.
 * @returns {GoogleAppsScript.Spreadsheet.Sheet | null} Объект листа или null, если лист не найден.
 */
function getSheetByName(ss: GoogleAppsScript.Spreadsheet.Spreadsheet, sheetName: string): GoogleAppsScript.Spreadsheet.Sheet | null {
  const sheet = ss.getSheetByName(sheetName);
  if (!sheet) {
    Logger.log(`Лист с именем '${sheetName}' не найден в таблице '${ss.getName()}'.`);
  }
  return sheet;
}

// Пример использования
// if (spreadsheet) {
//   const sheet = getSheetByName(spreadsheet, 'Данные по кампаниям');
// }

/**
 * Получает лист по его индексу (позиции) в таблице.
 * @param {GoogleAppsScript.Spreadsheet.Spreadsheet} ss - Объект таблицы.
 * @param {number} index - Индекс листа (начиная с 0).
 * @returns {GoogleAppsScript.Spreadsheet.Sheet | null} Объект листа или null при ошибке.
 */
function getSheetByIndex(ss: GoogleAppsScript.Spreadsheet.Spreadsheet, index: number): GoogleAppsScript.Spreadsheet.Sheet | null {
  try {
    const sheets = ss.getSheets();
    if (index >= 0 && index < sheets.length) {
      return sheets[index];
    }
    Logger.log(`Лист с индексом ${index} не найден. Всего листов: ${sheets.length}.`);
    return null;
  } catch (e) {
    Logger.log(`Ошибка получения листа по индексу ${index}: ${e}`);
    return null;
  }
}

// Пример использования
// if (spreadsheet) {
//  const firstSheet = getSheetByIndex(spreadsheet, 0);
// }

/**
 * Получает активный (текущий) лист в таблице.
 * @param {GoogleAppsScript.Spreadsheet.Spreadsheet} ss - Объект таблицы.
 * @returns {GoogleAppsScript.Spreadsheet.Sheet} Объект активного листа.
 */
function getActiveSheet(ss: GoogleAppsScript.Spreadsheet.Spreadsheet): GoogleAppsScript.Spreadsheet.Sheet {
  return ss.getActiveSheet();
}

// Пример использования
// if (spreadsheet) {
//   const currentSheet = getActiveSheet(spreadsheet);
// }

/**
 * Демонстрация обработки ошибок при доступе к листу.
 */
function safeSheetAccessExample() {
  const ssId = 'INVALID_ID_EXAMPLE'; // Невалидный ID для примера
  const ss = getSpreadsheetById(ssId);

  if (!ss) {
    Logger.log("Не удалось получить доступ к таблице. Прекращение работы.");
    return; // Прерываем выполнение, если таблица не найдена
  }

  const sheetName = 'НесуществующийЛист';
  const sheet = getSheetByName(ss, sheetName);

  if (!sheet) {
    Logger.log(`Лист '${sheetName}' не найден. Создаем новый лист.`);
    // Можно добавить логику создания листа, если он отсутствует
    // const newSheet = ss.insertSheet(sheetName);
    // Logger.log(`Лист '${sheetName}' успешно создан.`);
    return; // Прерываем или обрабатываем дальше
  }

  // ... дальнейший код работы с листом 'sheet'
  Logger.log(`Успешно получен доступ к листу '${sheet.getName()}'`);
}

/**
 * Записывает значение в указанную ячейку листа.
 * @param {GoogleAppsScript.Spreadsheet.Sheet} sheet - Объект листа.
 * @param {number} row - Номер строки (начиная с 1).
 * @param {number} column - Номер столбца (начиная с 1).
 * @param {string | number | Date | boolean} value - Значение для записи.
 */
function writeToCell(sheet: GoogleAppsScript.Spreadsheet.Sheet, row: number, column: number, value: string | number | Date | boolean): void {
  try {
    const cell: GoogleAppsScript.Spreadsheet.Range = sheet.getRange(row, column);
    cell.setValue(value);
    Logger.log(`Значение '${value}' успешно записано в ячейку R${row}C${column} листа '${sheet.getName()}'.`);
  } catch (e) {
    Logger.log(`Ошибка записи в ячейку R${row}C${column} листа '${sheet.getName()}': ${e}`);
  }
}

// Пример использования
function demoWrite() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getSheetByName('Лист1'); // Убедитесь, что лист с таким именем существует

  if (sheet) {
    writeToCell(sheet, 1, 1, 'Название кампании'); // A1
    writeToCell(sheet, 1, 2, 'Расход');          // B1
    writeToCell(sheet, 2, 1, 'Поиск - Бренд');    // A2
    writeToCell(sheet, 2, 2, 1500.75);       // B2
  }
}

// Запись в ячейку C5
// sheet.getRange('C5').setValue('Пример текста');

/**
 * Пример: Запись данных о рекламной кампании из переменных.
 */
function logCampaignData() {
  const campaignName: string = 'Весенняя распродажа - Контекст';
  const cost: number = 5230.50;
  const clicks: number = 1245;
  const conversions: number = 35;
  const reportDate: Date = new Date();

  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getSheetByName('Отчет по рекламе');

  if (!sheet) {
    Logger.log('Лист "Отчет по рекламе" не найден.');
    return;
  }

  // Находим первую пустую строку для записи
  const lastRow = sheet.getLastRow();
  const targetRow = lastRow + 1;

  // Записываем данные
  writeToCell(sheet, targetRow, 1, reportDate);
  writeToCell(sheet, targetRow, 2, campaignName);
  writeToCell(sheet, targetRow, 3, cost);
  writeToCell(sheet, targetRow, 4, clicks);
  writeToCell(sheet, targetRow, 5, conversions);
  // Можно добавить расчетные метрики
  if (clicks > 0) {
     const cpc = cost / clicks;
     writeToCell(sheet, targetRow, 6, cpc);
  }
   if (conversions > 0) {
     const cpa = cost / conversions;
     writeToCell(sheet, targetRow, 7, cpa);
  }
}

/**
 * Записывает двумерный массив данных в указанный диапазон.
 * @param {GoogleAppsScript.Spreadsheet.Sheet} sheet - Объект листа.
 * @param {number} startRow - Начальная строка диапазона.
 * @param {number} startColumn - Начальный столбец диапазона.
 * @param {any[][]} data - Двумерный массив данных для записи.
 */
function writeBatchData(sheet: GoogleAppsScript.Spreadsheet.Sheet, startRow: number, startColumn: number, data: any[][]): void {
  if (!data || data.length === 0 || data[0].length === 0) {
    Logger.log('Нет данных для записи.');
    return;
  }

  const numRows = data.length;
  const numCols = data[0].length;

  try {
    const range: GoogleAppsScript.Spreadsheet.Range = sheet.getRange(startRow, startColumn, numRows, numCols);
    range.setValues(data);
    Logger.log(`Массив данных (${numRows}x${numCols}) успешно записан начиная с R${startRow}C${startColumn}.`);
  } catch (e) {
    Logger.log(`Ошибка пакетной записи данных: ${e}`);
  }
}

// Пример использования: Запись данных по нескольким кампаниям
function demoBatchWrite() {
  const campaignData: any[][] = [
    [new Date(), 'Кампания Alpha', 1200.00, 850, 15], // Дата, Название, Расход, Клики, Конверсии
    [new Date(), 'Кампания Beta - Ремаркетинг', 850.25, 1500, 25],
    [new Date(), 'Кампания Gamma - Видео', 2100.50, 25000, 5] // Видео может иметь меньше конверсий
  ];

  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getSheetByName('Сводный отчет');

  if (sheet) {
    const startRow = sheet.getLastRow() + 1;
    writeBatchData(sheet, startRow, 1, campaignData);
  }
}

/**
 * Записывает данные и применяет базовое форматирование.
 */
function writeAndFormat() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getSheetByName('Форматирование');
  if (!sheet) return;

  const data = [
    ['Заголовок 1', 'Заголовок 2', 'Заголовок 3'],
    ['Данные A', 123.456, new Date()],
    ['Данные B', 789, new Date()]
  ];

  const startRow = 2;
  const startCol = 2; // B2

  const range = sheet.getRange(startRow, startCol, data.length, data[0].length);
  range.setValues(data);

  // Применение форматирования
  // Заголовки (первая строка диапазона)
  range.offset(0, 0, 1, data[0].length) // Получаем диапазон заголовков
       .setFontWeight('bold')
       .setBackground('#d9ead3'); // Светло-зеленый фон

  // Числовой столбец (второй столбец диапазона)
  range.offset(1, 1, data.length - 1, 1) // Получаем диапазон числовых данных (исключая заголовок)
       .setNumberFormat('#,##0.00'); // Формат числа с 2 знаками после запятой

  // Столбец с датами (третий столбец диапазона)
  range.offset(1, 2, data.length - 1, 1) // Получаем диапазон дат
       .setNumberFormat('yyyy-mm-dd HH:mm'); // Формат даты и времени

  Logger.log('Данные записаны и отформатированы.');
}

/**
 * Функция, которую будет вызывать триггер.
 */
function dailyCampaignUpdate() {
  // const yesterdayData = fetchYesterdayCampaignData(); // Получаем данные за вчера
  // ... обработка данных ...
  // logCampaignData(processedData); // Записываем обработанные данные
  Logger.log("Ежедневное обновление данных кампании выполнено.");
}

// Триггер настраивается вручную в редакторе Apps Script:
// 1. Откройте редактор скриптов.
// 2. Слева выберите иконку "Триггеры" (будильник).
// 3. Нажмите "+ Добавить триггер".
// 4. Настройте параметры:
//    - Выберите функцию для запуска: dailyCampaignUpdate
//    - Выберите развертывание: Head
//    - Выберите источник события: Триггер по времени
//    - Выберите тип триггера на основе времени: Дневной таймер
//    - Выберите время суток: например, 8 - 9 утра
//    - Настройки уведомления об ошибках: по необходимости
// 5. Сохраните триггер (потребуется авторизация).

function robustDataWrite() {
  try {
    const ssId = PropertiesService.getScriptProperties().getProperty('TARGET_SS_ID');
    if (!ssId) {
      throw new Error('ID целевой таблицы не найден в Script Properties.');
    }

    const ss = SpreadsheetApp.openById(ssId);
    const sheet = ss.getSheetByName('Raw Data');
    if (!sheet) {
      throw new Error(`Лист 'Raw Data' не найден в таблице ${ssId}.`);
    }

    // const data = fetchDataFromAPI(); // Получение данных из внешнего источника
    const data = [['Example', 100]]; // Пример данных

    if (data && data.length > 0) {
       const targetRow = sheet.getLastRow() + 1;
       sheet.getRange(targetRow, 1, data.length, data[0].length).setValues(data);
       Logger.log(`Данные успешно записаны, ${data.length} строк.`);
    } else {
      Logger.log('Нет новых данных для записи.');
    }

  } catch (error) {
    // Логируем ошибку
    Logger.log(`Произошла ошибка: ${error.message}\nСтек вызовов: ${error.stack}`);

    // Опционально: Отправляем уведомление администратору
    // MailApp.sendEmail('admin@example.com', 'Ошибка в скрипте записи данных', `Произошла ошибка: ${error.message}`);
  }
}