Как вызвать внешний API из Google Apps Script?

Что такое Google Apps Script и его возможности

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

Почему вызывать внешние API полезно и когда это необходимо

Вызовы внешних API расширяют функциональность Google Apps Script, позволяя:

• Получать данные из внешних источников (например, курсы валют, погода).
• Автоматизировать взаимодействие с другими веб-сервисами (например, отправка SMS, управление задачами).
• Интегрировать Google Workspace с корпоративными системами.

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

Обзор сервиса UrlFetchApp

UrlFetchApp — это встроенный сервис Google Apps Script, предназначенный для отправки HTTP-запросов к внешним API. Он позволяет отправлять GET, POST, PUT, DELETE и другие типы запросов, а также настраивать заголовки, параметры и содержимое запроса.

Использование UrlFetchApp для GET запросов

Базовый синтаксис UrlFetchApp.fetch()

Основной метод для выполнения GET запроса – UrlFetchApp.fetch(url, params). url – это строка с URL API-endpoint. params — необязательный объект с дополнительными параметрами запроса.

Создание простого GET запроса и обработка ответа

/**
 * @param {string} apiUrl - URL API endpoint.
 * @return {object} JSON response from the API.
 */
function getApiResponse(apiUrl: string): object {
  try {
    const response = UrlFetchApp.fetch(apiUrl);
    const content = response.getContentText();
    const json = JSON.parse(content);
    return json;
  } catch (e) {
    Logger.log('Error fetching API: ' + e);
    return null;
  }
}

// Пример использования
function myFunction() {
  const apiUrl = 'https://api.example.com/data';
  const data = getApiResponse(apiUrl);
  if (data) {
    Logger.log(data);
    // Дальнейшая обработка данных
  }
}

Обработка ошибок и статусов HTTP

Важно обрабатывать возможные ошибки при выполнении запросов. UrlFetchApp.fetch() выбрасывает исключение в случае ошибок. Статус HTTP ответа можно получить через response.getResponseCode(). Коды 200-299 обычно означают успешное выполнение запроса.

function checkApiResponse() {
  try {
    const response = UrlFetchApp.fetch('https://api.example.com/resource');
    const statusCode = response.getResponseCode();
    if (statusCode >= 200 && statusCode < 300) {
      Logger.log('API call successful!');
    } else {
      Logger.log('API call failed with status code: ' + statusCode);
    }
  } catch (e) {
    Logger.log('Error during API call: ' + e);
  }
}

Примеры GET запросов к различным API (REST)

Предположим, есть API для получения данных о пользователе по ID:

function getUserData(userId: string): object | null {
  const apiUrl = `https://api.example.com/users/${userId}`;
  return getApiResponse(apiUrl);
}

function testUserData() {
  const userData = getUserData('123');
  if (userData) {
    Logger.log(userData);
  }
}

Использование UrlFetchApp для POST запросов

Отправка данных в формате JSON

Для отправки данных в формате JSON необходимо преобразовать объект в JSON строку с помощью JSON.stringify() и указать соответствующий заголовок Content-Type.

Установка заголовков запроса (headers)

Заголовки запроса позволяют указать тип контента, параметры авторизации и другую информацию.

Опции запроса: метод, payload, headers

Полный синтаксис для выполнения POST запроса выглядит так:

const options = {
  'method': 'post',
  'contentType': 'application/json',
  'payload': JSON.stringify(data),
  'headers': {
    'Authorization': 'Bearer ' + accessToken
  }
};
const response = UrlFetchApp.fetch(url, options);

• method: HTTP метод (GET, POST, PUT, DELETE и т.д.).
• contentType: Тип контента (например, application/json, application/x-www-form-urlencoded).
• payload: Тело запроса (данные, которые необходимо отправить). Должно быть строкой.
• headers: Объект с заголовками запроса.

Примеры POST запросов к различным API

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

function createUser(name: string, email: string): object | null {
  const apiUrl = 'https://api.example.com/users';
  const data = {
    'name': name,
    'email': email
  };
  const options = {
    'method': 'post',
    'contentType': 'application/json',
    'payload': JSON.stringify(data)
  };
  try {
    const response = UrlFetchApp.fetch(apiUrl, options);
    const content = response.getContentText();
    const json = JSON.parse(content);
    return json;
  } catch (e) {
    Logger.log('Error creating user: ' + e);
    return null;
  }
}

function testCreateUser() {
  const newUser = createUser('John Doe', 'john.doe@example.com');
  if (newUser) {
    Logger.log(newUser);
  }
}

Авторизация и аутентификация при вызовах API

Передача API ключей в запросе

API ключи обычно передаются в заголовках запроса или в параметрах URL.

// Пример передачи API ключа в заголовке
const options = {
  'method': 'get',
  'headers': {
    'X-API-Key': 'YOUR_API_KEY'
  }
};
const response = UrlFetchApp.fetch(url, options);

// Пример передачи API ключа в параметрах URL
const url = 'https://api.example.com/data?api_key=YOUR_API_KEY';
const response = UrlFetchApp.fetch(url);

Использование OAuth 2.0 для авторизации (пример)

Для работы с OAuth 2.0 удобно использовать библиотеку OAuth2 for Google Apps Script.

Пример упрощенного сценария (требуется настройка OAuth2 библиотеки):

function getOAuth2Service() {
  // Замените значения на свои
  return OAuth2.createService('YourServiceName')
    .setClientId('YOUR_CLIENT_ID')
    .setClientSecret('YOUR_CLIENT_SECRET')
    .setTokenUrl('https://oauth2.example.com/token')
    .setAuthorizationBaseUrl('https://oauth2.example.com/auth')
    .setCallbackFunction('authCallback')
    .setPropertyStore(PropertiesService.getUserProperties());
}

function authCallback(request) {
  const service = getOAuth2Service();
  const authorized = service.handleCallback(request);
  if (authorized) {
    return HtmlService.createHtmlOutput('Success!');
  } else {
    return HtmlService.createHtmlOutput('Denied.');
  }
}

function callApiWithOAuth() {
  const service = getOAuth2Service();
  if (service.hasAccess()) {
    const url = 'https://api.example.com/protected';
    const response = UrlFetchApp.fetch(url, {
      headers: {
        Authorization: 'Bearer ' + service.getAccessToken()
      }
    });
    Logger.log(response.getContentText());
  } else {
    const authorizationUrl = service.getAuthorizationUrl();
    Logger.log('Open the following URL to authorize: ' + authorizationUrl);
  }
}

Обработка ответов API с авторизацией

После получения ответа необходимо проверить его статус. Код 401 Unauthorized означает, что токен устарел или недействителен. В этом случае нужно обновить токен и повторить запрос.

Продвинутые техники и лучшие практики

Асинхронные вызовы API (если применимо, Queue)

Google Apps Script имеет ограничение по времени выполнения скрипта. Для продолжительных операций можно использовать триггеры по времени или сервис Script Queue (при его доступности в Apps Script).

Кэширование ответов API для оптимизации

Для снижения нагрузки на API и ускорения работы скрипта можно кэшировать ответы API с помощью сервиса CacheService.

function getCachedData(key: string, apiUrl: string, expirationInSeconds: number = 3600): object | null {
  const cache = CacheService.getScriptCache();
  const cached = cache.get(key);
  if (cached) {
    return JSON.parse(cached);
  } else {
    const data = getApiResponse(apiUrl);
    if (data) {
      cache.put(key, JSON.stringify(data), expirationInSeconds);
      return data;
    } else {
      return null;
    }
  }
}

Обработка лимитов API и повторные попытки

Важно учитывать лимиты API и обрабатывать ошибки, связанные с превышением лимитов. Можно реализовать повторные попытки запроса с экспоненциальной задержкой.

Безопасность при работе с API ключами и секретами

Не храните API ключи и секреты в коде скрипта в открытом виде. Используйте сервис PropertiesService для хранения конфиденциальной информации.

function getApiKey(): string {
  const properties = PropertiesService.getScriptProperties();
  return properties.getProperty('API_KEY');
}

Установите API ключ через интерфейс редактора скриптов, раздел «Свойства проекта».