Google Apps Script: руководство и примеры

Иллюстрация Google Apps Script

Введение: что такое Google Apps Script

Google Apps Script (часто называют Google Script) — это платформа разработки на JavaScript-подобном языке, которая позволяет автоматизировать и расширять возможности приложений Google: Sheets, Docs, Slides, Drive, Gmail, Calendar, Forms и других. Ключевая идея: один редактор в облаке и глобальные объекты для каждого сервиса (например, GmailApp, SpreadsheetApp), через которые вы вызываете API и выполняете задачи.

Определение в 1 строке: Google Apps Script — это серверный скриптовый движок от Google для автоматизации задач внутри экосистемы Google Workspace.

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

Что можно автоматизировать и интегрировать

Ниже — перечисление наиболее практичных сценариев использования:

Создание пользовательских функций для Google Sheets (как формулы).
Интеграция Google Sheets или Docs с Gmail для отправки массовых писем или уведомлений.
Создание веб-приложений и диалоговых окон, развёртываемых как веб-страницы или встраиваемые в Google Sites.
Добавление пользовательского меню в Google Docs/Sheets.
Построение дашбордов трафика в Google Sheets на основе данных Google Analytics.
Автоматическое архивирование, маркировка и управление письмами в Gmail.
Триггерное выполнение по расписанию (Cron-подобно) или по событиям (onEdit, onOpen и др.).

Это неполный список: платформа гибкая и масштабируется от простых макросов до сложных интеграций с внешними API.

Ваш первый Google Apps Script — пошаговая инструкция

Ниже — упрощённая и исправленная последовательность действий для создания «Hello World», который отправляет письмо через Gmail.

Откройте браузер и перейдите на адрес script.google.com
Войдите в ваш Google аккаунт, если ещё не вошли.
Нажмите «Новый проект» или «New script».
В поле с названием проекта, где написано «Untitled project», введите имя «My First Script».
Удалите весь код из основного окна редактора.
Вставьте следующий код (это Google Apps Script, JavaScript-подобный синтаксис):

function SendAnEmail() {
  // Установите адрес получателя
  var email = 'xxxxx@yahoo.com';

  // Тема письма
  var subject = 'This is my first script!';

  // Текст письма
  var body = 'Hello, world!';

  // Отправка письма через Gmail
  GmailApp.sendEmail(email, subject, body);
}

Нажмите на значок дискеты или выберите «File → Save», чтобы сохранить проект.
Нажмите на кнопку «Run» (Запустить). При первом запуске появится окно с просьбой предоставить разрешения. Подтвердите от имени своего аккаунта и разрешите доступ к Gmail, если потребуется.

Примечание: при первом запуске вы можете увидеть предупреждение о том, что приложение не прошло проверку. Нажмите «Дополнительно» и затем «Перейти к My First Script (unsafe)», чтобы продолжить — это нормальная практика для пользовательских скриптов, которые вы написали сами.

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

Скриншот письма, отправленного через Google Script

Этот пример использует глобальный объект GmailApp для отправки почты — так же работают SpreadsheetApp, DocumentApp, DriveApp и другие.

Работа с редактором скриптов в Google Sheets и Docs

Редактор скриптов встроен в сервисы Google Workspace и доступен из меню: в Google Sheets выберите Инструменты → Редактор сценариев (Tools → Script editor).

Редактор скриптов в Google Sheets

Вы можете добавлять пользовательские функции, меню, боковые панели и диалоги, использовать триггеры onOpen/onEdit и привязывать скрипты к конкретным таблицам или использовать их как централизованные библиотечные скрипты.

Gmail Add-ons и разработка расширений для Gmail

С помощью Google Apps Script можно создавать надстройки для Gmail, которые изменяют окно составления сообщения, показывают доп. панели или автоматизируют обработку входящих писем. Для разработки надстроек включите в Gmail поддержку разработческих надстроек:

Откройте Gmail → Настройки (Settings).
Перейдите в раздел Надстройки (Add-ons).
Выберите «Enable developer add-ons for my account» и подтвердите действие.

Включение разработческих надстроек Gmail в настройках

Создание полноценной надстройки требует изучения официального руководства по созданию Gmail add-on и OAuth-авторизации для доступа к данным пользователя.

Advanced Google Services и Google Cloud Platform (GCP)

Чтобы использовать расширенные API (например, библиотеку Google Analytics API), выполните две операции:

В редакторе скриптов откройте меню «Resources → Advanced Google services» и активируйте нужный сервис.
В том же окне нажмите ссылку Google Cloud Platform API Dashboard, где нужно включить соответствующий API в консоли GCP: «Enable APIs and Services», найдите нужный API в библиотеке и нажмите «Enable».

Окно Advanced Google services в редакторе скриптов

Не забудьте сохранить ссылку на Reference documentation для выбранного API — там примеры вызовов и синтаксис, которые пригодятся при интеграции.

Включение API Google Analytics в Google Cloud Platform

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

Список API сервисов Google в библиотеке API

Пример: интеграция Google Analytics → Google Sheets

Классический сценарий — периодическое извлечение метрик трафика из Google Analytics и формирование дашборда в Google Sheets.

Мини-алгоритм:

Включить Google Analytics API в GCP и в Advanced Google services.
Создать в Google Sheets новый лист с колонками: Дата, Сессии, Просмотры, Источник.
Написать скрипт, который через Analytics API делает запросы, парсит ответ и записывает строки в таблицу.
Настроить триггер ежесуточного запуска скрипта.

Преимущество: отчёт автоматически обновляется, данные доступны в привычной табличной форме и легко визуализируются встроенными диаграммами Sheets.

Методология проектирования скриптов (мини‑метод)

Цель: чётко опишите, какую задачу автоматизируете и какие сервисы вовлечены.
Доступы: определите, какие разрешения нужны (Gmail, Drive, Analytics) и минимизируйте права.
Прототип: начните с одного сценария и локального теста.
Триггеры: выберите режим запуска — пользовательский, триггер или веб‑hook.
Логирование и мониторинг: используйте Logger.log и сохранение ошибок в отдельный лист или Cloud Logging.
Тесты и приёмка: разработайте набор тестовых данных и критериев приёмки.
Развертывание: сохраните версию проекта и продеплойте как web app или add-on при необходимости.
Документация: краткое README с описанием назначений, триггеров и необходимых прав.

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

Скрипт выполняет основную задачу без ошибок для стандартного набора данных.
Все требуемые разрешения оформлены и задокументированы.
Логи ошибок доступны и понятны.
При изменении входных параметров поведение соответствует описанию в README.
Нет утечек персональных данных beyond scope.

Роль‑ориентированные чеклисты

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

Локально протестирован основной сценарий.
Написаны минимальные проверки ошибок.
Добавлены комментарии к функциям и использованным API.

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

Проверены права доступа и OAuth‑клиенты.
Включены нужные API в GCP.
Назначены ответственные за мониторинг.

Чеклист для конечного пользователя:

Понял, какие данные скрипт использует.
Согласился на необходимые разрешения.
Получил инструкцию по запуску и отчетам.

Тестовые сценарии и приёмочные тесты

Тестовые случаи для примера с отправкой почты:

Тест 1: валидный e‑mail → письмо отправлено, в логах — статус OK.
Тест 2: некорректный e‑mail → скрипт валидирует адрес и записывает ошибку.
Тест 3: превышение квот Gmail → скрипт ловит исключение и уведомляет админа.

Критерии приёмки: письма доставляются, ошибки обрабатываются, лог содержит таймстампы.

SOP для развертывания и rollback

SOP — краткий план развертывания:

Создайте версию проекта в редакторе скриптов.
Протестируйте версию на тестовой учётной записи.
Обновите триггеры (если требуется).
Документируйте изменения в CHANGELOG.

Rollback:

Откатить на предыдущую сохранённую версию в редакторе скриптов и пересоздать триггеры.

Матрица рисков и меры снижения

Риск: Утечка персональных данных → Митигирование: минимизировать права, шифрование получаемых данных, логирование с маскированием.
Риск: Превышение квот API → Митигирование: добавить повторные попытки с экспоненциальной задержкой, следить за использованием в GCP.
Риск: Непроверенные внешние данные → Митигирование: валидация входа и sanitization.

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

Доступы: используйте OAuth с минимумом прав.
Логи: не сохраняйте персональные данные в открытом виде.
Согласие: уведомляйте пользователей, если скрипт обрабатывает их данные.
Хранение: если вы выгружаете данные за пределы Google, убедитесь, что это соответствует правилам компании и законам о защите данных.

Важно: если скрипт используется в корпоративной среде, согласуйте его с администратором Google Workspace и службой безопасности.

Когда Google Apps Script не годится — ограничения и альтернативы

Ограничения:

Квоты выполнения и лимиты Google Apps Script.
Ограничения на время выполнения (скрипт не должен работать бесконечно).
Сложности с очень высокими нагрузками и параллельностью.

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

Для тяжёлых ETL‑задач: использовать Cloud Functions, Cloud Run или собственные серверы.
Для сложных интеграций с большим количеством параллельных вызовов — строить микросервисы на GCP.

Полезные сниппеты и «cheat sheet»

Вставка данных в активный лист:

function appendRowExample() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  sheet.appendRow(['Дата', new Date(), 'Комментарий']);
}

Получение содержимого документа Google Docs:

function readDoc() {
  var doc = DocumentApp.openById('DOCUMENT_ID');
  var body = doc.getBody().getText();
  Logger.log(body);
}

Создание временного триггера на часовой интервал:

function createHourlyTrigger() {
  ScriptApp.newTrigger('SendAnEmail')
    .timeBased()
    .everyHours(1)
    .create();
}

Модель зрелости использования Apps Script (уровни)

Уровень 1 — макросы и одноразовые автоматизации.
Уровень 2 — регулярно запускаемые скрипты с логированием и базовой обработкой ошибок.
Уровень 3 — интеграции с Advanced Google Services и внешними API, тестирование и CI.
Уровень 4 — корпоративные надстройки и многоуровневая архитектура с мониторингом и SLA.

Лучшие практики и рекомендации

Используйте именованные функции и модульную структуру.
Логируйте ключевые события и ошибки.
Минимизируйте права OAuth.
Версионируйте проект перед прод‑выпуском.
Тестируйте на тестовой учётной записи, чтобы не нарушить рабочие данные.

Короткий глоссарий

Apps Script: платформа для скриптов Google.
Advanced Google services: дополнительные API, активируемые в редакторе и GCP.
GCP: Google Cloud Platform, консоль управления API и квотами.
OAuth: протокол авторизации, позволяющий скриптам получать доступ к данным пользователя.

Заключение и следующие шаги

Google Apps Script — быстрый путь от идеи до автоматизации в экосистеме Google. Начните с простого примера отправки письма, затем поэтапно подключайте Advanced APIs и выстраивайте тесты и мониторинг. Если хотите попробовать следующий шаг, реализуйте интеграцию Google Forms → Gmail: автоматическое чтение ответов формы и отправка персонализированного письма-ответа.

Важно: при переходе от прототипа к продакшену уделите внимание безопасности, квотам и документации.

Краткая сводка действий для старта: