Google Apps Script: Как осуществить запись данных в строку?

/**
 * Получает активный лист Google Sheets.
 * @returns {GoogleAppsScript.Spreadsheet.Sheet} Активный лист.
 */
function getActiveSheet(): GoogleAppsScript.Spreadsheet.Sheet | null {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  if (!ss) {
    Logger.log('Не удалось получить доступ к активной таблице.');
    return null;
  }
  const sheet = ss.getActiveSheet();
  if (!sheet) {
    Logger.log('Не удалось получить доступ к активному листу.');
    return null;
  }
  return sheet;
}

/**
 * Записывает одно значение в указанную ячейку.
 * @param {GoogleAppsScript.Spreadsheet.Sheet} sheet - Лист для записи.
 * @param {string} cellNotation - Нотация ячейки (например, 'A1').
 * @param {any} value - Значение для записи.
 */
function writeSingleValue(sheet: GoogleAppsScript.Spreadsheet.Sheet, cellNotation: string, value: any): void {
  if (!sheet) return;
  try {
    const range = sheet.getRange(cellNotation);
    range.setValue(value);
    Logger.log(`Значение '${value}' успешно записано в ячейку ${cellNotation}.`);
  } catch (e) {
    Logger.log(`Ошибка записи в ячейку ${cellNotation}: ${e}`);
  }
}

// Пример вызова
const currentSheet = getActiveSheet();
if (currentSheet) {
  writeSingleValue(currentSheet, 'C5', 'Новый статус'); 
}

/**
 * Записывает массив значений в строку, начиная с указанной ячейки.
 * @param {GoogleAppsScript.Spreadsheet.Sheet} sheet - Лист для записи.
 * @param {string} startCellNotation - Начальная ячейка строки (например, 'A2').
 * @param {any[]} rowData - Массив значений для записи в строку.
 */
function writeRowValues(sheet: GoogleAppsScript.Spreadsheet.Sheet, startCellNotation: string, rowData: any[]): void {
  if (!sheet || !rowData || rowData.length === 0) return;
  try {
    // Определяем диапазон: 1 строка, количество столбцов = длине массива rowData
    const range = sheet.getRange(startCellNotation).offset(0, 0, 1, rowData.length);
    // setValues требует двумерный массив
    range.setValues([rowData]); 
    Logger.log(`Данные успешно записаны в строку начиная с ${startCellNotation}.`);
  } catch (e) {
    Logger.log(`Ошибка записи строки начиная с ${startCellNotation}: ${e}`);
  }
}

// Пример вызова
const sheet = getActiveSheet();
if (sheet) {
  const campaignData = ['Campaign 123', 'Google Ads', 150.75, new Date()];
  writeRowValues(sheet, 'A10', campaignData);
}

/**
 * Записывает данные о рекламной кампании в указанную строку.
 * @param {GoogleAppsScript.Spreadsheet.Sheet} sheet - Лист для записи.
 * @param {number} rowIndex - Номер строки для записи (начиная с 1).
 * @param {string} campaignName - Название кампании.
 * @param {number} clicks - Количество кликов.
 * @param {number} cost - Затраты.
 */
function logCampaignData(sheet: GoogleAppsScript.Spreadsheet.Sheet, rowIndex: number, campaignName: string, clicks: number, cost: number): void {
  if (!sheet) return;
  
  const timestamp: Date = new Date();
  const dataToWrite: any[] = [campaignName, clicks, cost, timestamp];
  
  try {
    // Запись в строку rowIndex, начиная с 1-го столбца
    const range = sheet.getRange(rowIndex, 1, 1, dataToWrite.length);
    range.setValues([dataToWrite]);
    Logger.log(`Данные кампании '${campaignName}' записаны в строку ${rowIndex}.`);
  } catch (e) {
    Logger.log(`Ошибка записи данных кампании '${campaignName}' в строку ${rowIndex}: ${e}`);
  }
}

// Пример вызова
const activeSheet = getActiveSheet();
if (activeSheet) {
  const campaign = 'Summer Sale Promotion';
  const clickCount = 542;
  const totalCost = 215.50;
  const targetRow = 15; // Записать в 15-ю строку
  logCampaignData(activeSheet, targetRow, campaign, clickCount, totalCost);
}

/**
 * Находит последнюю строку с данными и записывает данные в следующую строку.
 * @param {GoogleAppsScript.Spreadsheet.Sheet} sheet - Лист для записи.
 * @param {any[]} rowData - Массив данных для записи.
 */
function appendDataToNextRow(sheet: GoogleAppsScript.Spreadsheet.Sheet, rowData: any[]): void {
  if (!sheet || !rowData || rowData.length === 0) return;
  try {
    const lastRow = sheet.getLastRow();
    const nextRow = lastRow + 1;
    const range = sheet.getRange(nextRow, 1, 1, rowData.length);
    range.setValues([rowData]);
    Logger.log(`Данные добавлены в строку ${nextRow}.`);
  } catch (e) {
    Logger.log(`Ошибка добавления данных в конец листа: ${e}`);
  }
}

// Пример вызова
const sheetForAppend = getActiveSheet();
if (sheetForAppend) {
  const newLogEntry = ['INFO', new Date(), 'User logged in', 'user@example.com'];
  appendDataToNextRow(sheetForAppend, newLogEntry);
}

/**
 * Обновляет строку с данными пользователя, если email совпадает.
 * @param {GoogleAppsScript.Spreadsheet.Sheet} sheet - Лист для поиска и обновления.
 * @param {string} emailToFind - Email пользователя для поиска.
 * @param {any[]} newRowData - Новые данные для записи.
 * @param {number} emailColumnIndex - Индекс столбца с email (начиная с 1).
 */
function updateRowByEmail(sheet: GoogleAppsScript.Spreadsheet.Sheet, emailToFind: string, newRowData: any[], emailColumnIndex: number = 1): void {
  if (!sheet) return;
  try {
    const dataRange = sheet.getDataRange();
    const values = dataRange.getValues();
    let rowFound = false;

    for (let i = 0; i < values.length; i++) {
      // Проверяем email в нужном столбце (индекс в массиве = emailColumnIndex - 1)
      if (values[i][emailColumnIndex - 1] === emailToFind) {
        const targetRowIndex = i + 1; // Номер строки в таблице (начиная с 1)
        const rangeToUpdate = sheet.getRange(targetRowIndex, 1, 1, newRowData.length);
        rangeToUpdate.setValues([newRowData]);
        Logger.log(`Строка ${targetRowIndex} для email ${emailToFind} обновлена.`);
        rowFound = true;
        break; // Прерываем цикл после нахождения и обновления
      }
    }

    if (!rowFound) {
      Logger.log(`Пользователь с email ${emailToFind} не найден для обновления.`);
    }
  } catch (e) {
    Logger.log(`Ошибка при обновлении строки по email ${emailToFind}: ${e}`);
  }
}

// Пример вызова
const sheetToUpdate = getActiveSheet();
if (sheetToUpdate) {
  const userEmail = 'test@example.com';
  const updatedUserData = [userEmail, 'Updated Name', 'Active', new Date()];
  updateRowByEmail(sheetToUpdate, userEmail, updatedUserData, 1); // Email в 1-м столбце
}

// Пример структуры с try...catch см. в предыдущих функциях.
// Важно логировать ошибку (e) для последующего анализа.
// Можно добавить уведомления администратору при критических ошибках.

/**
 * Добавляет строку данных в конец листа с использованием appendRow.
 * @param {GoogleAppsScript.Spreadsheet.Sheet} sheet - Лист для добавления данных.
 * @param {any[]} rowData - Массив данных для добавления.
 */
function appendRowEfficiently(sheet: GoogleAppsScript.Spreadsheet.Sheet, rowData: any[]): void {
  if (!sheet || !rowData || rowData.length === 0) return;
  try {
    sheet.appendRow(rowData);
    Logger.log('Данные успешно добавлены в конец листа с помощью appendRow.');
  } catch (e) {
    Logger.log(`Ошибка при использовании appendRow: ${e}`);
  }
}

// Пример вызова
const sheetForAppendRow = getActiveSheet();
if (sheetForAppendRow) {
  const webLeadData = [new Date(), 'contact_form', 'John Doe', 'john.doe@example.com', 'Inquiry about product X'];
  appendRowEfficiently(sheetForAppendRow, webLeadData);
}

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

  try {
    const range = sheet.getRange(startRow, startCol, numRows, numCols);
    range.setValues(data);
    Logger.log(`Пакет из ${numRows} строк успешно записан.`);
  } catch (e) {
    Logger.log(`Ошибка пакетной записи: ${e}`);
  }
}

// Пример вызова: запись 3 строк данных о кликах
const sheetForBatch = getActiveSheet();
if (sheetForBatch) {
  const clickDataBatch = [
    ['2023-10-26', 'campaign_A', 'ad_group_1', 15], 
    ['2023-10-26', 'campaign_B', 'ad_group_2', 22],
    ['2023-10-27', 'campaign_A', 'ad_group_1', 18]
  ];
  // Начать запись с 20-й строки, 1-го столбца
  writeBatchData(sheetForBatch, 20, 1, clickDataBatch); 
}

/**
 * Обработчик отправки формы, записывающий ответ и временную метку.
 * @param {GoogleAppsScript.Events.FormsOnFormSubmit} e - Объект события отправки формы.
 */
function onFormSubmitHandler(e: GoogleAppsScript.Events.FormsOnFormSubmit): void {
  const formResponse = e.response;
  const itemResponses = formResponse.getItemResponses();
  const responseData: any[] = [];

  // Собираем ответы на вопросы
  itemResponses.forEach(itemResponse => {
    responseData.push(itemResponse.getResponse());
  });

  // Добавляем временную метку
  responseData.unshift(new Date()); // Добавляем в начало массива

  // Получаем лист для записи (например, по имени)
  const ss = SpreadsheetApp.getActiveSpreadsheet(); 
  const logSheet = ss.getSheetByName('Form Responses Log'); // Укажите имя вашего листа

  if (logSheet) {
    appendRowEfficiently(logSheet, responseData);
  } else {
    Logger.log('Лист для записи логов формы не найден.');
  }
}

// Необходимо настроить триггер для этой функции в редакторе скриптов.

/** 
 * Универсальная функция логирования в Google Sheet.
 * @param {string} level - Уровень логирования (INFO, WARN, ERROR).
 * @param {string} message - Сообщение лога.
 * @param {string} [details=''] - Дополнительные детали (опционально).
 */
function logToSheet(level: string, message: string, details: string = ''): void {
  const logSheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Script Logs'); // Укажите имя листа
  if (!logSheet) {
    console.error('Log sheet not found!');
    return;
  }
  try {
    const timestamp = new Date();
    logSheet.appendRow([timestamp, level, message, details]);
  } catch (e) {
    console.error(`Failed to log to sheet: ${e}`);
  }
}

// Пример использования
logToSheet('INFO', 'Script execution started.');
try {
  // ... какой-то код ...
  // throw new Error('Simulated error'); // Для теста ERROR
  logToSheet('INFO', 'Data processing complete.');
} catch (error) {
  logToSheet('ERROR', 'An error occurred during processing.', error.message);
}