Команда Google AI представила утилиту командной строки (CLI) под названием gws, предназначенную для взаимодействия с API Google Workspace. Этот инструмент предлагает унифицированный интерфейс для работы с сервисами Google, такими как Drive, Gmail, Calendar и Sheets, упрощая интеграцию для разработчиков и агентов ИИ.
Устранение рутинных задач при работе с API
Традиционно, для интеграции API Google Workspace в приложения или конвейеры данных, требовалось написание шаблонного кода, который обрабатывал бы REST-запросы, пагинацию и процессы аутентификации OAuth 2.0. gws, будучи проектом с открытым исходным кодом (googleworkspace/cli), стремится устранить эту необходимость, предлагая динамический интерфейс командной строки для управления перечисленными сервисами.
Инструмент разработан с учетом потребностей как инженеров-разработчиков, так и систем искусственного интеллекта. Он исключает требование к созданию пользовательских скриптов-оберток, предоставляя данные в стандартизированном формате JSON, интегрируя поддержку Model Context Protocol (MCP) и автоматизируя процедуры аутентификации.
Архитектура динамического обнаружения API
В отличие от большинства CLI-инструментов, которые оперируют статическим набором команд, gws генерирует свою командную структуру в реальном времени. Этот процесс состоит из двухфазной стратегии парсинга:
- Первый аргумент команды используется для идентификации целевого сервиса, например, drive.
- Далее gws извлекает Google Discovery Document для этого сервиса (документы кешируются на 24 часа).
- На основе полученного документа формируется дерево команд, включающее ресурсы и методы.
- Заключительный этап включает парсинг оставшихся аргументов, аутентификацию и выполнение соответствующего HTTP-запроса.
Такой подход позволяет gws автоматически поддерживать новые конечные точки API Google Workspace сразу после их добавления в Discovery Service.
Основные возможности для инженеров-разработчиков и специалистов по данным
Установка CLI возможна через npm командой npm install -g @googleworkspace/cli, либо путём сборки из исходного кода с помощью cargo install --path .. После установки gws предоставляет набор встроенных утилит для извлечения данных и автоматизации:
- Интроспекция и предварительный просмотр: Для каждого ресурса доступна документация --help, автоматически генерируемая из Discovery API. Разработчики могут просматривать схему любого метода (например, gws schema drive.files.list) или использовать флаг --dry-run для предварительного просмотра HTTP-запроса перед его выполнением.
- Извлечение структурированных данных: По умолчанию все ответы, включая ошибки и метаданные, возвращаются в виде структурированного JSON.
- Автоматическая пагинация: При работе с большими наборами данных флаг --page-all автоматически управляет курсорами API, возвращая результаты в формате NDJSON (JSON, разделенный новой строкой). Это удобно для прямой передачи данных в консольные JSON-процессоры, как показано в примере:
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'
Интеграция с агентами ИИ и MCP
Одной из ключевых областей применения gws является его использование в качестве бэкенда для вызова инструментов большими языковыми моделями (LLM).
- Сервер Model Context Protocol (MCP): Запуск gws mcp -s drive,gmail,calendar активирует MCP-сервер через stdio. Это позволяет предоставлять API Workspace в виде структурированных инструментов, которые могут быть нативно вызваны любым MCP-совместимым клиентом (например, Claude Desktop или VS Code).
- Готовые навыки для агентов: Репозиторий включает более сотни готовых навыков для агентов, охватывающих все поддерживаемые API и общие рабочие процессы. Инженеры, работающие с ИИ, могут напрямую интегрировать их в свои среды агентов, используя команду npx skills add github:googleworkspace/cli.
- Расширение для Gemini CLI: Разработчики, использующие Gemini CLI, могут установить расширение gws (gemini extensions install https://github.com/googleworkspace/cli), что позволяет локальному агенту Gemini наследовать учетные данные gws и управлять ресурсами Workspace.
- Model Armor (санитаризация ответов): Для снижения рисков, связанных с инъекциями в промпт при передаче данных API в LLM, gws поддерживает Google Cloud Model Armor. Флаг --sanitize позволяет сканировать ответы API на наличие вредоносных данных до того, как они достигнут агента.
Авторизация
CLI обеспечивает безопасную аутентификацию в различных средах, исключая необходимость ручного управления токенами в пользовательских скриптах. Приоритет аутентификации устанавливается следующим образом: явные токены, затем файлы учетных данных, и наконец, локальное хранилище ключей операционной системы.
- Локальная среда: Команда gws auth setup инициирует интерактивный процесс настройки проекта Google Cloud, активации необходимых API и выполнения входа через OAuth. Учетные данные шифруются с использованием AES-256-GCM и сохраняются в системном хранилище ключей.
- Безголовые системы / CI/CD: Для серверных сред можно выполнить интерактивную аутентификацию локально, а затем экспортировать учетные данные в виде открытого текста:
gws auth export --unmasked > credentials.json
На безголовой машине путь к этому файлу указывается через переменную окружения: export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json.
- Сервисные аккаунты: gws предоставляет нативную поддержку файлам ключей сервисных аккаунтов для взаимодействия между серверами, а также делегирование на уровне домена (Domain-Wide Delegation) через переменную GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER.