Что такое Google Apps Script и зачем нужен API?
Google Apps Script (GAS) – это облачная платформа разработки, позволяющая автоматизировать задачи и расширять функциональность сервисов Google Workspace: Sheets, Docs, Forms, Drive и других. API в контексте GAS подразумевает возможность вызывать скрипт как веб-приложение, предоставляя ему данные и получая результаты обработки. Это открывает широкие возможности для интеграции GAS с другими системами.
Вместо ручного выполнения операций в Google Sheets, например, API позволяет автоматизировать обновление данных из внешних источников, обработку форм, отправку персонализированных email-рассылок на основе данных из CRM, и многое другое. Основное преимущество – автоматизация и интеграция, снижение ручного труда.
Обзор возможностей API Google Apps Script
API Google Apps Script позволяет:
Получать данные от внешних систем: Обновлять Google Sheets на основе данных из CRM, баз данных, API контекстной рекламы.
Обрабатывать данные: Выполнять сложные вычисления, агрегировать данные, форматировать отчеты.
Автоматизировать действия: Создавать документы, отправлять email, обновлять календари.
Интегрировать с другими сервисами Google Workspace: Связывать Sheets с Docs, Forms с Calendar.
Создавать веб-сервисы: Разрабатывать простые веб-приложения, использующие данные и функциональность Google Workspace.
Сценарии использования API Google Apps Script
Рассмотрим несколько конкретных сценариев:
Автоматизация отчетов контекстной рекламы: Скрипт, вызываемый по API, получает данные из Google Ads API, обрабатывает их и записывает в Google Sheets, формируя дашборд с ключевыми показателями.
Интеграция CRM с Google Sheets: При создании нового лида в CRM, данные автоматически передаются в Google Sheets для анализа воронки продаж.
Автоматическая генерация документов: На основе данных из Google Sheets, API вызывает скрипт, который генерирует персонализированные коммерческие предложения в Google Docs.
Обработка ответов Google Forms: После отправки формы, API вызывает скрипт, который анализирует ответы, создает задачи в task-менеджере, отправляет уведомления.
Подготовка Google Apps Script к вызову API
Создание и настройка проекта Google Apps Script
Откройте Google Drive.
Нажмите "Создать" > "Еще" > "Google Apps Script".
Дайте название проекту.
Начните написание кода.
Функции doGet() и doPost(): основа API
doGet(e) и doPost(e) — это специальные функции, которые вызываются при HTTP GET и POST запросах к вашему веб-приложению. Аргумент e содержит информацию о запросе, включая параметры и тело запроса. Типизация аргумента e является GoogleAppsScript.Events.DoGet.
/**
* Обрабатывает GET запросы.
* @param {GoogleAppsScript.Events.DoGet} e Объект события GET запроса.
* @return {GoogleAppsScript.Content.TextOutput} Ответ в формате Text.
*/
function doGet(e: GoogleAppsScript.Events.DoGet): GoogleAppsScript.Content.TextOutput {
// Логика обработки GET запроса
return ContentService.createTextOutput("Hello, GET!");
}
/**
* Обрабатывает POST запросы.
* @param {GoogleAppsScript.Events.DoPost} e Объект события POST запроса.
* @return {GoogleAppsScript.Content.TextOutput} Ответ в формате Text.
*/
function doPost(e: GoogleAppsScript.Events.DoPost): GoogleAppsScript.Content.TextOutput {
// Логика обработки POST запроса
return ContentService.createTextOutput("Hello, POST!");
}Развертывание скрипта как веб-приложения
В редакторе Apps Script, нажмите "Развернуть" > "Новое развертывание".
Выберите тип развертывания "Веб-приложение".
Укажите, кто имеет право запускать приложение (только вы, все пользователи аккаунта Google Workspace, или все пользователи).
Укажите, кто имеет право доступа к приложению (только я, все у кого есть ссылка).
Нажмите "Развернуть".
Скопируйте URL веб-приложения.
Настройка прав доступа к веб-приложению
При развертывании, вы выбираете, кто может запускать приложение и кто имеет к нему доступ. Важно правильно настроить эти параметры:
Запускать приложение от имени: Определяет, от чьего имени будет выполняться скрипт. Обычно, выбирают "Я" (автор скрипта).
Кто имеет доступ к приложению: Определяет, кто может вызывать API. Рекомендуется ограничивать доступ только теми, кому он действительно необходим.
Вызов API Google Apps Script из различных источников
Вызов API с использованием JavaScript (fetch API, XMLHttpRequest)
// Использование fetch API
const url = 'YOUR_WEB_APP_URL';
fetch(url, {
method: 'POST',
mode: 'no-cors',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({data: 'example'})
})
.then(response => response.text())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
// Использование XMLHttpRequest (альтернативный вариант)
const xhr = new XMLHttpRequest();
xhr.open('POST', url);
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.onload = function() {
if (xhr.status === 200) {
console.log(xhr.responseText);
} else {
console.error('Request failed. Returned status of ' + xhr.status);
}
};
xhr.send(JSON.stringify({data: 'example'}));Вызов API из других Google Sheets/Docs/Forms
Вы можете вызывать API одного скрипта из другого скрипта, связанного с другим Google Sheets/Docs/Forms.
function callApi() {
const url = 'YOUR_WEB_APP_URL';
const options: GoogleAppsScript.URL_Fetch.URLFetchRequestOptions = {
'method' : 'post',
'contentType': 'application/json',
'payload' : JSON.stringify({ 'message': 'Hello from another script!' })
};
const response = UrlFetchApp.fetch(url, options);
Logger.log(response.getContentText());
}Вызов API из сторонних приложений (Python, PHP, и др.)
Python:
import requests
import json
url = 'YOUR_WEB_APP_URL'
data = {'key': 'value'}
headers = {'Content-type': 'application/json'}
response = requests.post(url, data=json.dumps(data), headers=headers)
print(response.text)PHP:
'value');
$options = array(
'http' => array(
'method' => 'POST',
'header' => 'Content-type: application/json',
'content' => json_encode($data)
)
);
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
var_dump($result);
?>Использование cURL для вызова API
curl -X POST -H "Content-Type: application/json" -d '{"key":"value"}' YOUR_WEB_APP_URLОбработка данных и ошибок в API Google Apps Script
Получение параметров запроса (query parameters, body)
GET запросы (query parameters):
function doGet(e: GoogleAppsScript.Events.DoGet): GoogleAppsScript.Content.TextOutput {
const param1 = e.parameter.param1; // Получение параметра param1
const param2 = e.parameter.param2; // Получение параметра param2
return ContentService.createTextOutput(`param1: ${param1}, param2: ${param2}`);
}POST запросы (body):
function doPost(e: GoogleAppsScript.Events.DoPost): GoogleAppsScript.Content.TextOutput {
const requestBody = JSON.parse(e.postData.contents); // Получение тела запроса в формате JSON
const data = requestBody.data; // Получение данных из тела запроса
return ContentService.createTextOutput(`Received data: ${data}`);
}Форматирование ответа API (JSON, Text, HTML)
// JSON
function doGet(e: GoogleAppsScript.Events.DoGet): GoogleAppsScript.Content.TextOutput {
const data = { message: 'Hello, world!', status: 'success' };
return ContentService.createTextOutput(JSON.stringify(data)).setMimeType(ContentService.MimeType.JSON);
}
// Text
function doGet(e: GoogleAppsScript.Events.DoGet): GoogleAppsScript.Content.TextOutput {
return ContentService.createTextOutput('Hello, world!').setMimeType(ContentService.MimeType.TEXT);
}
// HTML
function doGet(e: GoogleAppsScript.Events.DoGet): GoogleAppsScript.Content.TextOutput {
return ContentService.createTextOutput('Hello, world!
').setMimeType(ContentService.MimeType.HTML);
}Обработка ошибок и исключений (try…catch)
function doGet(e: GoogleAppsScript.Events.DoGet): GoogleAppsScript.Content.TextOutput {
try {
// Код, который может вызвать ошибку
const result = 10 / e.parameter.number; // Попытка деления на параметр
return ContentService.createTextOutput(`Result: ${result}`);
} catch (error) {
// Обработка ошибки
Logger.log(`Error: ${error}`);
return ContentService.createTextOutput(`Error: ${error}`).setMimeType(ContentService.MimeType.TEXT);
}
}Логирование и отладка API Google Apps Script
Используйте Logger.log() для записи информации в журнал выполнения скрипта. Журнал доступен в редакторе Apps Script (Вид > Журналы).
Безопасность API Google Apps Script
Аутентификация и авторизация (OAuth 2.0)
Для защиты API от несанкционированного доступа, рекомендуется использовать OAuth 2.0. Это требует более сложной настройки, включающей создание проекта в Google Cloud Platform и настройку OAuth 2.0 клиента. Подробная информация доступна в документации Google.
Защита от CSRF и других атак
Для защиты от CSRF атак, рекомендуется использовать токены CSRF. При каждом запросе, клиент должен передавать токен, который проверяется на сервере. Это позволяет убедиться, что запрос был отправлен именно с вашего сайта.
Ограничение доступа к API
Ограничьте доступ к API только тем пользователям и приложениям, которым он действительно необходим. Используйте настройки доступа при развертывании веб-приложения, а также аутентификацию и авторизацию для более granular контроля.