Google Apps Script — руководство: автономные и привязанные скрипты

TL;DR

Google Apps Script (GAS) — облачная платформа на JavaScript для автоматизации и расширения Google Документов, Таблиц, Форм и Диска. В статье показано, как создать автономный и привязанный скрипты шаг за шагом, объяснены разрешения, триггеры, ограничения и лучшие практики. Также есть чек-листы для ролей, варианты отладки и альтернативные подходы.

Быстрые ссылки

• Что такое Google Apps Script?
• Как создать автономный скрипт
• Как создать привязанный скрипт

Что такое Google Apps Script?

Google Apps Script — это облачная платформа для быстрого создания лёгких веб-приложений и автоматизаций, которые интегрируются с продуктами Google (Docs, Sheets, Slides, Drive, Gmail и др.). Язык — JavaScript (современная версия V8), поэтому разработчику знакомая экосистема веб-разработки применяется внутри браузера.

Короткое определение терминов:

• Скрипт — программа, написанная на Apps Script/JavaScript для автоматизации задач.
• Привязанный скрипт — скрипт, связанный с конкретным файлом (например, таблицей). Работает только в контексте этого файла.
• Автономный скрипт — самостоятельный проект, который не привязан к конкретному документу; может управлять несколькими сервисами и работать по расписанию.

Типы скриптов:

• Standalone (автономный): выполняет задачи в пределах аккаунта и сервисов, похож на макросы, но создаётся отдельно от конкретного файла.
• Bound (привязанный): добавляет функциональность конкретному файлу — собственные меню, сайдбары, диалоговые окна и т.д.

Важно: GAS удобен для автоматизации рутинных задач, интеграции между сервисами Google и для быстрого прототипирования внутренних инструментов.

Как создать автономный скрипт: подробная инструкция

Ниже — пошаговое руководство по созданию простого автономного скрипта, который создаёт Google Документ и при желании отправляет уведомление по почте с ссылкой.

1. Откройте Google Apps Script: в браузере перейдите на https://script.google.com или через меню Google Workspace (в правом верхнем меню выберите Apps Script).

2. В верхнем левом углу нажмите на иконку «гамбургер», затем «New project» (Новый проект).

3. Откроется новый проект с примерной пустой функцией. Можно удалить предзаполненный код.

Примечание: для запуска необходимо быть вошедшим в Google-аккаунт.

4. Вставьте следующий код (комментарии переведены на русский):

// Инициализация функции: создаёт документ и добавляет в него параграф
function createADocument() {
  // Создаём новый Google Документ с именем 'Hello, world!'
  var doc = DocumentApp.create('Hello, world!');
  // Получаем тело документа и добавляем абзац
  doc.getBody().appendParagraph('This document was created by Google Apps Script.');
}

Пояснение к коду (построчно):

• DocumentApp.create(‘…’) — создаёт новый документ в корне Google Диска текущего пользователя.
• doc.getBody().appendParagraph(…) — получает тело документа и добавляет текстовый абзац.

5. Сохраните скрипт: в меню выберите «File» → «Save». Дайте проекту понятное имя.

6. Запустите код, нажав кнопку «Run» (значок ▶) в тулбаре. При первом запуске появится окно с запросом разрешений — нажмите «Review Permissions».

7. Так как приложение не проверено Google, появится предупреждение: нажмите «Advanced» (Дополнительно), затем «Go to CreateNewDoc» (или имя вашего проекта).

8. Просмотрите список разрешений и нажмите «Allow» (Разрешить).

9. После успешного выполнения откройте Google Диск — документ с именем «Hello, World!» будет создан. Дважды кликните, чтобы открыть.

10. Опционально: отправка уведомления по электронной почте. Добавьте после appendParagraph следующие строки (до закрывающей скобки функции):

// Получаем URL документа
var url = doc.getUrl();
// Получаем email активного пользователя
var email = Session.getActiveUser().getEmail();
// Используем имя документа как тему письма
var subject = doc.getName();
// Формируем тело письма
var body = 'Link to your doc: ' + url;
// Отправляем письмо с ссылкой
GmailApp.sendEmail(email, subject, body);

После добавления кода вы снова увидите запрос дополнительных разрешений (для Gmail). Подтвердите их тем же способом.

Когда скрипт выполнится, вы получите письмо с ссылкой на созданный документ.

Замечание: если вы не ожидаете письма или не доверяете приложению, внимательно смотрите запрашиваемые OAuth-области (scopes) при авторизации.

Как создать привязанный скрипт для Google Таблиц: пошагово

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

1. Откройте таблицу Google Sheets с дублирующимися строками.

2. В меню табличного редактора выберите «Tools» → «Script editor» (Инструменты → Редактор скриптов).

3. Откроется новый скрипт, привязанный к этой таблице: удалите начальный код и вставьте следующий:

// Удаляет повторяющиеся строки в активном листе
function removeDuplicates() {
  // Получаем текущий активный лист
  var sheet = SpreadsheetApp.getActiveSheet();
  // Считываем все значения диапазона
  var data = sheet.getDataRange().getValues();
  // Массив для уникальных строк
  var newData = [];
  // Проходим все строки
  for (var i in data) {
    var row = data[i];
    var duplicate = false;
    for (var j in newData) {
      if (row.join() == newData[j].join()) {
        duplicate = true;
        break;
      }
    }
    // Если строка не дубликат — добавляем
    if (!duplicate) {
      newData.push(row);
    }
  }
  // Очищаем лист и записываем новые данные
  sheet.clearContents();
  sheet.getRange(1, 1, newData.length, newData[0].length).setValues(newData);
}

Примечание: скрипт считает строки полностью совпадающими только если все ячейки в строке совпадают друг с другом. Для частичных совпадений (например, проверка по столбцу) сперва фильтруйте/нормализуйте данные.

4. Сохраните и запустите. При первом запуске потребуется авторизация доступа к Таблицам.

5. После выполнения откройте таблицу — дубликаты должны исчезнуть.

Ограничение: если у вас таблица оформлена как объект (например, внутри Google Docs или как «форматированная таблица»), скрипт может не корректно подстроить размеры или форматирование. Скрипт работает с данными в ячейках, но не сохранит стили/ширины столбцов/слияния ячеек.

Подробные объяснения и практические советы

Разрешения и OAuth-сферы доступа

Каждый скрипт запрашивает набор разрешений (scopes), чтобы получить доступ к сервисам (Docs, Drive, Gmail и т.д.). При запуске вы увидите экран авторизации и список необходимых областей доступа. Советы:

• Минимизируйте набор разрешений: запрашивайте только те сервисы, которые действительно нужны.
• Для корпоративного использования проводите аудит запрашиваемых областей и согласуйте с администратором Google Workspace.
• Если скрипт будет публично доступен (опубликован как аддон), вам может понадобиться проверка безопасности от Google (OAuth verification).

Важно: предупреждение «unverified app» означает, что Google ещё не проверял клиент OAuth. Для внутренних инструментов это нормально, но внешним пользователям оно может помешать.

Триггеры: когда запускать скрипты автоматически

Существует два вида триггеров:

• Простейшие (simple triggers): onOpen, onEdit, onFormSubmit. Они не требуют явной установки и работают с ограниченными правами (не могут обращаться к сервисам требующим авторизации).
• Устанавливаемые (installable triggers): по расписанию (time-driven), onChange, onFormSubmit и т.д. Они запускаются с правами пользователя, установившего триггер, и могут делать действия, требующие авторизации.

Примеры использования:

• Плановая очистка данных по ночам — time-driven триггер.
• Уведомления при отправке формы — installable onFormSubmit.

Как создать installable триггер: в редакторе Apps Script идите в раздел Triggers → Add Trigger и выберите функцию + время/событие.

Отладка и логирование

• Logger.log(‘…’) — вывод в лог (см. View → Logs). Полезно для быстрого дебага.
• console.log — работает в среде V8 и выводится в стеке выполнения/журнала.
• Try/catch — оборачивайте потенциально опасные участки кода и отправляйте ошибки в почту или систему логирования.
• Stackdriver / Cloud Logging — для корпоративных проектов интеграция с централизованным логированием.

Производительность и квоты

Apps Script имеет встроенные ограничения (квоты): число вызовов сервисов, время выполнения, частота отправки почты и т.д. Эти ограничения зависят от типа аккаунта (личный, рабочий/учебный, G Suite/Google Workspace). Рекомендации:

• Объединяйте операции: читайте/записывайте диапазоны блоками, а не по ячейке.
• Кешируйте повторяющиеся запросы (CacheService).
• Для больших объёмов данных используйте пакетную обработку и разбивайте на батчи.
• Используйте оптимизированные структуры (Map/Set) вместо вложенных циклов там, где это возможно.

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

Безопасность и приватность

• Никогда не храните чувствительные секреты (пароли, API-ключи) прямо в коде. Используйте PropertiesService для хранения параметров или секретов в защищённой области проекта.
• Для корпоративных сценариев используйте аккаунты сервисов и централизованную авторизацию, когда возможно.
• При публикации аддона убедитесь, что он соответствует политике конфиденциальности вашей организации и требованиям GDPR/локального законодательства при обработке персональных данных. Если скрипт обрабатывает персональные данные, документируйте цель обработки, правовое основание и срок хранения.

Публикация и распространение

Варианты дистрибуции:

• Локальные скрипты в аккаунтах пользователей (копирование/клонирование).
• Привязанные скрипты в шаблонах (Template) — пользователи копируют файл с привязанным скриптом.
• Публичные дополнения (Add-ons): требуют процесса публикации и, возможно, проверки Google.
• Установка триггеров администратором для домена: админ может развернуть решения на уровне домена.

Когда Apps Script не подходит: ограничения и альтернативы

Counterexamples / Когда это не сработает:

• Очень большие объёмы данных (миллионы строк): Apps Script не подходит для тяжёлой ETL-обработки; используйте BigQuery, Cloud Functions или внешние ETL-инструменты.
• Низкоуровневые задачи, требующие специализированных библиотек/бинарников — Apps Script ограничен браузерной/серверной средой JS.
• Сложные UI или клиентские приложения — лучше отдельный веб-приложение с OAuth и Google Workspace API.

Альтернативы:

• Google Workspace REST APIs (Drive API, Sheets API) + собственный backend (Cloud Run, App Engine) при необходимости масштабирования.
• Google Cloud Functions / Cloud Run для событийной и масштабируемой обработки.
• Создание полноценного веб-приложения (React/Vue) + OAuth: для сложных интерфейсов и публичных продуктов.

Ментальные модели (как думать о GAS):

• «Проводник» между продуктами Google — Apps Script удобно использовать как оркестратор сервисов.
• «Макрос ++» — более мощные макросы, которые могут обращаться к Drive, Gmail, Calendar и т.д.
• «Быстрая автоматизация» — для задач, которые можно решить с небольшим объёмом кода и стандартными сервисами.

Руководства и примеры: расширение и лучшие практики

Рассмотрим расширение приведённых примеров и возможные улучшения.

1. Обработка ошибок и оповещение (пример для createADocument):

function createADocumentWithNotify() {
  try {
    var doc = DocumentApp.create('Hello, world!');
    doc.getBody().appendParagraph('This document was created by Google Apps Script.');
    var url = doc.getUrl();
    var email = Session.getActiveUser().getEmail();
    GmailApp.sendEmail(email, doc.getName(), 'Link: ' + url);
  } catch (e) {
    // Логируем и уведомляем администратора
    Logger.log('Ошибка: ' + e.toString());
    // Отправим письмо с трассировкой ошибки ответственному
    GmailApp.sendEmail('admin@example.com', 'Script error', e.toString());
    throw e; // проброс исключения, чтобы видеть его в журнале
  }
}

2. Улучшение удаления дубликатов: сравнение по ключевому столбцу (например, столбец A):

function removeDuplicatesByColumn(columnIndex) {
  var sheet = SpreadsheetApp.getActiveSheet();
  var data = sheet.getDataRange().getValues();
  var seen = {};
  var newData = [];
  for (var i = 0; i < data.length; i++) {
    var key = data[i][columnIndex - 1]; // columnIndex: 1-based
    if (!seen[key]) {
      seen[key] = true;
      newData.push(data[i]);
    }
  }
  sheet.clearContents();
  sheet.getRange(1, 1, newData.length, newData[0].length).setValues(newData);
}

3. Использование CacheService для кэширования результатов внешних вызовов

function cachedLookup(key) {
  var cache = CacheService.getScriptCache();
  var cached = cache.get(key);
  if (cached) return JSON.parse(cached);
  var result = callExternalApi(key);
  cache.put(key, JSON.stringify(result), 1500);
  return result;
}

4. Примеры полезных API в Apps Script:

• DocumentApp, SpreadsheetApp, DriveApp, GmailApp, CalendarApp, UrlFetchApp, PropertiesService, CacheService, ScriptApp.

Чек-листы по ролям

Чек-лист для разработчика:

• Оценить объём данных и частоту выполнения.
• Спроектировать набор необходимых OAuth-областей и минимизировать их.
• Добавить обработку ошибок и логирование.
• Написать unit-style тесты (эмулируя данные) и ручные тесты.
• Документировать доступы и инструкцию по развёртыванию.

Чек-лист для администратора Google Workspace:

• Проверить соответствие политике безопасности домена.
• Решить вопрос распространения (локально/доменно/публично).
• Установить лимиты на создание скриптов, если нужно.

Чек-лист для пользователя (конечный):

• Убедиться, что понимаете, какие разрешения запрашивает скрипт.
• Проверить уведомления безопасности от Google после авторизации.
• Информировать администратора, если скрипт обрабатывает конфиденциальные данные.

Критерии приёмки

Пример набора критериев приёмки для скрипта удаления дубликатов:

• Скрипт корректно удаляет дубликаты при полном совпадении всех ячеек в строке.
• Скрипт сохраняет заголовки таблицы (если они есть) — предусмотреть исключение для первой строки.
• Скрипт не ломает форматирование критичных ячеек (при необходимости добавить резервную копию).
• Скрипт обрабатывает пустые значения и не удаляет их некорректно.
• Время выполнения для тестовой таблицы (N строк) соответствует ожиданиям команды (ручное тестирование).

Отладка: типичные ошибки и их решения

1. Скрипт падает с ошибкой «You do not have permission to call X»: проверьте, были ли предоставлены все необходимые разрешения и не используется ли простейший триггер там, где нужен installable.

2. Скрипт работает локально в редакторе, но не при запуске по триггеру: проверьте, под каким аккаунтом создан триггер и есть ли у него доступ к нужным ресурсам.

3. Ошибки при setValues: чаще всего связаны с несоответствием размеров массива и диапазона. Убедитесь, что newData.length и newData[0].length не нулевые и соответствуют диапазону.

4. Ограничение времени выполнения: разделите задачу на батчи и используйте продолжение через триггеры (ScriptApp.newTrigger(…)).

Советы по структуре проекта и управлению версиями

• Разбивайте код по файлам внутри проекта (Code.gs, Utils.gs, UI.gs, Config.gs).
• Используйте PropertiesService для хранения конфигурации (ScriptProperties / UserProperties / DocumentProperties).
• Для командной работы используйте clasp (командная утилита Google) и систему контроля версий (Git).
• Версионирование: перед публикацией создавайте новую версию проекта в меню «File» → «Manage versions».

Пример рабочего цикла с clasp:

• Инициализация: clasp create –type standalone –title “My Script”
• Работа локально, пуш: clasp push
• Тестирование и повтор.

Совместимость и миграция

• Apps Script перешёл на движок V8 — поддерживает современные возможности JavaScript (ES6+) и улучшенную производительность. Проверьте совместимость старого кода (особенно с eval/модулями).
• При миграции макросов Google Sheets в Apps Script проверьте генерируемый код и отрефакторьте повторяющиеся участки.

Короткая методология быстрого прототипирования (mini-method)

1. Определите цель: какая задача автоматизируется и какие данные задействованы.
2. Напишите минимальный рабочий пример (MWP) — 20–60 строк, который делает основную работу.
3. Запустите и проверьте права/авторизацию.
4. Добавьте логирование и обработку ошибок.
5. Оптимизируйте по производительности и безопасности.
6. Документируйте и распространите.

Примеры тест-кейсов и приёмки

Тест-кейсы для скрипта удаления дубликатов:

• Вход: таблица без дубликатов → Ожидание: таблица не изменилась.
• Вход: таблица с дубликатами в разных местах → Ожидание: все дубликаты удалены, порядок уникальных строк сохранён (если это нужно).
• Вход: таблица с заголовком → Ожидание: заголовок сохранён в верхней строке.
• Граничный случай: пустая таблица → Ожидание: скрипт завершился без ошибок.

Критерии приёмки для создающего документа скрипта:

• Документ создан и доступен у пользователя, запустившего скрипт.
• При включённой отправке почты — письмо приходит на указанный адрес с корректной ссылкой.

Публикация и политика конфиденциальности (коротко)

Если вы публикуете аддон для широкой аудитории, подготовьте страницу с политикой конфиденциальности, опишите какие данные собираете и как долго храните. Соблюдайте требования Google к OAuth verification и безопасности.

Короткая галерея крайних случаев

• Таблица с объединёнными ячейками: setValues может выбросить ошибку. Решение: разъединить ячейки, обработать данные и восстановить формат при необходимости.
• Формулы в ячейках: при чтении getValues возвращает вычисленные результаты, не формулы (для формул используйте getFormulas).
• Данные в защищённых диапазонах: скрипт не сможет изменить защищённый диапазон без соответствующих прав.

Резюме: что важно помнить

• Apps Script — быстрый путь для автоматизации Google Workspace, но он имеет ограничения по ресурсам и квотам.
• Всегда минимизируйте OAuth-разрешения и документируйте назначение скрипта.
• Для крупных, публичных или критичных систем рассматривайте облачную архитектуру (Cloud Functions/Run + Workspace API).
• Тестируйте на образцах данных, логируйте ошибки и используйте триггеры с осторожностью.

Дополнительные ресурсы

• Официальная документация Google Apps Script (script.google.com/docs)
• Репозиторий примеров и библиотек (например, GSuite Devs GitHub)
• Блоги и подборки примеров (Digital Inspiration и др.)

Короткое объявление (для рассылки или обновления)

Нужна автоматизация внутри Google Workspace? Мы подготовили подробное руководство по Google Apps Script: от создания первого автономного скрипта до развёртывания привязанных решений в Google Таблицах. В статье — пошаговые инструкции, примеры кода, чек-листы для ролей и рекомендации по безопасности.