# Google Диск
> Документы, таблицы и презентации Google как контекст: чтение, вопросы в комментариях, отчёт документом, область, сервисный аккаунт или своя учётная запись.
Google Диск для команды — **письменный контекст**, которого нет ни в задаче, ни в коде:
спецификация в документе, план в таблице, решения в презентации. Интеграция даёт модели
читать всё это, когда нужно для ответа, принимает вопросы прямо в комментариях к
документу, таблице или презентации и умеет оставлять результат **документом**, а не
только комментарием.
_Иллюстрация: Вопрос, ответ на который записан только в документе: модель сходила инструментом на Диск и ответила по нему._
## Инструменты
| Инструмент | Что делает |
|---|---|
| `search_files` | ищет документы, таблицы, презентации и папки по словам — в названии **и в тексте**: поиск делает сам Диск, по содержимому файлов |
| `get_file` | читает файл целиком: документ — как markdown, таблицу — все листы таблицами, презентацию — текстом, папку — списком содержимого; текстовый файл — как есть; вместе с обсуждением |
| `list_folder` | перечисляет содержимое папки — вложенные папки и файлы с их видом |
| `get_sheet` | один лист или диапазон таблицы (`Бюджет`, `A1:D20`) — когда таблица большая и нужна её часть |
| `get_comments` | обсуждения файла: ветки комментариев с ответами, кто и когда писал |
| `add_comment` | комментарий к файлу или ответ в ветке |
| `create_document` | документ Google из markdown — в папке области подключения |
Пять первых только читают и доступны везде, где модели даются инструменты коннектора —
в «Спросить» и в глубоком исследовании. Два пишущих модели не достаются ни на одной
стадии: ими пользуется сам коннектор, когда по команде платформы возвращает ответ
комментарием или отчёт исследования новым документом — и только внутри области.
**Документ приходит как markdown, таблица — таблицами.** Документ Google экспортируется
одним вызовом в markdown — заголовки, списки, таблицы, код, ссылки; интеграция ничего не
дополняет и ничего не обрезает. Таблица читается через Sheets API лист за листом, каждый
— markdown-таблицей с заголовком из первой строки; лист на тысячу строк остаётся листом
на тысячу строк. Презентация приходит текстом слайдов. Двоичный файл (архив, видео)
интеграция называет по виду и размеру, а не притворяется, что прочитала.
## Обращения в комментариях
Всё, что описано в [«Интеграциях с трекерами»](/docs/connector/trackers), работает и
здесь: `@buff <вопрос>`, `@buff research …`, `@buff task …` или `/ask`, `/research`,
`/task` в комментарии к документу, таблице или презентации — это вопрос, исследование или
черновик задачи. Ответ приходит **в ту же ветку** — ответом на комментарий; вопрос в новом
комментарии начинает новый разговор.
К боту обращаются **упоминанием его адреса** — в Google Docs это `+адрес` или `@адрес`,
подсказка сама подставит имя, — **именем учётной записи** или **псевдонимом** из настроек
(`buff`), написанным словом в тексте. Регистр не важен.
У документа нет ветки кода, поэтому ответ считается на уровне проекта разработки — или
[пространства](/docs/quickstart/space) — к которому привязано подключение.
### Исследование — документом
Ответ на `/research` не кладётся в комментарий: в папке документа, где спросили, появляется
**новый документ Google** с отчётом — сам текст, а не картинка текста, — и рядом с ним
PDF-файл. В ветку обсуждения приходит ответ со ссылкой на отчёт и на исследование в Buff.
Документ создаётся только внутри области.
## Область
В подключении перечисляются **корни** — ссылки или идентификаторы папок и файлов. Бот
работает в них и во всём, что вложено: файл считается «своим», если среди его родителей
есть корень (папка → папка → документ). Так же ограничена запись: ответить, создать
документ или комментарий вне области нельзя. Общие диски всегда в поле зрения — документ на
общем диске такой же ваш, как в «Моём диске».
**Пустой список корней означает «всё, что открыто учётной записи на Диске».** Для
сервисного аккаунта это те папки и файлы, которыми с ним поделились; для своей учётной
записи — весь её Диск и всё, чем с ней поделились. Это отличается от трекеров, где пустой
список означает «нигде», — семантика решается для каждого источника отдельно.
Права учётной записи в Google — внешняя граница, список корней — внутренняя; разумно
иметь обе: поделитесь с сервисным аккаунтом папкой, а не всем Диском.
## Два способа войти
Интеграция принимает учётные данные **двух видов** — выбор в форме подключения, и
коннектор в обоих случаях выпускает токены доступа сам: Google выдаёт их на час, и
обновлять их — забота коннектора, не ваша. Плагин ни ключа, ни токена не видит.
### Сервисный аккаунт — для команды
Отдельная учётная запись-робот в вашем проекте Google Cloud. Вы делитесь с её адресом
папками — как с коллегой, — и бот работает от своего имени: его комментарии подписаны
им, а не кем-то из людей. Коннектор подписывает JWT ключом аккаунта и обменивает его на
токен доступа.
1. В [консоли Google Cloud](https://console.cloud.google.com/) создайте проект (или
возьмите существующий) и включите в нём **Google Drive API** и **Google Sheets API**.
2. **IAM и администрирование → Сервисные аккаунты** → создайте аккаунт; роли в проекте
ему не нужны.
3. У аккаунта откройте **Ключи → Добавить ключ → JSON** — скачается файл ключа. Его
содержимое целиком — это учётные данные для коннектора.
4. На Диске **поделитесь** нужными папками и файлами с адресом аккаунта
(`имя@проект.iam.gserviceaccount.com`) с правом «Комментатор» для чтения и ответов или
«Редактор», если нужны документы-отчёты.
Документ, который сервисный аккаунт создаёт в чужой папке «Моего диска», принадлежит
ему, а не владельцу папки. На **общем диске** этого нет — файлы там принадлежат диску.
Если отчёты должны оставаться у команды, отметьте папку на общем диске.
### Своя учётная запись — для себя
Личный Диск подключается **от своего имени**: бот читает всё, что видите вы, и отвечает
как вы. Нужен собственный OAuth-клиент — Google не выдаёт общий, и создаётся он один раз.
1. В консоли Google Cloud включите **Google Drive API** и **Google Sheets API**.
2. **API и сервисы → Экран согласия OAuth**: тип «Внешний», добавьте себя в тестовые
пользователи. Пока приложение в режиме тестирования, Google показывает экран
«Приложение не проверено» — для своего клиента это нормально, нажмите «Продолжить».
3. **API и сервисы → Учётные данные → Создать → Идентификатор клиента OAuth**, тип
**«Компьютерное приложение»** (Desktop app). Скопируйте client ID и client secret —
или скачайте JSON-файл клиента, коннектор принимает его целиком.
4. В коннекторе выберите способ «вход через свою учётную запись», вставьте их и
**сохраните** подключение.
5. Нажмите **«Войти»**: откроется Google, вы дадите согласие — на экране согласия
**отметьте доступ к Диску**, галочка по умолчанию снята, — и Google вернёт браузер на
локальную страницу коннектора. Готово — вход выполнен, на странице видно, от чьего
имени работает подключение. Если галочку пропустили, проверка связи скажет
«insufficient authentication scopes»: нажмите «Войти заново».
Коннектор на сервере, а браузер — на вашем ноутбуке? Google всё равно вернёт браузер на
адрес `127.0.0.1` коннектора — страница не откроется. Скопируйте адрес из адресной строки
этой пустой страницы (в нём код) и вставьте его в поле «адрес страницы, на которую вернул
источник» на странице коннектора. Тот же вход, только руками. Через SSH-туннель до
локальной страницы возврат приходит сам.
Refresh-токен хранится в файле учётных данных на вашей машине; пока он действует, входить
заново не нужно. Отозвать доступ можно в
[настройках аккаунта Google](https://myaccount.google.com/permissions) — подключение тогда
скажет об этом словами Google при проверке связи.
_Иллюстрация: Способ входа выбирается в форме; после сохранения появляется кнопка «Войти» и поле для возврата вручную._
## События — опрос
У Диска **нет ленты комментариев** по всем файлам, а push-уведомления Google требуют
проверенный HTTPS-домен, которого у коннектора нет. Поэтому обращения находит **опрос**:
интеграция обходит документы области по кругу, несколько за проход, и спрашивает у каждого
комментарии, изменённые после начала чтения. По умолчанию **раз в 5 секунд**: интервал —
настройка подключения. Лимит Drive API — 12 000 запросов в минуту на пользователя, так что
даже большая область укладывается с запасом; ответы `429` и `403 rateLimitExceeded`
интеграция выжидает так, как просит Google.
_Иллюстрация: Форма настройки: адреса API подставлены, остаётся выбрать способ входа, назвать корни и интервал опроса._
## Настройка
| Поле | Значение |
|---|---|
| Адрес Drive API, Sheets API | подставлены — менять не нужно |
| Адреса входа и выдачи токенов | подставлены — менять не нужно |
| Способ входа для `api` | **сервисный аккаунт (JSON-ключ)** или **вход через свою учётную запись (OAuth)** |
| Учётные данные `api` | содержимое JSON-ключа целиком — или client ID и client secret своего OAuth-клиента |
| Папки и файлы | ссылки или идентификаторы корней, через запятую; пусто — всё, что открыто учётной записи |
| Как ещё к боту обращаются | короткое имя, например `buff` |
| Интервал опроса | секунды; пусто — как предлагает интеграция, 5 |
Проверка связи говорит не «ок», а от чьего имени работает подключение — сервисный аккаунт
или учётная запись, с адресом, — сколько корней в области и сколько из них реально
доступно.
Из командной строки: `connector install google-drive`, затем
`connector instance set --plugin google-drive --version 1.0.0 --set roots=<ссылка>,<ссылка> --poll 5`
и `connector instance secret <подключение> --secret api --kind service_account` (ключ —
со стандартного ввода). Для своей учётной записи — `--kind oauth2` с JSON вида
`{"client_id":"…","client_secret":"…"}`, затем `connector instance signin <подключение> --secret api`:
команда напечатает адрес для входа и примет адрес возврата.
_Иллюстрация: Проверка связи: от чьего имени работает подключение и сколько корней доступно._
## Чего интеграция не делает
- **Не редактирует существующие документы, таблицы и презентации** — только читает их,
пишет комментарии и создаёт новые документы внутри области.
- **Не копирует и не индексирует** содержимое Диска к нам: читается то, что понадобилось
для конкретного ответа, и попадает в контекст этого ответа.
- **Не получает push-уведомления** — обращения находит опрос.
- **Не работает с Gmail, Календарём и Формами** — только с Диском, Документами, Таблицами
и Презентациями.