Идентификатор скрипта библиотеки OAuth2 в Google Apps Script: подробное руководство

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

OAuth 2.0 — это открытый стандарт авторизации, позволяющий приложениям получать ограниченный доступ к учетным записям пользователей на HTTP-сервисах, таких как Google, Facebook, GitHub и др. В контексте Google Apps Script (GAS), OAuth2 критически важен для безопасного взаимодействия скриптов с API Google (Google Sheets, Drive, Ads, Analytics, Calendar и т.д.) и сторонними сервисами от имени пользователя, не требуя при этом передачи или хранения его учетных данных (логина и пароля).

Использование OAuth2 в GAS обеспечивает гранулярный контроль доступа: скрипт запрашивает только необходимые разрешения (scopes), а пользователь явно дает свое согласие на их предоставление. Это повышает безопасность и доверие к вашим приложениям.

Обзор библиотеки OAuth2 для Google Apps Script

Хотя Google Apps Script имеет встроенные сервисы для работы с некоторыми API Google (например, DriveApp, SheetsApp), они не покрывают все существующие API и тем более сторонние сервисы. Для универсального решения была создана популярная сторонняя библиотека OAuth2 для Google Apps Script. Она значительно упрощает реализацию потоков авторизации OAuth2 (Authorization Code, Client Credentials и др.) в ваших скриптах.

Эта библиотека инкапсулирует сложные детали протокола, предоставляя разработчикам удобный интерфейс для получения токенов доступа, их обновления и выполнения авторизованных запросов к API.

Роль идентификатора скрипта в библиотеке OAuth2

Идентификатор скрипта (Script ID) — это уникальный идентификатор, присваиваемый каждому проекту Google Apps Script. Когда речь идет о библиотеке OAuth2, ее собственный Script ID используется для того, чтобы другие проекты GAS могли подключить и использовать ее функциональность. Добавление библиотеки по ее идентификатору является стандартным способом повторного использования кода в экосистеме Google Apps Script.

Таким образом, знание и правильное использование идентификатора скрипта библиотеки OAuth2 необходимо для ее интеграции в ваш проект и последующей настройки потоков авторизации для доступа к защищенным ресурсам.

Получение идентификатора скрипта библиотеки OAuth2

Как найти идентификатор скрипта опубликованной библиотеки

Идентификатор скрипта официальной и наиболее часто используемой библиотеки OAuth2 для Google Apps Script является общедоступным и задокументированным. На момент написания статьи, актуальный идентификатор:

1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF

Этот идентификатор может со временем измениться при выходе новых версий библиотеки. Всегда рекомендуется сверяться с официальной документацией или репозиторием библиотеки (например, на GitHub) для получения актуального ID.

Если вы используете другую или собственную библиотеку OAuth2, ее идентификатор можно найти:

  1. В настройках проекта библиотеки: Файл > Настройки проекта. Поле Идентификатор скрипта содержит нужный ID.
  2. В URL редактора скрипта библиотеки: URL имеет вид https://script.google.com/d/{SCRIPT_ID}/edit.

Использование идентификатора скрипта для установки библиотеки OAuth2

Для добавления библиотеки OAuth2 в ваш проект GAS:

  1. Откройте редактор скриптов вашего проекта.
  2. В левой панели нажмите на значок + рядом с разделом Библиотеки.
  3. В поле Найти библиотеку вставьте идентификатор скрипта библиотеки OAuth2.
  4. Нажмите Найти.
  5. Выберите найденную библиотеку (обычно OAuth2).
  6. Выберите последнюю стабильную версию.
  7. Измените стандартный идентификатор OAuth2 (если необходимо) на более удобный, например, OAuth2Lib.
  8. Нажмите Добавить.

Библиотека будет добавлена в ваш проект, и вы сможете использовать ее функции.

Альтернативные способы определения идентификатора скрипта

В редких случаях, если стандартные методы недоступны (например, для очень старых или неопубликованных версий), ID можно попытаться найти:

  • В исходном коде других скриптов, которые уже используют эту библиотеку (в файле appsscript.json или в разделе библиотек старого редактора).
  • В документации или инструкциях, предоставленных разработчиком библиотеки.

Однако для официальной библиотеки OAuth2 использование опубликованного ID является наиболее надежным способом.

Настройка и использование библиотеки OAuth2 с идентификатором скрипта

Импорт библиотеки OAuth2 в ваш проект Google Apps Script

После добавления библиотеки с использованием ее идентификатора скрипта, как описано выше, она становится доступной в вашем коде через идентификатор, который вы ей присвоили при добавлении (по умолчанию OAuth2).

/**
 * Пример функции, демонстрирующей использование импортированной библиотеки.
 * Обратите внимание: имя 'OAuth2' соответствует идентификатору, 
 * указанному при добавлении библиотеки.
 */
function checkLibraryImport(): void {
  try {
    if (OAuth2) {
      Logger.log('Библиотека OAuth2 успешно импортирована.');
      // Можно вызвать какую-либо функцию библиотеки для проверки
      // Logger.log(OAuth2.getRedirectUri()); 
    } else {
      Logger.log('Ошибка: Библиотека OAuth2 не найдена.');
    }
  } catch (e) {
    Logger.log(`Произошла ошибка при проверке импорта: ${e}`);
  }
}

Создание и настройка OAuth2 сервиса

Ключевым шагом является создание экземпляра сервиса OAuth2, специфичного для API, к которому вы хотите получить доступ. Это включает настройку URL-адресов конечных точек OAuth2, идентификатора клиента, секрета клиента и запрашиваемых областей разрешений (scopes).

/**
 * Создает и возвращает сервис OAuth2 для доступа к Google Ads API.
 * @returns {GoogleAppsScript.OAuth2.Service} Сконфигурированный сервис OAuth2.
 */
function getGoogleAdsService(): GoogleAppsScript.OAuth2.Service {
  // Замените на ваши учетные данные из Google Cloud Console
  const CLIENT_ID: string = 'YOUR_CLIENT_ID';
  const CLIENT_SECRET: string = 'YOUR_CLIENT_SECRET';

  // URL перенаправления должен быть добавлен в разрешенные 
  // URI перенаправления в настройках учетных данных OAuth в Google Cloud Console.
  const REDIRECT_URI: string = `https://script.google.com/macros/d/${ScriptApp.getScriptId()}/usercallback`;

  return OAuth2.createService('googleAds')
    // Установка учетных данных клиента
    .setAuthorizationBaseUrl('https://accounts.google.com/o/oauth2/v2/auth')
    .setTokenUrl('https://oauth2.googleapis.com/token')
    .setClientId(CLIENT_ID)
    .setClientSecret(CLIENT_SECRET)

    // Установка имени функции обратного вызова, которая будет вызвана 
    // после завершения процесса авторизации.
    .setCallbackFunction('authCallback')

    // Установка URI перенаправления
    .setRedirectUri(REDIRECT_URI) // Добавлено для явного указания

    // Установка области разрешений (scope). Для Google Ads API.
    .setScope('https://www.googleapis.com/auth/adwords')

    // Установка дополнительных параметров для запроса авторизации.
    .setParam('access_type', 'offline') // Запрос refresh_token для оффлайн-доступа
    .setParam('prompt', 'consent')     // Запрос согласия пользователя каждый раз

    // Управление хранилищем токенов (рекомендуется использовать PropertiesService)
    .setPropertyStore(PropertiesService.getUserProperties());
}

/**
 * Функция обратного вызова, вызываемая после авторизации пользователя.
 * @param {object} request Параметры запроса.
 * @returns {GoogleAppsScript.HTML.HtmlOutput} Результат для отображения пользователю.
 */
function authCallback(request: object): GoogleAppsScript.HTML.HtmlOutput {
  const adsService = getGoogleAdsService();
  const isAuthorized = adsService.handleCallback(request);
  if (isAuthorized) {
    return HtmlService.createHtmlOutput('Авторизация прошла успешно! Вы можете закрыть эту страницу.');
  } else {
    return HtmlService.createHtmlOutput('Ошибка авторизации.');
  }
}

/**
 * Инициирует процесс авторизации, если это необходимо.
 */
function authorizeGoogleAds(): void {
  const adsService = getGoogleAdsService();
  if (!adsService.hasAccess()) {
    Logger.log('Требуется авторизация. Откройте URL: ' + adsService.getAuthorizationUrl());
  } else {
    Logger.log('Авторизация уже пройдена.');
  }
}
Реклама

Примеры использования OAuth2 для доступа к API Google и другим сервисам

После успешной авторизации и получения токена доступа, библиотека OAuth2 позволяет легко выполнять запросы к API.

/**
 * Получает список кампаний из Google Ads API.
 */
function fetchGoogleAdsCampaigns(): void {
  const adsService = getGoogleAdsService();

  if (!adsService.hasAccess()) {
    Logger.log('Скрипт не авторизован. Запустите функцию authorizeGoogleAds() и перейдите по ссылке.');
    return;
  }

  const accessToken: string = adsService.getAccessToken();
  const customerId: string = 'YOUR_CUSTOMER_ID'; // Укажите ваш ID клиента Google Ads (без дефисов)
  const developerToken: string = 'YOUR_DEVELOPER_TOKEN'; // Укажите ваш Developer Token
  const loginCustomerId: string = 'YOUR_LOGIN_CUSTOMER_ID'; // Если используете MCC, укажите ID управляющего аккаунта

  const apiUrl: string = `https://googleads.googleapis.com/v16/customers/${customerId}/googleAds:searchStream`;

  const requestBody = {
    query: `
      SELECT 
        campaign.id, 
        campaign.name, 
        campaign.status 
      FROM campaign 
      ORDER BY campaign.name
    `
  };

  const options: GoogleAppsScript.URL_Fetch.URLFetchRequestOptions = {
    method: 'post',
    contentType: 'application/json',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'developer-token': developerToken,
      'login-customer-id': loginCustomerId // Необходим при работе через MCC
    },
    payload: JSON.stringify(requestBody),
    muteHttpExceptions: true // Позволяет обрабатывать ошибки вручную
  };

  try {
    const response = UrlFetchApp.fetch(apiUrl, options);
    const responseCode = response.getResponseCode();
    const responseBody = response.getContentText();

    if (responseCode === 200) {
      const results = JSON.parse(responseBody);
      // У Google Ads API ответ в виде массива объектов, даже если один результат
      if (results && results.length > 0 && results[0].results) {
        results[0].results.forEach((item: any) => {
           Logger.log(`ID: ${item.campaign.id}, Name: ${item.campaign.name}, Status: ${item.campaign.status}`);
        });
      } else {
         Logger.log('Кампании не найдены или ответ пуст.');
         Logger.log(`Response: ${responseBody}`);
      }
    } else {
      Logger.log(`Ошибка запроса к Google Ads API: ${responseCode}`);
      Logger.log(`Ответ: ${responseBody}`);
      // Попытка сбросить токен, если ошибка связана с авторизацией (например, 401)
      if (responseCode === 401) {
         adsService.reset();
         Logger.log('Токен доступа сброшен из-за ошибки 401. Попробуйте авторизоваться снова.');
      }
    }
  } catch (e) {
    Logger.log(`Исключение при выполнении запроса: ${e}`);
  }
}

Устранение неполадок и часто задаваемые вопросы (FAQ)

Наиболее распространенные ошибки, связанные с идентификатором скрипта

  • Библиотека с указанным идентификатором не найдена: Убедитесь, что вы скопировали и вставили правильный и актуальный идентификатор скрипта библиотеки OAuth2. Проверьте наличие опечаток или лишних символов.
  • Идентификатор 'OAuth2' не определен: Это происходит, если библиотека не была добавлена в проект или была добавлена с другим идентификатором (например, OAuth2Lib). Проверьте раздел Библиотеки в настройках проекта и используйте правильное имя в коде.
  • Проблемы с версиями: Иногда выбор несовместимой версии библиотеки может привести к ошибкам. Рекомендуется использовать последнюю стабильную версию.

Рекомендации по отладке OAuth2 в Google Apps Script

  • Используйте Logger.log(): Активно логируйте ключевые шаги: получение URL авторизации, наличие доступа (hasAccess()), получение токена, параметры запроса и ответ API.
  • Проверьте URL перенаправления: Убедитесь, что URL, сгенерированный OAuth2.getRedirectUri() или указанный вручную, точно совпадает с тем, что добавлен в разрешенные URI перенаправления в настройках вашего OAuth-клиента (например, в Google Cloud Console).
  • Проверьте области разрешений (Scopes): Запрашиваемые scopes должны соответствовать тем, что разрешены для вашего OAuth-клиента и требуются для вызовов API.
  • Используйте try...catch: Оборачивайте вызовы API и операции с OAuth2 в блоки try...catch для перехвата и анализа ошибок.
  • Сброс авторизации (service.reset()): Если вы подозреваете проблемы с сохраненным токеном (например, он устарел или был отозван), вызовите метод reset() для вашего сервиса OAuth2, чтобы удалить сохраненные данные и пройти авторизацию заново.

Что делать, если идентификатор скрипта не работает

  1. Проверить актуальность ID: Убедитесь, что вы используете последний известный идентификатор для официальной библиотеки OAuth2. Проверьте официальную документацию или репозиторий.
  2. Проверить статус сервисов Google: В редких случаях проблемы могут быть на стороне Google Apps Script или связанных сервисов.
  3. Использовать альтернативную библиотеку: Если официальная библиотека недоступна или не работает, рассмотрите возможность использования форков или альтернативных реализаций OAuth2 для GAS, но подходите к этому с осторожностью.
  4. Скопировать код библиотеки: В крайнем случае, вы можете скопировать исходный код библиотеки OAuth2 непосредственно в свой проект. Это усложнит обновление, но обеспечит работоспособность.

Заключение

Преимущества использования библиотеки OAuth2 с идентификатором скрипта

Использование библиотеки OAuth2 через ее идентификатор скрипта является стандартным и рекомендуемым подходом в Google Apps Script. Это позволяет:

  • Упростить разработку: Абстрагироваться от сложностей протокола OAuth2.
  • Повысить безопасность: Реализовать стандартные и проверенные потоки авторизации.
  • Обеспечить чистоту кода: Избежать дублирования кода авторизации в разных проектах.
  • Легко обновлять: Получать исправления и новые функции, обновляя версию библиотеки в настройках проекта.

Дальнейшие шаги и ресурсы для изучения OAuth2 в Google Apps Script

  • Официальная документация библиотеки OAuth2: Изучите репозиторий на GitHub (ищите googleworkspace/apps-script-oauth2) для детального описания всех функций и настроек.
  • Документация Google Identity Platform (OAuth 2.0): Понимание основ OAuth2 на платформе Google поможет в настройке клиентов и разрешений.
  • Документация API: Ознакомьтесь с требованиями к авторизации конкретного API, с которым вы работаете (например, Google Ads API, Google Analytics API), включая необходимые scopes.
  • Примеры и руководства: Ищите примеры использования библиотеки OAuth2 для конкретных задач и API в блогах и сообществах разработчиков Google Apps Script.

Добавить комментарий