Что такое API Google Apps Script и зачем он нужен

API Google Apps Script — это интерфейс программирования приложений, который позволяет внешним приложениям удаленно вызывать функции скриптов Apps Script, управлять проектами и развертываниями. Это открывает возможности для интеграции логики Apps Script с другими системами, автоматизации развертывания и создания более сложных рабочих процессов.

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

ChatGPT

Google AI

Grok

Perplexity

Основное назначение API — предоставить программный доступ к вашим скриптам. Например, вы можете инициировать выполнение скрипта из внешнего веб-приложения, Python-скрипта или даже другого проекта Apps Script. Это позволяет вынести сложную логику или взаимодействие с сервисами Google в Apps Script, а управлять ее вызовом извне.

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

Для работы с API Google Apps Script вам необходимы:

Аккаунт Google: Любой стандартный аккаунт Google (@gmail.com) или аккаунт Google Workspace.

Доступ к Google Apps Script: Возможность создавать и редактировать скрипты (script.google.com).

Доступ к Google Cloud Platform (GCP): Для включения самого API и управления учетными данными потребуется доступ к консоли GCP (console.cloud.google.com). Может потребоваться привязка платежного аккаунта, хотя само использование API Apps Script в большинстве случаев бесплатно в рамках стандартных квот.

Активация API Google Apps Script через Google Cloud Platform (GCP)

Этот метод необходим, если вы планируете вызывать функции Apps Script из внешних приложений.

Создание или выбор существующего проекта GCP

Любые API Google управляются через проекты Google Cloud Platform.

Перейдите в Google Cloud Console.

В верхнем меню выберите существующий проект или создайте новый, нажав на название текущего проекта и выбрав "New Project".

Укажите имя проекта и, при необходимости, организацию.

Включение API Google Apps Script в проекте GCP

После выбора или создания проекта необходимо активировать сам API.

В меню навигации (☰) выберите "APIs & Services" -> "Library".

В строке поиска введите "Google Apps Script API" и выберите его из результатов.

Нажмите кнопку "Enable". Ожидайте завершения процесса активации.

Настройка учетных данных (credentials) для доступа к API

Для взаимодействия с API вашему приложению потребуются учетные данные.

Перейдите в "APIs & Services" -> "Credentials".

Нажмите "+ CREATE CREDENTIALS".

Наиболее распространенные варианты:

OAuth 2.0 Client ID: Подходит для веб-приложений, установленных приложений или серверных приложений, которые действуют от имени пользователя (после его согласия) или от имени сервисного аккаунта.

API Key: Не подходит для вызова функций Apps Script, так как требует авторизации пользователя.

Service Account: Подходит для серверных приложений, которые действуют от своего имени, а не от имени пользователя. Требует настройки Domain-Wide Delegation, если сервисный аккаунт должен работать с данными пользователей Workspace.

При создании OAuth 2.0 Client ID выберите тип приложения (например, "Web application") и укажите необходимые URI перенаправления (Redirect URIs), куда будет отправлен код авторизации после согласия пользователя.

После создания сохраните Client ID и Client Secret (если применимо) в безопасном месте.

Разрешения (scopes) API Google Apps Script: выбор необходимых областей доступа

При запросе авторизации (OAuth 2.0) ваше приложение должно указать, к каким данным и действиям ему нужен доступ. Для API Google Apps Script основные области разрешений:

https://www.googleapis.com/auth/script.projects: Полный доступ к проектам Apps Script (создание, чтение, обновление).

https://www.googleapis.com/auth/script.deployments: Управление развертываниями (создание, чтение, обновление).

https://www.googleapis.com/auth/script.scriptapp: Запуск выполнения функций в скриптах.

https://www.googleapis.com/auth/drive: Часто требуется косвенно, так как проекты Apps Script хранятся на Google Drive.

Выбирайте минимально необходимые разрешения для вашего приложения.

Активация API Google Apps Script через Apps Script IDE

Этот раздел описывает не активацию самого Apps Script API для внешних вызовов, а подключение других API Google (как расширенных сервисов) внутри вашего скрипта Apps Script.

Открытие редактора Apps Script

Перейдите на script.google.com или откройте редактор из связанного документа (Google Sheets, Docs и т.д.) через меню "Tools" -> "Script editor".

Включение необходимых сервисов Google в редакторе Apps Script

Многие API Google доступны в Apps Script как "Advanced Google Services".

В редакторе Apps Script слева выберите "Services".

Нажмите "+ Add a service".

Найдите нужный сервис (например, Google Sheets API, Google Drive API, Google Analytics API и т.д.).

Выберите найденный сервис и нажмите "Add".

Сервис появится в списке слева. Идентификатор, указанный при добавлении (например, Sheets), будет использоваться для вызова методов этого API в коде.

Авторизация скрипта для доступа к API (выдача разрешений)

При первом запуске функции, использующей новый сервис (встроенный, требующий разрешений, или расширенный), Apps Script запросит авторизацию.

Запустите любую функцию, использующую этот сервис (например, из редактора, нажав "Run").

Появится диалоговое окно "Authorization Required". Нажмите "Review Permissions".

Выберите аккаунт Google, под которым будет выполняться скрипт.

Вы увидите экран "Google hasn’t verified this app", если скрипт не прошел верификацию (что нормально для личных скриптов). Нажмите "Advanced", затем "Go to [Имя вашего скрипта] (unsafe)".

Просмотрите список запрашиваемых разрешений и нажмите "Allow".

После этого скрипт получит OAuth-токен для доступа к указанным API от вашего имени.

Использование API Google Apps Script: Примеры и практические советы

Здесь приведены примеры использования сервисов Google внутри Apps Script после их активации (как описано в предыдущем разделе).

Пример: Получение данных из Google Sheets с использованием API

Предположим, вы включили "Google Sheets API" как расширенный сервис с идентификатором Sheets.

/**
 * Получает данные из указанного диапазона Google Таблицы,
 * используя расширенный сервис Sheets API.
 *
 * @param {string} spreadsheetId Идентификатор таблицы.
 * @param {string} range Диапазон в формате A1 (например, "Sheet1!A1:B10").
 * @returns {Array<Array> | null} Двумерный массив данных или null в случае ошибки.
 */
function getSheetDataViaAdvancedService(spreadsheetId: string, range: string): string[][] | null {
  try {
    // Вызов метода spreadsheets.values.get из Sheets API v4
    const response = Sheets.Spreadsheets.Values.get(spreadsheetId, range);
    
    if (!response || !response.values) {
      console.log('Данные не найдены или ответ пуст.');
      return null;
    }
    
    console.log(`Получено ${response.values.length} строк данных.`);
    return response.values;

  } catch (error) {
    // Обработка возможных ошибок API
    console.error(`Ошибка при получении данных из таблицы ${spreadsheetId}, диапазон ${range}: ${error}`);
    return null;
  }
}

// Пример вызова
function testGetData() {
  const SPREADSHEET_ID: string = "YOUR_SPREADSHEET_ID"; // Замените на ID вашей таблицы
  const RANGE: string = "Лист1!A1:C5";
  const data: string[][] | null = getSheetDataViaAdvancedService(SPREADSHEET_ID, RANGE);

  if (data) {
    console.log("Полученные данные:");
    console.log(JSON.stringify(data, null, 2));
  }
}

Пример: Отправка электронных писем через Gmail API

Для отправки писем чаще используется встроенный сервис GmailApp, который также требует авторизации.

/**
 * Отправляет электронное письмо с помощью сервиса GmailApp.
 *
 * @param {string} recipient Адрес получателя.
 * @param {string} subject Тема письма.
 * @param {string} body Тело письма (поддерживает HTML).
 * @param {object} [options] Дополнительные параметры (cc, bcc, attachments и т.д.).
 * @returns {boolean} true в случае успеха, false в случае ошибки.
 */
function sendEmail(recipient: string, subject: string, body: string, options?: GoogleAppsScript.Gmail.GmailAdvancedOptions): boolean {
  try {
    // Проверка наличия обязательных параметров
    if (!recipient || !subject || !body) {
      throw new Error("Получатель, тема и тело письма обязательны.");
    }

    GmailApp.sendEmail(recipient, subject, "", { // Пустая строка для plain text body
      htmlBody: body, // Используем htmlBody для форматирования
      ...(options || {}) // Добавляем опциональные параметры
    });
    
    console.log(`Письмо успешно отправлено на адрес ${recipient}.`);
    return true;

  } catch (error) {
    console.error(`Ошибка при отправке письма на ${recipient}: ${error}`);
    return false;
  }
}

// Пример вызова
function testSendEmail() {
  const recipientEmail: string = "test@example.com"; // Замените на реальный email
  const emailSubject: string = "Тестовое письмо от Apps Script";
  const emailBody: string = "
Привет!
Это тестовое письмо, отправленное с помощью Google Apps Script.
";

  const success: boolean = sendEmail(recipientEmail, emailSubject, emailBody, {
    cc: "cc@example.com",
    name: "Тестовый Отправитель" // Имя отправителя
  });

  if (success) {
    console.log("Проверка отправки завершена успешно.");
  } else {
    console.log("Проверка отправки завершена с ошибкой.");
  }
}

Обработка ошибок и отладка при работе с API

Используйте try...catch: Оборачивайте вызовы API в блоки try...catch для перехвата и обработки исключений. Логируйте ошибки с помощью console.error().

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

Логирование: Используйте Logger или console.log() для вывода промежуточных значений и отладки потока выполнения.

Квоты и лимиты: Помните о суточных квотах и ограничениях на частоту вызовов для каждого API. Изучите документацию Google по лимитам для используемых сервисов.

Отладчик Apps Script: Используйте встроенный отладчик для пошагового выполнения кода и проверки значений переменных.

Заключение и полезные ресурсы

Обзор рассмотренных способов активации API

Мы рассмотрели два основных сценария:

Активация Google Apps Script API через GCP: Необходима для внешних приложений, которым требуется удаленно управлять скриптами или запускать их функции.

Активация Advanced Google Services через Apps Script IDE: Позволяет внутри скрипта Apps Script использовать мощные API Google (Sheets, Drive, Analytics и др.) после предоставления соответствующих разрешений.

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

Дополнительные ресурсы для изучения API Google Apps Script (документация, форумы)

Официальная документация Google Apps Script API: https://developers.google.com/apps-script/api

Справочник по сервисам Apps Script: https://developers.google.com/apps-script/reference

Квоты Google Apps Script: https://developers.google.com/apps-script/guides/services/quotas

Сообщество Google Apps Script на Stack Overflow: https://stackoverflow.com/questions/tagged/google-apps-script

Официальный блог Google Workspace Developers: https://developers.googleblog.com/

Успешной автоматизации с Google Apps Script!