Что такое исполняемый файл Google Apps Script и зачем он нужен?
Исполняемый файл Google Apps Script – это развернутая версия вашего скрипта, доступная для выполнения вне редактора скриптов. Он позволяет запускать функции в вашем Apps Script проекте из внешних приложений или сервисов, предоставляя программный интерфейс (API) к вашему скрипту. Это полезно для автоматизации задач, интеграции с другими системами и создания веб-сервисов.
Обзор возможностей API исполняемого файла
API исполняемого файла предоставляет следующие основные возможности:
- Запуск функций: Позволяет запускать определенные функции в вашем Apps Script проекте, передавая параметры и получая результаты.
- Аутентификация и авторизация: Обеспечивает безопасный доступ к вашему скрипту, используя OAuth 2.0 для аутентификации и авторизации.
- Управление развертываниями: Позволяет управлять развертываниями вашего скрипта, создавая новые версии и управляя доступом.
Когда следует использовать API исполняемого файла вместо других подходов
API исполняемого файла особенно полезен в следующих сценариях:
- Интеграция с внешними системами: Когда необходимо интегрировать Google Apps Script с другими приложениями или сервисами.
- Автоматизация задач по расписанию: Когда требуется запускать скрипт автоматически по расписанию, например, из cron-задания.
- Создание веб-сервисов: Когда нужно предоставить доступ к функциям вашего скрипта через HTTP API.
- Делегирование прав доступа: Когда нужно дать возможность другому пользователю запускать скрипт от вашего имени, без предоставления полного доступа к Google аккаунту.
Настройка проекта Google Cloud Platform для доступа к API
Создание проекта GCP и включение API Apps Script Execution API
Для использования API исполняемого файла необходимо создать проект в Google Cloud Platform (GCP) и включить API Apps Script Execution API.
- Перейдите в Google Cloud Console.
- Создайте новый проект или выберите существующий.
- В консоли GCP найдите «API и сервисы» и перейдите в раздел «Библиотека».
- Найдите «Apps Script Execution API» и включите его.
Настройка экрана запроса согласия OAuth (OAuth consent screen)
Перед использованием API необходимо настроить экран запроса согласия OAuth. Это необходимо для того, чтобы пользователи знали, какие разрешения запрашивает ваше приложение.
- В консоли GCP найдите «API и сервисы» и перейдите в раздел «Экран запроса согласия OAuth».
- Выберите тип пользователя («Внутренний» для тестирования внутри организации или «Внешний» для публичного использования).
- Заполните информацию о вашем приложении: название, адрес электронной почты, логотип (опционально).
- Укажите области действия (scopes), которые ваше приложение будет запрашивать (например,
https://www.googleapis.com/auth/script.execute).
Создание учетных данных (credentials) для приложения: OAuth 2.0 Client ID
Для аутентификации необходимо создать учетные данные OAuth 2.0.
- В консоли GCP найдите «API и сервисы» и перейдите в раздел «Учетные данные».
- Нажмите «Создать учетные данные» и выберите «OAuth client ID».
- Выберите тип приложения (например, «Веб-приложение» или «Приложение для рабочего стола»).
- Укажите разрешенные URI перенаправления (redirect URIs) для веб-приложений или URI перенаправления для приложений для рабочего стола.
- Сохраните Client ID и Client Secret.
Включение API Apps Script API
Убедитесь, что API Apps Script API также включен в вашем проекте GCP, аналогично Apps Script Execution API. Это необходимо для управления развертываниями.
Авторизация и аутентификация для доступа к API
Получение токена доступа OAuth 2.0
Для доступа к API исполняемого файла необходимо получить токен доступа OAuth 2.0. Процесс получения токена зависит от типа вашего приложения. Для веб-приложений обычно используется Authorization Code Grant flow.
Пример (abstract):
/**
* @param {string} clientId
* @param {string} clientSecret
* @param {string} authorizationCode
* @returns {Promise<string>} - Access token
*/
async function getAccessToken(clientId: string, clientSecret: string, authorizationCode: string): Promise<string> {
const tokenEndpoint = 'https://oauth2.googleapis.com/token';
const params = new URLSearchParams();
params.append('client_id', clientId);
params.append('client_secret', clientSecret);
params.append('code', authorizationCode);
params.append('grant_type', 'authorization_code');
params.append('redirect_uri', 'YOUR_REDIRECT_URI');
const response = await fetch(tokenEndpoint, {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
},
body: params.toString(),
});
const data = await response.json();
return data.access_token;
}
Использование токена доступа в запросах к API
Токен доступа необходимо включать в заголовок Authorization каждого запроса к API.
Authorization: Bearer YOUR_ACCESS_TOKEN
Обновление токена доступа (refresh token)
Токены доступа обычно имеют ограниченный срок действия. Для получения нового токена необходимо использовать refresh token. Процесс обновления токена аналогичен получению первоначального токена, но вместо authorization code используется refresh token.
Разрешения (Scopes) необходимые для различных операций
Необходимые разрешения (scopes) зависят от того, какие операции вы хотите выполнять. Основные scopes:
https://www.googleapis.com/auth/script.execute: Для запуска функций.https://www.googleapis.com/auth/script.deployments: Для управления развертываниями.https://www.googleapis.com/auth/script.projects: Для управления проектами.
Использование API исполняемого файла для запуска функций
Создание развертывания (deployment) исполняемого файла
Перед запуском функций необходимо создать развертывание исполняемого файла. Это можно сделать через редактор скриптов или через API.
Отправка запроса на выполнение функции (projects.run)
Для запуска функции необходимо отправить POST-запрос к endpoint https://script.googleapis.com/v1/projects/{scriptId}:run, где {scriptId} – это ID вашего скрипта.
/**
* @param {string} scriptId
* @param {string} functionName
* @param {any[]} parameters
* @param {string} accessToken
* @returns {Promise<any>}
*/
async function runAppsScriptFunction(scriptId: string, functionName: string, parameters: any[], accessToken: string): Promise<any> {
const endpoint = `https://script.googleapis.com/v1/projects/${scriptId}:run`;
const payload = {
function: functionName,
parameters: parameters,
};
const response = await fetch(endpoint, {
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
const data = await response.json();
if (data.error) {
throw new Error(data.error.message);
}
return data.response.result;
}
Передача параметров в функцию
Параметры функции передаются в массиве parameters в теле запроса. Типы параметров должны быть совместимы с типами параметров в вашей Apps Script функции.
Обработка результатов выполнения функции и ошибок
Результат выполнения функции возвращается в поле response.result в ответе API. В случае ошибки, информация об ошибке возвращается в поле error.
Примеры использования и лучшие практики
Пример: Запуск скрипта для обработки данных из внешнего источника
Предположим, у вас есть Apps Script, который обрабатывает данные из внешнего API. Вы можете использовать API исполняемого файла для запуска этого скрипта из cron-задания.
// Cron job (abstract)
const scriptId = 'YOUR_SCRIPT_ID';
const functionName = 'processExternalData';
const parameters = ["some_external_api_url"];
const accessToken = 'YOUR_ACCESS_TOKEN';
try {
const result = await runAppsScriptFunction(scriptId, functionName, parameters, accessToken);
console.log('Result:', result);
} catch (error) {
console.error('Error:', error);
}
Пример: Интеграция с веб-приложением для автоматизации задач
Вы можете интегрировать API исполняемого файла с веб-приложением для автоматизации задач, например, для создания отчетов или отправки электронных писем.
Советы по обеспечению безопасности при использовании API
- Ограничьте разрешения (scopes): Предоставляйте только те разрешения, которые необходимы для выполнения конкретной задачи.
- Храните учетные данные в безопасном месте: Не храните Client ID и Client Secret в открытом виде в коде.
- Проверяйте входящие данные: Всегда проверяйте данные, полученные от внешних источников, перед их использованием в скрипте.
- Используйте безопасные методы аутентификации: Используйте OAuth 2.0 для аутентификации и авторизации.
Оптимизация производительности и обработка ошибок
- Оптимизируйте код Apps Script: Убедитесь, что ваш код Apps Script работает быстро и эффективно.
- Обрабатывайте ошибки: Добавьте обработку ошибок в ваш код Apps Script и в код, который вызывает API.
- Используйте асинхронные вызовы: Используйте асинхронные вызовы для выполнения длительных операций, чтобы не блокировать основной поток выполнения.