Развертывание скриптов Google Apps Script: Полное руководство

Что такое Google Apps Script и зачем его развертывать?

Google Apps Script (GAS) — это облачная платформа для разработки на JavaScript, позволяющая расширять функциональность приложений Google Workspace (Sheets, Docs, Drive, Gmail и др.) и создавать автоматизированные рабочие процессы. Изначально скрипты работают только в среде разработки и доступны лишь автору.

Саммари статьи

ChatGPT

Google AI

Grok

Perplexity

Развертывание — это процесс публикации скрипта, делающий его доступным для других пользователей или систем в контролируемом режиме. Без развертывания скрипт остается инструментом для личного пользования, неспособным служить веб-приложением, API или дополнением.

Обзор различных типов развертываний (веб-приложения, API, дополнения)

Существует несколько основных способов развертывания скриптов GAS:

• Веб-приложение: Скрипт становится доступным по уникальному URL и может генерировать HTML-интерфейсы или обрабатывать HTTP-запросы (GET/POST). Подходит для создания интерактивных инструментов, дашбордов, форм.
• API Executable: Скрипт предоставляет программный интерфейс (API), который могут вызывать другие приложения (веб-сервисы, мобильные приложения) для выполнения функций скрипта и обмена данными. Использует стандартные методы аутентификации и авторизации.
• Дополнение Google Workspace (Add-on): Интегрирует функциональность скрипта непосредственно в интерфейс приложений Google Workspace (например, боковая панель в Google Sheets). Распространяется через Google Workspace Marketplace.
• Библиотека (Library): Позволяет повторно использовать код одного скрипта в других скриптах GAS. Хотя это не развертывание в классическом смысле, управление версиями библиотек схоже с процессом развертывания.

Необходимые условия для развертывания скрипта

• Google Аккаунт: Для создания и управления скриптами.
• Проект Google Apps Script: Скрипт, который вы планируете развернуть.
• Понимание областей действия (Scopes): Необходимо определить, к каким данным и сервисам Google скрипт будет запрашивать доступ.
• Настроенный проект Google Cloud Platform (GCP) (опционально, но часто необходимо): Требуется для расширенных сценариев, таких как использование API Executable, управление OAuth-клиентами для дополнений и веб-приложений с определенными настройками доступа.

Развертывание скрипта как веб-приложения

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

Создание нового развертывания веб-приложения

1. Откройте редактор скриптов.
2. В правом верхнем углу нажмите Развертывание > Новое развертывание.
3. Выберите тип развертывания: Веб-приложение.

Настройка параметров развертывания (доступ пользователей, версии)

При создании развертывания необходимо настроить:

• Описание (необязательно): Помогает идентифицировать развертывание.
• Веб-приложение:
  • Выполнять как:
    • Я (ваш email@gmail.com): Скрипт всегда выполняется от вашего имени, используя ваши разрешения. Пользователям не нужно авторизовать скрипт, но все действия (изменение файлов, отправка писем) будут выполняться от вашего аккаунта.
    • Пользователь, обращающийся к веб-приложению: Каждый пользователь должен будет авторизовать скрипт при первом доступе. Скрипт выполняется от имени текущего пользователя.
  • Доступ:
    • Только я: Доступно только вам.
    • Все пользователи в домене .com: Доступно только пользователям вашего Google Workspace домена (требуется авторизация).
    • Все: Доступно любому пользователю в интернете (анонимно или с авторизацией Google, в зависимости от настройки «Выполнять как»).

Права доступа и авторизация скрипта

Скрипт запрашивает разрешения (scopes) при первой авторизации пользователем (если выбрано «Выполнять как: Пользователь…») или при первом запуске развертывания (если «Выполнять как: Я»). Важно запрашивать только необходимые разрешения.

Публикация веб-приложения и получение URL

После настройки параметров нажмите Развернуть. Система сгенерирует уникальный URL для вашего веб-приложения. Этот URL используется для доступа к приложению.

Пример простого веб-приложения для отображения данных из Google Sheets:

/**
 * Идентификатор таблицы Google Sheets с данными.
 * @type {string}
 */
const SPREADSHEET_ID = 'YOUR_SPREADSHEET_ID';

/**
 * Имя листа с данными.
 * @type {string}
 */
const SHEET_NAME = 'CampaignData';

/**
 * Обрабатывает GET-запросы к веб-приложению.
 * @param {GoogleAppsScript.Events.DoGet} e - Объект события GET-запроса.
 * @returns {GoogleAppsScript.HTML.HtmlOutput} HTML-страница.
 */
function doGet(e: GoogleAppsScript.Events.DoGet): GoogleAppsScript.HTML.HtmlOutput {
  try {
    const ss = SpreadsheetApp.openById(SPREADSHEET_ID);
    const sheet = ss.getSheetByName(SHEET_NAME);
    if (!sheet) {
      throw new Error(`Лист с именем '${SHEET_NAME}' не найден.`);
    }
    const data = sheet.getDataRange().getDisplayValues();

    // Пропускаем заголовок
    const campaigns = data.slice(1);

    let html = '<h1>Список Рекламных Кампаний</h1><ul>';
    campaigns.forEach(row => {
      // Предполагаем, что название кампании в первом столбце
      if (row[0]) { 
        html += `<li>${row[0]}</li>`;
      }
    });
    html += '</ul>';

    return HtmlService.createHtmlOutput(html)
      .setTitle('Данные Кампаний');

  } catch (error) {
    Logger.log(`Ошибка в doGet: ${error.message}`);
    return HtmlService.createHtmlOutput(`<p>Произошла ошибка: ${error.message}</p>`);
  }
}

Обновление и управление версиями веб-приложения

При внесении изменений в код скрипта существующее развертывание не обновляется автоматически. Чтобы применить изменения:

1. Перейдите в Развертывание > Управление развертываниями.
2. Выберите активное развертывание и нажмите на значок карандаша (Редактировать).
3. В выпадающем списке Версия выберите Новая версия.
4. Нажмите Развернуть.

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

Устранение неполадок при развертывании веб-приложения

• Проверка журналов: Используйте Logger.log() или console.log() в коде и проверяйте логи выполнения в редакторе скриптов (Выполнения).
• Права доступа: Убедитесь, что настройки доступа («Доступ») и выполнения («Выполнять как») соответствуют вашим требованиям. Проверьте, авторизован ли скрипт с нужными областями.
• Ошибки кода: Отлаживайте функции doGet(e) и doPost(e) локально в редакторе, передавая тестовые объекты событий e.
• Квоты Google Apps Script: Веб-приложения имеют ограничения на время выполнения, количество запросов и т.д.

Развертывание скрипта в качестве API (endpoint)

Позволяет внешним системам взаимодействовать с вашим скриптом программно.

Подготовка скрипта для использования в качестве API

Функции, которые вы хотите сделать доступными через API, должны принимать параметры и возвращать данные в формате, понятном вызывающей системе (часто JSON).

Пример функции для API, возвращающей данные кампании по ID:

«`javascript
/**

• Возвращает метрики для указанной рекламной кампании.
• @param {string} campaignId Идентификатор кампании.
• @returns {object | null} Объект с данными кампании или null, если не найдено.
  */
  function getCampaignMetrics(campaignId: string): { id: string; name: string; clicks: number; ctr: number } | null {
  // Здесь должна быть логика получения данных, например, из Google Ads API или Google Sheet
  // Для примера вернем заглушку
  if (campaignId === ‘cmp-123’) {
  return {
  id: campaignId,
  name: ‘Тестовая кампания’,
  clicks: 1500,
  ctr: 0.05
  };
  } else {
  return null;
  }
  }

// Функции doPost и doGet могут служить точками входа для API

/**

• Обрабатывает POST-запросы к API.

• @param {GoogleAppsScript.Events.DoPost} e Объект события POST-запроса.

• @returns {GoogleAppsScript.Content.TextOutput} Ответ в формате JSON.
  */
  function doPost(e: GoogleAppsScript.Events.DoPost): GoogleAppsScript.Content.TextOutput {
  try {
  const params = JSON.parse(e.postData.contents);
  const campaignId = params.campaignId;

  if (!campaignId || typeof campaignId !== ‘string’) {
  throw new Error(‘Параметр