Что такое Apps Script и зачем нужны разрешения?
Apps Script — это облачная платформа для автоматизации, интеграции и расширения функциональности Google Workspace, включая Google Sheets. Разрешения (scopes) в Apps Script играют ключевую роль в определении того, какие ресурсы Google Workspace (например, данные в Sheets, доступ к Gmail, Calendar и т.д.) скрипт может читать, изменять или использовать иным образом. Без соответствующих разрешений скрипт не сможет выполнять операции, требующие доступа к данным пользователя или другим сервисам Google.
Разрешения необходимы для обеспечения безопасности. Они гарантируют, что скрипты не смогут получить доступ к данным, к которым у них нет явного разрешения, и защищают пользовательские данные от злоупотреблений.
Обзор различных типов разрешений Apps Script (scopes)
Apps Script использует систему разрешений OAuth 2.0. Разрешения определяются строками, описывающими доступ к конкретным сервисам и функциям. Примеры:
https://www.googleapis.com/auth/spreadsheets: Полный доступ к Google Sheets.https://www.googleapis.com/auth/spreadsheets.readonly: Доступ только для чтения Google Sheets.https://www.googleapis.com/auth/script.container.ui: Разрешение на создание пользовательского интерфейса в Google Sheets.https://www.googleapis.com/auth/drive.readonly: Доступ только для чтения Google Drive.
Полный список разрешений можно найти в документации Google Apps Script.
Как разрешения влияют на безопасность ваших скриптов
Неправильно настроенные разрешения могут представлять угрозу безопасности. Скрипт с избыточными разрешениями может быть использован злоумышленником для доступа к данным, к которым ему не следовало бы иметь доступ. Поэтому важно придерживаться принципа наименьших привилегий и запрашивать только те разрешения, которые действительно необходимы для работы скрипта.
Настройка разрешений в Google Sheets Apps Script
Автоматическое определение необходимых разрешений
Apps Script автоматически определяет необходимые разрешения на основе кода скрипта. Когда вы запускаете скрипт, который требует определенного разрешения, Apps Script запрашивает это разрешение у пользователя. Например, если скрипт пытается прочитать данные из Google Sheets, Apps Script автоматически обнаружит необходимость разрешения https://www.googleapis.com/auth/spreadsheets.readonly или https://www.googleapis.com/auth/spreadsheets.
Просмотр и изменение запрошенных разрешений в редакторе скриптов
Разрешения, необходимые скрипту, можно просмотреть в редакторе Apps Script. Для этого выберите Просмотреть > Разрешения (View > Manifest) в редакторе. В манифесте скрипта (appsscript.json) можно увидеть секцию oauthScopes, где перечислены все необходимые разрешения.
{
"oauthScopes": [
"https://www.googleapis.com/auth/spreadsheets",
"https://www.googleapis.com/auth/script.container.ui"
],
// ... другие настройки манифеста
}
Внимание: Не рекомендуется напрямую редактировать файл манифеста для изменения разрешений, лучше позволить Apps Script определять их автоматически на основе кода. Изменение вручную может привести к неожиданному поведению скрипта или проблемам с безопасностью.
Разрешения при публикации скрипта как веб-приложения или дополнения
При публикации скрипта как веб-приложения или дополнения необходимо учитывать следующее:
- Веб-приложения: При первом запуске веб-приложения пользователю будет предложено предоставить разрешения, необходимые для его работы. Важно четко объяснить пользователям, зачем нужны те или иные разрешения, чтобы они доверяли вашему приложению.
- Дополнения: Дополнения проходят процесс проверки Google, который включает проверку запрошенных разрешений. Google может отклонить дополнение, если запрошенные разрешения кажутся чрезмерными или не соответствуют функциональности дополнения.
Понимание и интерпретация запросов на разрешения
Расшифровка сообщений о запросе разрешений (примеры)
Когда Apps Script запрашивает разрешение, пользователю отображается сообщение с описанием того, к каким данным или сервисам скрипт хочет получить доступ. Примеры:
- «Скрипт хочет получить доступ к вашим Google Sheets.»: Это означает, что скрипт запрашивает разрешение
https://www.googleapis.com/auth/spreadsheets. - «Скрипт хочет отображать диалоговые окна и боковые панели в Google Sheets.»: Это означает, что скрипт запрашивает разрешение
https://www.googleapis.com/auth/script.container.ui.
Важно понимать, что эти сообщения часто обобщены. Чтобы получить более точное представление о том, какие данные запрашивает скрипт, необходимо проанализировать его код и манифест.
Как объяснить пользователям необходимость запрошенных разрешений
Предоставьте пользователям понятное объяснение, почему скрипту требуются те или иные разрешения. Например:
«Для автоматического импорта данных о рекламных кампаниях из Google Ads, скрипту необходим доступ к вашим Google Sheets для записи данных и доступ к Google Ads API для получения информации о кампаниях.»
Добавьте это объяснение в описание скрипта, в пользовательский интерфейс или в сопроводительную документацию.
Минимизация необходимых разрешений для повышения доверия
Чем меньше разрешений запрашивает скрипт, тем больше доверия он вызывает у пользователей. По возможности, используйте более узкие разрешения. Например, вместо https://www.googleapis.com/auth/spreadsheets используйте https://www.googleapis.com/auth/spreadsheets.readonly, если скрипту требуется только чтение данных.
Расширенные сценарии управления разрешениями
Использование сервиса Script Service для управления разрешениями программно
Сервис Script Service позволяет получить информацию о том, какие разрешения необходимы скрипту, а также проверять, предоставлены ли эти разрешения пользователем. Пример:
/**
* @return {boolean} True, если у скрипта есть необходимые разрешения.
*/
function hasRequiredPermissions(): boolean {
/** @type {string[]} */
const requiredScopes: string[] = ScriptApp.getOAuthScopes();
for (const scope of requiredScopes) {
if (!OAuth2.hasAccess(scope)) {
return false;
}
}
return true;
}
/**
* Проверяет наличие разрешений и запрашивает их при необходимости.
*/
function checkAndRequestPermissions(): void {
if (!hasRequiredPermissions()) {
Logger.log("Недостаточно разрешений. Требуется авторизация.");
// Можно отобразить пользователю сообщение с просьбой предоставить разрешения.
// Например, через ui.alert()
} else {
Logger.log("Все необходимые разрешения предоставлены.");
}
}
// Предполагается, что OAuth2 - это внешняя библиотека для управления OAuth 2.0.
// Ее необходимо подключить отдельно.
Примечание: Для использования OAuth2.hasAccess() требуется установить и настроить внешнюю библиотеку OAuth2. Она не является частью стандартной библиотеки Apps Script.
Обработка ошибок, связанных с недостающими разрешениями
Скрипт должен корректно обрабатывать ошибки, возникающие из-за отсутствия необходимых разрешений. Используйте блоки try...catch для перехвата исключений и предоставления пользователю информативного сообщения об ошибке. Например:
function tryReadDataFromSheet(): void {
try {
const spreadsheet: GoogleAppsScript.Spreadsheet.Spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
const sheet: GoogleAppsScript.Spreadsheet.Sheet = spreadsheet.getActiveSheet();
const range: GoogleAppsScript.Spreadsheet.Range = sheet.getDataRange();
const values: any[][] = range.getValues();
Logger.log(values);
} catch (e) {
Logger.log("Ошибка при чтении данных: " + e.message);
// Проверяем, связана ли ошибка с отсутствием разрешений.
if (e.message.includes("Authorization is required to perform that action.")) {
Logger.log("Недостаточно разрешений для чтения данных из Google Sheets.");
// Здесь можно показать пользователю сообщение с просьбой предоставить разрешения.
}
}
}
Смена аккаунта и влияние на разрешения
Если пользователь переключается между разными аккаунтами Google, это может повлиять на разрешения скрипта. Разрешения предоставляются для каждого аккаунта отдельно. Поэтому, если скрипт был авторизован под одним аккаунтом, а пользователь переключился на другой, скрипту потребуется повторная авторизация.
Лучшие практики по работе с разрешениями Apps Script в Google Sheets
Принцип наименьших привилегий: запрашивайте только необходимые разрешения
Всегда запрашивайте только те разрешения, которые абсолютно необходимы для работы скрипта. Избегайте использования разрешений с широким охватом, если можно использовать более узкие разрешения.
Регулярный аудит и обновление разрешений ваших скриптов
Регулярно проверяйте разрешения, запрошенные вашими скриптами. Если скрипт больше не нуждается в каком-либо разрешении, удалите его из манифеста. Также, обновляйте используемые библиотеки и API, так как новые версии могут требовать другие разрешения.
Безопасность превыше всего: рекомендации по защите данных пользователей
- Никогда не храните учетные данные пользователей в скрипте.
- Используйте безопасные методы хранения данных, такие как Properties Service или Secret Manager.
- Тщательно проверяйте входные данные, чтобы предотвратить атаки типа «injection».
- Будьте внимательны к сторонним библиотекам и API. Используйте только те, которым вы доверяете.
- Следуйте рекомендациям Google по безопасности Apps Script.