Как использовать Bearer Token в Google Apps Script?

Что такое Bearer Token и зачем он нужен?

Bearer Token — это строка, используемая для авторизации запросов к API. Он сообщает серверу, что клиент (в данном случае, ваш Google Apps Script) имеет разрешение на доступ к ресурсам. Bearer Token является частью стандарта OAuth 2.0 и широко используется в современных веб-сервисах. В отличие от базовой аутентификации (имя пользователя/пароль), Bearer Token предоставляет более безопасный и гибкий способ аутентификации, поскольку может быть отозван, иметь ограниченный срок действия и предоставлять различные уровни доступа.

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

ChatGPT

Google AI

Grok

Perplexity

Когда следует использовать Bearer Token в Google Apps Script?

Bearer Token необходим, когда вы хотите получить доступ к API, требующему авторизацию OAuth 2.0. Это может быть API платформы контекстной рекламы (например, Google Ads API, Facebook Ads API), API аналитики (например, Google Analytics API), или любой другой сервис, где требуется идентифицировать пользователя или приложение, делающее запрос. Например, вы можете использовать Bearer Token для:

• Получения данных об рекламных кампаниях.
• Автоматической генерации отчетов.
• Обновления ставок.
• Публикации контента в социальных сетях.

Необходимые условия для работы с Bearer Token в Apps Script

Перед тем, как начать, убедитесь, что у вас есть:

1. Доступ к API, для которого требуется Bearer Token. Это означает, что вы должны зарегистрироваться в сервисе и получить учетные данные (например, Client ID и Client Secret).
2. Google Apps Script проект, где вы будете писать код.
3. Базовое понимание работы с HTTP запросами и JSON.

Получение Bearer Token

Авторизация в стороннем сервисе и получение токена

Процесс получения Bearer Token обычно включает перенаправление пользователя на страницу авторизации сервиса, где он должен предоставить разрешение вашему приложению. После этого сервис перенаправит пользователя обратно в ваше приложение с кодом авторизации, который вы затем обменяете на Bearer Token. Этот процесс называется OAuth 2.0 authorization code flow. Детали зависят от API.

/**
 * @param {string} clientId The client ID from the API console
 * @param {string} clientSecret The client secret from the API console
 * @param {string} redirectUri The URI to redirect to after authorization
 * @return {string} The URL to redirect the user to for authorization.
 */
function getAuthorizationUrl(clientId, clientSecret, redirectUri) {
  const authUrl = 'https://accounts.google.com/o/oauth2/auth';
  const params = {
    'client_id': clientId,
    'redirect_uri': redirectUri,
    'response_type': 'code',
    'scope': 'https://www.googleapis.com/auth/analytics.readonly' // example scope
  };
  const queryString = Object.keys(params).map(key => `${key}=${encodeURIComponent(params[key])}`).join('&');
  return `${authUrl}?${queryString}`;
}

Сохранение токена в безопасном месте (например, Script Properties)

Крайне важно безопасно хранить Bearer Token. Не помещайте его непосредственно в код. Используйте Script Properties (или User Properties, если токен относится к конкретному пользователю) для хранения токена. Script Properties шифруются и хранятся на сервере Google.

/**
 * Сохраняет токен в Script Properties.
 * @param {string} token Bearer token.
 */
function saveToken(token) {
  PropertiesService.getScriptProperties().setProperty('bearer_token', token);
}

/**
 * Возвращает токен из Script Properties.
 * @return {string|null} Bearer token, или null, если токен не найден.
 */
function getToken() {
  return PropertiesService.getScriptProperties().getProperty('bearer_token');
}

Обновление токена (refresh token), если это необходимо

Bearer Token имеет ограниченный срок действия. Для автоматического обновления токена необходимо использовать refresh token, если API его предоставляет. Refresh token позволяет получить новый Bearer Token без повторного запроса авторизации у пользователя.

Использование Bearer Token в Google Apps Script

Создание HTTP запроса с использованием UrlFetchApp

Google Apps Script предоставляет сервис UrlFetchApp для выполнения HTTP запросов.

Добавление заголовка ‘Authorization: Bearer [ваш_токен]’ к запросу

Для отправки Bearer Token необходимо добавить заголовок Authorization к HTTP запросу. Значением заголовка должно быть Bearer [ваш_токен], где [ваш_токен] — это полученный вами Bearer Token.

Примеры кода: GET, POST запросы с Bearer Token

/**
 * Выполняет GET запрос с использованием Bearer Token.
 * @param {string} url URL API.
 * @return {object|null} JSON ответ, или null в случае ошибки.
 */
function getData(url) {
  const token = getToken();
  if (!token) {
    Logger.log('Токен не найден. Необходимо авторизоваться.');
    return null;
  }

  const options = {
    'method': 'get',
    'headers': {
      'Authorization': 'Bearer ' + token
    }
  };

  try {
    const response = UrlFetchApp.fetch(url, options);
    const content = response.getContentText();
    return JSON.parse(content);
  } catch (e) {
    Logger.log('Ошибка при выполнении запроса: ' + e);
    return null;
  }
}

/**
 * Выполняет POST запрос с использованием Bearer Token.
 * @param {string} url URL API.
 * @param {object} payload Данные для отправки в теле запроса.
 * @return {object|null} JSON ответ, или null в случае ошибки.
 */
function postData(url, payload) {
  const token = getToken();
  if (!token) {
    Logger.log('Токен не найден. Необходимо авторизоваться.');
    return null;
  }

  const options = {
    'method': 'post',
    'contentType': 'application/json',
    'payload': JSON.stringify(payload),
    'headers': {
      'Authorization': 'Bearer ' + token
    }
  };

  try {
    const response = UrlFetchApp.fetch(url, options);
    const content = response.getContentText();
    return JSON.parse(content);
  } catch (e) {
    Logger.log('Ошибка при выполнении запроса: ' + e);
    return null;
  }
}

// Пример использования
function exampleUsage() {
  const apiUrl = 'https://api.example.com/data'; // Замените на реальный URL
  const data = getData(apiUrl);

  if (data) {
    Logger.log(data);
  } else {
    Logger.log('Не удалось получить данные.');
  }

  const postApiUrl = 'https://api.example.com/resource';
  const postPayload = { key1: 'value1', key2: 'value2' };
  const postResponse = postData(postApiUrl, postPayload);

  if (postResponse) {
    Logger.log(postResponse);
  } else {
    Logger.log('Не удалось отправить данные.');
  }
}

Обработка ответов от API

Разбор JSON ответа

Сервис UrlFetchApp возвращает ответ в виде строки. Для работы с данными необходимо распарсить JSON строку в объект JavaScript с помощью JSON.parse(). Убедитесь, что ответ действительно является JSON, прежде чем пытаться его распарсить.

Обработка ошибок авторизации (401 Unauthorized)

Если Bearer Token недействителен или истек, API вернет ошибку 401 Unauthorized. Необходимо обработать эту ошибку и либо запросить новый токен у пользователя, либо попытаться обновить токен с помощью refresh token.

Логирование и отладка запросов с Bearer Token

Для отладки используйте Logger.log() для записи информации о запросах и ответах. Это поможет вам определить, что идет не так. Не записывайте сам Bearer Token в лог, это небезопасно. Вместо этого, логируйте, что запрос был выполнен с использованием Bearer Token.

Рекомендации по безопасности и лучшие практики

Безопасное хранение токенов

• Используйте Script Properties или User Properties для хранения токенов.
• Не храните токены в коде.
• Рассмотрите возможность шифрования токенов перед сохранением.

Ограничение прав доступа токена

При получении Bearer Token запросите только необходимые права доступа (scopes). Это уменьшит риск, если токен будет скомпрометирован.

Важность обработки ошибок и валидации данных

• Всегда проверяйте ответы от API на наличие ошибок.
• Обрабатывайте ошибки авторизации (401 Unauthorized).
• Валидируйте данные, полученные от API, чтобы избежать неожиданного поведения.