Что такое развертывание Google Apps Script и зачем оно нужно?

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

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

ChatGPT

Google AI

Grok

Perplexity

Развертывание необходимо для:

Расширения функциональности Google Workspace: Создание дополнений для Google Docs, Sheets, Slides и Forms.

Автоматизации бизнес-процессов: Развертывание веб-приложений для управления данными, создания отчетов или интеграции с CRM системами.

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

Создания пользовательских интерфейсов: Развертывание веб-приложений для сбора данных или отображения информации.

Основные типы развертываний: веб-приложения, API Executable и дополнения

Существует три основных типа развертываний Google Apps Script:

Веб-приложения: Скрипты, доступные через URL-адрес. Они могут отображать HTML-страницы, обрабатывать формы и взаимодействовать с пользователем.

API Executable: Скрипты, доступные через Google Cloud Platform (GCP) API. Они позволяют вызывать функции скрипта из других приложений или сервисов.

Дополнения (Add-ons): Скрипты, интегрированные в Google Workspace приложения (Docs, Sheets, Slides, Forms). Они добавляют новые функции и возможности в эти приложения.

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

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

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

Доступ к Google Apps Script: Убедитесь, что у вас есть доступ к редактору Google Apps Script.

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

Рабочий код: Убедитесь, что скрипт работает корректно и не содержит ошибок.

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

Создание и настройка функции doGet/doPost

Для развертывания скрипта как веб-приложения необходимо создать как минимум одну из функций doGet(e) или doPost(e). Функция doGet(e) вызывается, когда пользователь открывает URL-адрес веб-приложения через GET-запрос. Функция doPost(e) вызывается, когда пользователь отправляет данные на URL-адрес веб-приложения через POST-запрос. Параметр e содержит информацию о запросе, такую как параметры URL или данные формы.

Пример функции doGet(e):

/**
 * @param {GoogleAppsScript.Events.DoGet} e The event object representing the HTTP GET request.
 * @return {GoogleAppsScript.HTML.HtmlOutput} The HTML service output.
 */
function doGet(e: GoogleAppsScript.Events.DoGet): GoogleAppsScript.HTML.HtmlOutput {
  // Создание HTML-страницы
  const output = HtmlService.createHtmlOutput('
Привет, мир!
');

  // Обработка параметров запроса
  if (e.parameter.name) {
    output.append('
Привет, ' + e.parameter.name + '!
');
  }

  return output;
}

Публикация скрипта как веб-приложения: пошаговая инструкция

Откройте скрипт в редакторе Google Apps Script.

Нажмите "Развернуть" (Deploy) -> "Новое развертывание" (New deployment).

Выберите тип развертывания "Веб-приложение" (Web app).

Укажите описание (Description).

Выберите, от имени кого будет запускаться приложение ("Execute as").

Выберите, кто будет иметь доступ к приложению ("Who has access").

Нажмите "Развернуть" (Deploy).

Скопируйте URL-адрес веб-приложения.

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

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

Только я (Only myself): Только вы сможете запускать приложение.

Все, у кого есть аккаунт Google (Anyone with a Google account): Любой пользователь с аккаунтом Google сможет запускать приложение.

Все (Anyone): Любой пользователь в Интернете сможет запускать приложение, даже без аккаунта Google. Внимание: данный пункт доступен только, если запуск происходит от имени пользователя, а не сервиса.

Рекомендуется ограничивать доступ к веб-приложению только тем пользователям, которым оно действительно необходимо. Предоставление доступа "Всем" может представлять угрозу безопасности.

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

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

Чтобы создать новую версию:

Внесите изменения в скрипт.

Нажмите "Развернуть" -> "Управление развертываниями" (Manage deployments).

Найдите активное развертывание и нажмите "Редактировать" (Edit).

В поле "Версия" (Version) выберите "Новая версия" (New version) и укажите описание изменений.

Нажмите "Развернуть" (Deploy).

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

Развертывание Google Apps Script как API Executable

Включение API Apps Script и создание проекта Google Cloud Platform (GCP)

Для развертывания скрипта как API необходимо включить API Apps Script в Google Cloud Platform (GCP) и создать проект GCP, если его еще нет.

Перейдите в Google Cloud Console (console.cloud.google.com).

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

Включите API Apps Script: перейдите в "API и сервисы" -> "Библиотека" (APIs & Services -> Library), найдите "Apps Script API" и нажмите "Включить" (Enable).

Настройка авторизации и разрешений для доступа к API

Для доступа к API необходимо настроить авторизацию и разрешения. Это можно сделать с помощью OAuth 2.0.

В Google Cloud Console перейдите в "API и сервисы" -> "Учетные данные" (APIs & Services -> Credentials).

Создайте учетные данные OAuth 2.0: выберите "Создать учетные данные" (Create credentials) -> "Идентификатор клиента OAuth" (OAuth client ID).

Выберите тип приложения (например, "Веб-приложение") и укажите URI перенаправления (Redirect URI).

Получите идентификатор клиента (Client ID) и секрет клиента (Client Secret).

Вызов функций Google Apps Script через API: примеры кода на разных языках

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

Пример вызова функции на Python:

from googleapiclient.discovery import build
from google.oauth2 import credentials

# Учетные данные OAuth 2.0
creds = credentials.Credentials.from_authorized_user_file('token.json', ['https://www.googleapis.com/auth/script.execute'])

# Создание сервиса Apps Script API
service = build('script', 'v1', credentials=creds)

# Параметры запроса
script_id = 'YOUR_SCRIPT_ID'
function_name = 'YOUR_FUNCTION_NAME'
params = {
    'function': function_name,
    'parameters': ['param1', 'param2']
}

# Вызов функции
request = service.scripts().run(scriptId=script_id, body=params)
response = request.execute()

# Обработка ответа
if 'error' in response:
    print(response['error'])
else:
    print(response['response']['result'])

Замените YOUR_SCRIPT_ID и YOUR_FUNCTION_NAME на соответствующие значения. Также, нужно предварительно получить token.json через процесс авторизации OAuth 2.0.

Ограничения и лучшие практики при использовании API Executable

Квоты: Существуют ограничения на количество запросов к API Apps Script. Ознакомьтесь с документацией Google Cloud Platform для получения актуальной информации о квотах.

Авторизация: Правильно настройте авторизацию и разрешения для доступа к API. Используйте OAuth 2.0 для безопасной аутентификации.

Обработка ошибок: Реализуйте обработку ошибок в коде, чтобы корректно обрабатывать возможные сбои при вызове API.

Логирование: Добавьте логирование для отслеживания выполнения скриптов и выявления проблем.

Развертывание Google Apps Script как дополнения (Add-on)

Разработка манифеста дополнения (appsscript.json)

Для развертывания скрипта как дополнения необходимо создать манифест дополнения – файл appsscript.json. Этот файл содержит метаданные о дополнении, такие как название, описание, иконка, разрешения и точки входа.

Пример файла appsscript.json:

{
  "timeZone": "Etc/GMT",
  "dependencies": {},
  "webapp": {
    "access": "ANYONE",
    "executeAs": "USER_DEPLOYING"
  },
  "oauthScopes": [
    "https://www.googleapis.com/auth/spreadsheets",
    "https://www.googleapis.com/auth/documents.readonly"
  ],
  "addOns": {
    "common": {
      "name": "My Add-on",
      "logoUrl": "https://example.com/logo.png",
      "homepageUrl": "https://example.com"
    },
    "docs": {
      "onOpen": {
        "functionName": "onOpenDoc",
        "enabled": true
      },
      "onInstall": {
        "functionName": "onInstall",
        "enabled": true
      },
      "menu": [
        {
          "name": "Insert Date",
          "functionName": "insertDate"
        }
      ]
    }
  },
  "exceptionLogging": "STACKDRIVER"
}

Тестирование дополнения в режиме разработчика

Перед публикацией дополнения необходимо протестировать его в режиме разработчика. Для этого:

Откройте Google Workspace приложение (Docs, Sheets, Slides, Forms).

Перейдите в "Инструменты" -> "Редактор скриптов" (Tools -> Script editor).

Откройте манифест (appsscript.json).

В редакторе Google Apps Script выберите "Развернуть" (Deploy) -> "Тестовые развертывания" (Test deployments).

Выберите версию для тестирования и установите дополнение в выбранном Google Workspace приложении.

Процесс публикации дополнения в Google Workspace Marketplace

После тестирования дополнения можно опубликовать его в Google Workspace Marketplace. Для этого необходимо:

Подготовить описание дополнения, скриншоты и видео.

Проверить, что дополнение соответствует требованиям Google Workspace Marketplace.

Создать проект Google Cloud Platform (GCP) и связать его с дополнением.

Заполнить форму публикации в Google Cloud Console.

Отправить дополнение на проверку в Google.

Рекомендации по созданию качественного и полезного дополнения

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

Простой и интуитивно понятный интерфейс: Интерфейс дополнения должен быть простым и интуитивно понятным.

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

Поддержка: Обеспечьте поддержку пользователей и отвечайте на вопросы.

Безопасность: Убедитесь, что дополнение безопасно и не содержит вредоносного кода.

Управление и отладка развернутых Google Apps Script

Мониторинг выполнения скриптов и логирование ошибок

Для мониторинга выполнения скриптов и логирования ошибок можно использовать Stackdriver Logging. Stackdriver Logging позволяет записывать информацию о выполнении скриптов, ошибки и отладочные сообщения.

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

/**
 * @param {string} message The message to log.
 * @return {void}
 */
function logMessage(message: string): void {
  Logger.log(message);
  console.log(message);
}

try {
  // Код, который может вызвать ошибку
  SpreadsheetApp.getActiveSpreadsheet().getSheetByName('NonExistentSheet').activate();
} catch (e) {
  // Логирование ошибки
  logMessage('Произошла ошибка: ' + e.message);
}

Использование Stackdriver Logging для отладки

Stackdriver Logging предоставляет возможности для фильтрации и поиска логов. Вы можете фильтровать логи по уровню серьезности (например, INFO, WARNING, ERROR), по времени, по имени скрипта и другим параметрам.

Для просмотра логов Stackdriver Logging перейдите в Google Cloud Console и выберите "Logging" -> "Log Explorer".

Практические советы по устранению распространенных проблем при развертывании

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

Проверьте код: Убедитесь, что код работает корректно и не содержит ошибок. Используйте отладчик Google Apps Script для поиска ошибок.

Проверьте квоты: Убедитесь, что не превышены квоты на использование API Apps Script.

Проверьте конфигурацию развертывания: Убедитесь, что правильно настроены параметры развертывания, такие как доступ и от имени кого запускать приложение.

Отзыв и обновление развертываний: как правильно вносить изменения

Чтобы отозвать развертывание, перейдите в "Развернуть" -> "Управление развертываниями" (Manage deployments), найдите нужное развертывание и нажмите "Удалить" (Delete).

При внесении изменений в скрипт необходимо создать новую версию развертывания, как описано выше. Не рекомендуется вносить изменения непосредственно в активное развертывание, так как это может привести к нестабильной работе приложения. Всегда создавайте новую версию для внесения изменений.