Определение и назначение сервисного аккаунта
Сервисный аккаунт – это специальный тип учетной записи Google, предназначенный для неинтерактивного использования. В отличие от обычной учетной записи пользователя, сервисный аккаунт не требует непосредственного участия человека. Он позволяет приложениям (в нашем случае, скриптам Google Apps Script) безопасно и автоматически получать доступ к сервисам Google, таким как Google Sheets, Drive, Calendar и другим, а также к сторонним API.
Сервисные аккаунты идентифицируются уникальным адресом электронной почты и аутентифицируются с помощью криптографических ключей. Это позволяет Apps Script скриптам взаимодействовать с Google сервисами от имени этого аккаунта, а не от имени пользователя, запускающего скрипт.
Отличия сервисного аккаунта от учетной записи пользователя
| Характеристика | Учетная запись пользователя | Сервисный аккаунт |
|—|—|—|
| Аутентификация | Пароль, двухфакторная аутентификация | Ключ JSON |
| Интерактивность | Требует участия пользователя | Работает в фоновом режиме |
| Назначение | Доступ к сервисам для человека | Доступ к сервисам для приложений |
| Управление | Пользователь | Администратор GCP проекта |
Основное отличие заключается в способе аутентификации и назначении. Пользовательская учетная запись требует участия человека, в то время как сервисный аккаунт предназначен для автоматической работы скриптов и приложений.
Когда следует использовать сервисный аккаунт в Apps Script
Использование сервисного аккаунта рекомендуется в следующих случаях:
- Автоматизация задач без участия пользователя: Когда необходимо, чтобы скрипт выполнялся по расписанию или в ответ на определенные события, не требуя при этом присутствия пользователя.
- Интеграция с внешними API: Если Apps Script скрипт взаимодействует с внешними API, требующими аутентификации, сервисный аккаунт позволяет безопасно хранить и использовать учетные данные.
- Предоставление доступа к данным с ограниченными правами: Сервисный аккаунт позволяет предоставить скрипту доступ только к определенным данным и функциям, минимизируя риски безопасности.
- Работа с большими объемами данных: Сервисные аккаунты обычно имеют более высокие лимиты использования, чем учетные записи пользователей, что позволяет обрабатывать большие объемы данных.
Создание и настройка сервисного аккаунта для Apps Script
Создание проекта Google Cloud Platform (GCP)
Для начала работы с сервисным аккаунтом необходимо создать проект в Google Cloud Platform (GCP). Перейдите в Google Cloud Console и создайте новый проект. Укажите название проекта и организацию (если применимо).
Включение API для Google Apps Script
В созданном проекте GCP необходимо включить API, которые будут использоваться вашим Apps Script скриптом. В частности, для работы с Apps Script необходимо включить «Apps Script API». Также, включите API для тех сервисов Google, к которым будет обращаться ваш скрипт (например, «Google Sheets API», «Google Drive API», и т.д.).
Создание сервисного аккаунта в GCP
- В Google Cloud Console перейдите в раздел «IAM & Admin» -> «Service Accounts».
- Нажмите кнопку «Create Service Account».
- Укажите имя сервисного аккаунта и его описание.
- Предоставьте сервисному аккаунту необходимые роли (например, «Editor» или более специфические роли, такие как «Storage Object Viewer» для доступа к Google Cloud Storage).
- Нажмите кнопку «Done».
Генерация ключа JSON для сервисного аккаунта
- Найдите созданный сервисный аккаунт в списке и нажмите на его имя.
- Перейдите на вкладку «Keys».
- Нажмите кнопку «Add Key» -> «Create new key».
- Выберите формат ключа «JSON» и нажмите кнопку «Create».
- Сохраните сгенерированный файл JSON в безопасном месте. Этот файл содержит закрытый ключ, который необходим для аутентификации сервисного аккаунта. Не передавайте его никому и не храните в общедоступном месте!
Использование сервисного аккаунта в Google Apps Script
Авторизация с использованием ключа JSON
Для авторизации в Apps Script необходимо использовать библиотеку googleapis. Для начала, добавьте библиотеку в ваш проект Apps Script. Затем, используйте код, представленный ниже, для авторизации.
/**
* Авторизует сервисный аккаунт для доступа к Google Sheets.
*
* @param {string} privateKey JSON ключ сервисного аккаунта.
* @param {string} clientEmail Email сервисного аккаунта.
* @return {GoogleAppsScript.Sheets.Spreadsheet} Объект Spreadsheet или null в случае ошибки.
*/
function authorizeServiceAccount(privateKey, clientEmail) {
try {
const scopes = ["https://www.googleapis.com/auth/spreadsheets"];
const oAuthService = OAuth2.createService('Sheets')
.setPrivateKey(privateKey)
.setClientEmail(clientEmail)
.setScopes(scopes);
if (!oAuthService.hasAccess()) {
Logger.log('Не удалось авторизовать сервисный аккаунт.');
return null;
}
// Пример использования Google Sheets API после успешной авторизации
const spreadsheetId = 'YOUR_SPREADSHEET_ID'; // Замените на ID вашей таблицы
const spreadsheet = SpreadsheetApp.openById(spreadsheetId);
return spreadsheet;
} catch (error) {
Logger.log('Ошибка авторизации: ' + error);
return null;
}
}
function main() {
// Вставьте данные вашего сервисного аккаунта
const privateKey = "-----BEGIN PRIVATE KEY-----\n...YOUR_PRIVATE_KEY...\n-----END PRIVATE KEY-----\n"; // Содержимое поля private_key из JSON файла
const clientEmail = "your-service-account@your-project.iam.gserviceaccount.com"; // Содержимое поля client_email из JSON файла
const spreadsheet = authorizeServiceAccount(privateKey, clientEmail);
if (spreadsheet) {
Logger.log('Авторизация прошла успешно. Имя таблицы: ' + spreadsheet.getName());
} else {
Logger.log('Авторизация не удалась.');
}
}
В этом примере используется библиотека OAuth2 for Apps Script. Установите её в ваш проект, добавив ID библиотеки 1B7FSor0LqYqYI7kY4ppEzzbcj-jYF-bgQWjvc5jC62CkMHvP0xXmI59 в меню Ресурсы -> Библиотеки. Замените YOUR_PRIVATE_KEY и your-service-account@your-project.iam.gserviceaccount.com на значения из вашего JSON файла. Также, замените YOUR_SPREADSHEET_ID на ID таблицы, к которой вы хотите получить доступ.
Делегирование прав сервисному аккаунту (Domain-wide delegation)
Если вам необходимо, чтобы сервисный аккаунт имел доступ к данным пользователей в рамках вашего домена Google Workspace, необходимо настроить делегирование прав. Это позволяет сервисному аккаунту действовать от имени любого пользователя в вашем домене. Для этого:
- Перейдите в Admin console.
- Перейдите в
Безопасность -> API controls -> Domain wide delegation. - Добавьте новый клиент API.
- В поле
Client IDукажите Client ID сервисного аккаунта (найдете в JSON файле). - В поле
OAuth Scopesукажите список scopes, к которым сервисному аккаунту нужен доступ (например,https://www.googleapis.com/auth/spreadsheets).
Примеры кода: чтение и запись в Google Sheets от имени сервисного аккаунта
/**
* Читает данные из Google Sheets от имени сервисного аккаунта.
*
* @param {GoogleAppsScript.Sheets.Spreadsheet} spreadsheet Объект Spreadsheet.
* @param {string} sheetName Имя листа.
* @param {string} range Диапазон ячеек.
* @return {any[][]} Массив значений.
*/
function readDataFromSheet(spreadsheet, sheetName, range) {
try {
const sheet = spreadsheet.getSheetByName(sheetName);
if (!sheet) {
Logger.log('Лист с именем ' + sheetName + ' не найден.');
return null;
}
const values = sheet.getRange(range).getValues();
return values;
} catch (error) {
Logger.log('Ошибка чтения данных: ' + error);
return null;
}
}
/**
* Записывает данные в Google Sheets от имени сервисного аккаунта.
*
* @param {GoogleAppsScript.Sheets.Spreadsheet} spreadsheet Объект Spreadsheet.
* @param {string} sheetName Имя листа.
* @param {string} range Диапазон ячеек.
* @param {any[][]} values Массив значений для записи.
*/
function writeDataToSheet(spreadsheet, sheetName, range, values) {
try {
const sheet = spreadsheet.getSheetByName(sheetName);
if (!sheet) {
Logger.log('Лист с именем ' + sheetName + ' не найден.');
return;
}
sheet.getRange(range).setValues(values);
Logger.log('Данные успешно записаны.');
} catch (error) {
Logger.log('Ошибка записи данных: ' + error);
}
}
function main() {
// Вставьте данные вашего сервисного аккаунта
const privateKey = "-----BEGIN PRIVATE KEY-----\n...YOUR_PRIVATE_KEY...\n-----END PRIVATE KEY-----\n"; // Содержимое поля private_key из JSON файла
const clientEmail = "your-service-account@your-project.iam.gserviceaccount.com"; // Содержимое поля client_email из JSON файла
const spreadsheet = authorizeServiceAccount(privateKey, clientEmail);
if (spreadsheet) {
const sheetName = 'Лист1';
const readRange = 'A1:B2';
const writeRange = 'C1:D2';
const data = readDataFromSheet(spreadsheet, sheetName, readRange);
if (data) {
Logger.log('Прочитанные данные: ' + JSON.stringify(data));
writeDataToSheet(spreadsheet, sheetName, writeRange, data);
} else {
Logger.log('Не удалось прочитать данные.');
}
} else {
Logger.log('Авторизация не удалась.');
}
}
Практические примеры использования сервисного аккаунта
Автоматизация задач администрирования Google Workspace
Сервисные аккаунты могут быть использованы для автоматизации рутинных задач администрирования Google Workspace, таких как:
- Создание и удаление пользователей.
- Управление группами пользователей.
- Мониторинг использования ресурсов.
- Создание отчетов.
Это позволяет существенно сэкономить время и ресурсы администраторов.
Интеграция с внешними API без участия пользователя
Сервисные аккаунты позволяют интегрировать Apps Script с внешними API без необходимости аутентификации каждого пользователя. Например, можно настроить скрипт, который автоматически получает данные из CRM системы и обновляет информацию в Google Sheets.
Планирование и выполнение задач в фоновом режиме
С помощью сервисных аккаунтов можно создавать скрипты, которые выполняются по расписанию (с использованием триггеров Apps Script) или в ответ на определенные события, не требуя участия пользователя. Это полезно для задач, таких как автоматическая отправка email-уведомлений, резервное копирование данных и т.д.
Безопасность и ограничения сервисных аккаунтов
Управление разрешениями и ролями сервисного аккаунта
Важно тщательно управлять разрешениями и ролями, назначенными сервисному аккаунту. Предоставляйте сервисному аккаунту только те права, которые необходимы для выполнения конкретной задачи. Используйте принципы наименьших привилегий.
Лучшие практики по безопасному хранению ключа JSON
Ключ JSON является самым важным элементом безопасности сервисного аккаунта. Следуйте этим рекомендациям для его безопасного хранения:
- Не храните ключ JSON в общедоступном репозитории кода.
- Не передавайте ключ JSON по электронной почте или другим небезопасным каналам.
- Используйте переменные окружения или секретные хранилища для хранения ключа JSON.
- Ограничьте доступ к файлу ключа JSON на сервере.
- Регулярно ротируйте ключи JSON.
Квоты и лимиты использования сервисных аккаунтов
Сервисные аккаунты имеют свои квоты и лимиты использования, которые могут отличаться от лимитов для обычных учетных записей пользователей. Учитывайте эти ограничения при разработке и планировании задач.
Узнать больше о квотах можно в документации Google.