Что такое Google Apps Script и его возможности
Google Apps Script (GAS) — это облачная платформа для разработки на языке JavaScript, позволяющая автоматизировать, расширять и интегрировать сервисы Google Workspace (Gmail, Drive, Sheets, Docs, Calendar, Groups и другие). GAS предоставляет удобный способ создания легковесных веб-приложений и автоматизации рутинных задач без необходимости управления сложной инфраструктурой.
Возможности GAS включают создание пользовательских меню и диалоговых окон в Google Документах и Таблицах, автоматическую обработку входящих писем в Gmail, создание кастомных отчетов на основе данных из Google Analytics, управление файлами на Google Диске и, что особенно релевантно для данной статьи, администрирование пользователей и групп в Google Workspace.
Обзор Google Groups: назначение и структура
Google Groups — это сервис для создания списков рассылки и дискуссионных форумов. Группы используются для коммуникации внутри команд, отделов или всей организации, управления доступом к ресурсам Google Workspace (например, к общим дискам, календарям, сайтам), а также для настройки политик безопасности.
Каждая группа имеет уникальный email-адрес и набор участников (пользователей или другие группы). Управление членством в группах — одна из ключевых задач администрирования Google Workspace.
Зачем удалять пользователей из Google Groups с помощью Apps Script
Ручное удаление пользователей из групп, особенно при больших объемах или частых изменениях (например, увольнения сотрудников, смена проектных команд), может быть трудоемким и подверженным ошибкам. Автоматизация этого процесса с помощью Google Apps Script позволяет:
- Экономить время: Мгновенное удаление пользователей по списку или триггеру.
- Снижать ошибки: Устранение человеческого фактора при ручном поиске и удалении.
- Интегрировать процессы: Связать удаление из групп с другими системами (например, HR-системой через Google Sheets).
- Обеспечивать актуальность: Поддерживать состав групп в соответствии с текущей организационной структурой или статусом сотрудников.
Необходимые условия и настройка окружения
Получение доступа к Google Groups API в Apps Script
Для управления группами через Apps Script необходимо использовать Admin SDK Directory API, так как старый сервис GroupsApp устарел и имеет ограниченные возможности. Этот API относится к Advanced Google Services.
- Откройте редактор скриптов Google Apps Script.
- В меню выберите Службы (+).
- Найдите Admin Directory API и нажмите Добавить.
- Важно: Для выполнения операций с группами скрипту потребуются соответствующие права. Необходимо добавить нужные области OAuth в файл манифеста (
appsscript.json):
{
"timeZone": "Europe/Moscow",
"dependencies": {
"enabledAdvancedServices": [{
"userSymbol": "AdminDirectory",
"serviceId": "admin",
"version": "directory_v1"
}]
},
"oauthScopes": [
"https://www.googleapis.com/auth/admin.directory.group.member",
"https://www.googleapis.com/auth/admin.directory.group",
"https://www.googleapis.com/auth/script.external_request"
],
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8"
}
Убедитесь, что пользователь, запускающий скрипт, обладает правами администратора Google Workspace или настроена делегированная авторизация на уровне домена.
Создание нового скрипта Google Apps Script
Создайте новый скрипт через Google Drive (Создать -> Еще -> Google Apps Script) или посетив script.google.com.
Импорт библиотеки GroupsApp (если применимо, или использование Groups API напрямую)
Как упоминалось, GroupsApp устарел. Вместо него используется сервис AdminDirectory, который был добавлен на шаге активации Admin SDK Directory API. Обращение к его методам происходит через объект AdminDirectory.
Удаление пользователя из группы: пошаговая инструкция
Получение идентификатора группы (Group ID)
Для удаления пользователя требуется уникальный идентификатор группы. Это может быть:
- Email-адрес группы: Например,
marketing-team@yourdomain.com. - Уникальный ID группы: Получить его можно через Admin SDK API или из консоли администратора Google Workspace.
Использование email-адреса группы является наиболее распространенным и удобным способом.
Определение пользователя для удаления: по email или ID
Аналогично группе, пользователя можно идентифицировать по:
- Email-адресу: Например,
user.name@yourdomain.com. - Уникальному ID пользователя: Внутренний идентификатор Google Workspace.
Использование email также является предпочтительным методом для большинства сценариев.
Использование метода AdminDirectory.Members.remove() для удаления пользователя
Основной метод для удаления пользователя — AdminDirectory.Members.remove(groupKey, memberKey).
groupKey: Идентификатор группы (email или ID).memberKey: Идентификатор пользователя (email или ID).
Метод не возвращает значения при успешном выполнении, но генерирует исключение в случае ошибки.
Обработка ошибок и исключений (пользователь не найден, отсутствие прав)
При работе с API важно обрабатывать возможные ошибки:
- Пользователь не найден в группе (404 Not Found): Попытка удалить пользователя, который не является членом группы.
- Отсутствие прав (403 Forbidden): Скрипт выполняется пользователем без необходимых административных привилегий или не были предоставлены нужные OAuth scopes.
- Неверный ID группы или пользователя (400 Bad Request/404 Not Found): Указаны некорректные идентификаторы.
Используйте блоки try...catch для перехвата и логирования ошибок.
Примеры кода для удаления пользователя из группы
Пример 1: Удаление пользователя по email
/**
* Удаляет пользователя из указанной группы по его email.
*
* @param {string} userEmail Email пользователя для удаления.
* @param {string} groupEmail Email группы.
*/
function removeUserFromGroupByEmail(userEmail, groupEmail) {
try {
AdminDirectory.Members.remove(groupEmail, userEmail);
Logger.log(`Пользователь ${userEmail} успешно удален из группы ${groupEmail}.`);
} catch (error) {
Logger.log(`Ошибка при удалении пользователя ${userEmail} из группы ${groupEmail}: ${error}`);
// Здесь можно добавить более детальную обработку ошибок,
// например, проверку кода ошибки (error.details.code)
}
}
// Пример вызова:
function testRemoveUser() {
removeUserFromGroupByEmail('test.user@yourdomain.com', 'test-group@yourdomain.com');
}
Пример 2: Удаление пользователя с проверкой наличия в группе
Хотя AdminDirectory.Members.remove() выбросит ошибку, если пользователь не найден, иногда требуется явная проверка перед удалением, например, для логики интерфейса или избежания лишних вызовов API при массовой обработке.
/**
* Проверяет наличие пользователя в группе и удаляет его, если он найден.
*
* @param {string} userEmail Email пользователя.
* @param {string} groupEmail Email группы.
* @return {boolean} Возвращает true, если пользователь был найден и удален, иначе false.
*/
function removeUserIfMember(userEmail, groupEmail) {
try {
// Попытка получить информацию о членстве пользователя
AdminDirectory.Members.get(groupEmail, userEmail);
// Если пользователь найден, исключение не выброшено, можно удалять
try {
AdminDirectory.Members.remove(groupEmail, userEmail);
Logger.log(`Пользователь ${userEmail} найден и удален из группы ${groupEmail}.`);
return true;
} catch (removeError) {
Logger.log(`Ошибка при удалении пользователя ${userEmail} из группы ${groupEmail}: ${removeError}`);
return false;
}
} catch (getError) {
// Проверяем, что ошибка связана именно с отсутствием пользователя (404)
if (getError.details && getError.details.code === 404) {
Logger.log(`Пользователь ${userEmail} не найден в группе ${groupEmail}. Удаление не требуется.`);
} else {
// Другая ошибка при проверке членства
Logger.log(`Ошибка при проверке членства пользователя ${userEmail} в группе ${groupEmail}: ${getError}`);
}
return false;
}
}
// Пример вызова:
function testRemoveUserWithCheck() {
const userRemoved = removeUserIfMember('another.user@yourdomain.com', 'project-alpha@yourdomain.com');
if (userRemoved) {
// Дополнительные действия после успешного удаления
}
}
Пример 3: Массовое удаление пользователей из группы (оптимизация)
Предположим, список email для удаления находится в Google Таблице.
/**
* Массово удаляет пользователей из группы на основе списка email в Google Таблице.
*
* @param {string} spreadsheetId ID Google Таблицы.
* @param {string} sheetName Имя листа с email.
* @param {string} groupEmail Email группы, из которой удалять пользователей.
* @param {number} emailColumn Индекс колонки с email (начиная с 1).
*/
function bulkRemoveUsersFromGroup(spreadsheetId, sheetName, groupEmail, emailColumn) {
const ss = SpreadsheetApp.openById(spreadsheetId);
const sheet = ss.getSheetByName(sheetName);
if (!sheet) {
Logger.log(`Лист с именем ${sheetName} не найден.`);
return;
}
// Получаем все email из указанной колонки, пропуская заголовок
const emailRange = sheet.getRange(2, emailColumn, sheet.getLastRow() - 1, 1);
const emailsToRemove = emailRange.getValues().flat().filter(String); // flat() для одномерного массива, filter(String) для удаления пустых строк
if (emailsToRemove.length === 0) {
Logger.log('Список email для удаления пуст.');
return;
}
Logger.log(`Начинается удаление ${emailsToRemove.length} пользователей из группы ${groupEmail}...`);
let removedCount = 0;
let errorCount = 0;
emailsToRemove.forEach(userEmail => {
try {
// Небольшая задержка между запросами, чтобы не превысить квоты API
Utilities.sleep(300); // 300 миллисекунд
AdminDirectory.Members.remove(groupEmail, userEmail);
Logger.log(`Успешно удален: ${userEmail}`);
removedCount++;
} catch (error) {
// Логируем ошибку, но продолжаем обработку остальных
if (error.details && error.details.code === 404) {
Logger.log(`Пользователь ${userEmail} не найден в группе ${groupEmail}. Пропущен.`);
} else {
Logger.log(`Ошибка при удалении ${userEmail}: ${error}`);
}
errorCount++;
}
});
Logger.log(`Завершено. Удалено: ${removedCount}, Ошибок/Пропущено: ${errorCount}.`);
}
// Пример вызова:
function testBulkRemove() {
const SPREADSHEET_ID = 'YOUR_SPREADSHEET_ID'; // Замените на ID вашей таблицы
const SHEET_NAME = 'UsersToRemove'; // Замените на имя вашего листа
const GROUP_EMAIL = 'departed-employees@yourdomain.com'; // Целевая группа
const EMAIL_COLUMN_INDEX = 1; // Колонка A
bulkRemoveUsersFromGroup(SPREADSHEET_ID, SHEET_NAME, GROUP_EMAIL, EMAIL_COLUMN_INDEX);
}
Дополнительные возможности и оптимизация
Автоматизация процесса удаления пользователей (например, по расписанию)
С помощью триггеров Google Apps Script можно настроить регулярный запуск скрипта (например, ежедневно или еженедельно) для автоматического удаления пользователей из групп. Это полезно для синхронизации с внешними данными или выполнения плановых чисток.
- В редакторе скриптов перейдите в раздел Триггеры (значок будильника).
- Нажмите Добавить триггер.
- Выберите функцию для запуска (например,
testBulkRemove), источник события (Триггер по времени), тип триггера (например, Дневной таймер) и время выполнения.
Интеграция с другими Google Workspace сервисами (Sheets, Forms)
- Google Sheets: Как показано в примере 3, можно использовать Таблицы как источник данных для массового удаления. Это позволяет легко управлять списками пользователей нетехническим специалистам.
- Google Forms: Можно создать Форму для запроса на удаление пользователя из группы. При отправке формы триггер
onFormSubmitможет запускать Apps Script, который обработает запрос и удалит пользователя.
Советы по оптимизации скрипта для больших групп
- Используйте
AdminDirectory.Members.list()с осторожностью: Получение полного списка участников большой группы может быть медленным и ресурсоемким. Если нужно проверить членство перед удалением,AdminDirectory.Members.get()для конкретного пользователя эффективнее. - Обрабатывайте квоты API: При массовых операциях учитывайте квоты Google Admin SDK API. Используйте
Utilities.sleep()для вставки пауз между запросами, чтобы избежать ошибокRate Limit Exceeded. - Логирование: Используйте
Logger.logили Stackdriver Logging для отслеживания выполнения и диагностики проблем, особенно при работе с большими объемами данных или по расписанию. - Пакетные запросы (Batch Requests): Для очень больших объемов операций рассмотрите возможность использования пакетных запросов к Google API (требует более сложной реализации с
UrlFetchApp), что позволяет объединить несколько вызовов API в один HTTP-запрос, значительно снижая количество запросов и увеличивая скорость.