Что такое 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, ее идентификатор можно найти:
- В настройках проекта библиотеки:
Файл>Настройки проекта. ПолеИдентификатор скриптасодержит нужный ID. - В URL редактора скрипта библиотеки: URL имеет вид
https://script.google.com/d/{SCRIPT_ID}/edit.
Использование идентификатора скрипта для установки библиотеки OAuth2
Для добавления библиотеки OAuth2 в ваш проект GAS:
- Откройте редактор скриптов вашего проекта.
- В левой панели нажмите на значок
+рядом с разделомБиблиотеки. - В поле
Найти библиотекувставьте идентификатор скрипта библиотеки OAuth2. - Нажмите
Найти. - Выберите найденную библиотеку (обычно
OAuth2). - Выберите последнюю стабильную версию.
- Измените стандартный идентификатор
OAuth2(если необходимо) на более удобный, например,OAuth2Lib. - Нажмите
Добавить.
Библиотека будет добавлена в ваш проект, и вы сможете использовать ее функции.
Альтернативные способы определения идентификатора скрипта
В редких случаях, если стандартные методы недоступны (например, для очень старых или неопубликованных версий), 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, чтобы удалить сохраненные данные и пройти авторизацию заново.
Что делать, если идентификатор скрипта не работает
- Проверить актуальность ID: Убедитесь, что вы используете последний известный идентификатор для официальной библиотеки OAuth2. Проверьте официальную документацию или репозиторий.
- Проверить статус сервисов Google: В редких случаях проблемы могут быть на стороне Google Apps Script или связанных сервисов.
- Использовать альтернативную библиотеку: Если официальная библиотека недоступна или не работает, рассмотрите возможность использования форков или альтернативных реализаций OAuth2 для GAS, но подходите к этому с осторожностью.
- Скопировать код библиотеки: В крайнем случае, вы можете скопировать исходный код библиотеки 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.