Автоматизация загрузки файлов с помощью API Drive
Безопасно автоматизируйте загрузки TrekMail Drive: ключи идемпотентности, проверка квоты, составная загрузка, MCP и обработка сбоев.
Сведения о статье
Тип, сложность, тарифы и дата последнего обновления.
▼
Сведения о статье
Тип, сложность, тарифы и дата последнего обновления.
- Тип
- Справочная статья
- Сложность
- Средний уровень
- Тарифы
- Starter · Pro · Agency · + Drive Add-on
- Обновлено
- 10 сен 2026 г.
Автоматизация загрузки является одним из самых полезных рабочих процессов API Drive. Отчеты, счета, сформированные выгрузки, подписанные PDF и вложения службы поддержки могут попадать в нужную папку TrekMail Drive без ручного перетаскивания.
Безопасная схема проста: проверьте хранилище, создайте или выберите папку, начните загрузку, передайте байты, завершите загрузку и создайте полезную запись аудита.
Рекомендуемые области доступа
Для загрузки в Drive учетной записи начните с:
drive:account:readdrive:account:write
Для загрузки в Drive почтового ящика используйте:
drive:mailbox:readdrive:mailbox:write
Не предоставляйте области для общего доступа и безвозвратного удаления, если они действительно не нужны тому же процессу. Если задание также создает публичные ссылки, добавьте соответствующую область общего доступа.
Предварительные проверки
Перед загрузкой большого файла вызовите endpoint сводки хранилища или использования пространства. Интеграция должна обрабатывать результат "квота превышена" как обычную рабочую ситуацию, а не как сбой.
Также проверяйте наличие целевой папки. Если ее нет, создайте ее с ключом идемпотентности, чтобы повторные попытки не создавали дубликаты.
Процесс загрузки REST
- Отправьте
POST /api/v1/drive/spaces/{space}/uploads:initiate, указав имя, размер файла, необязательный ID папки и тип MIME. - Отправьте байты файла на полученный URL загрузки или URL составной загрузки.
- После успешной передачи отправьте
POST /api/v1/drive/uploads/{file}:complete. - При сбое передачи вызовите
POST /api/v1/drive/uploads/{file}:abort, чтобы быстро освободить резерв.
Для начального запроса, резервирующего объем, используйте Idempotency-Key. Применяйте стабильный ключ для каждого логического файла, например invoice-2026-05-001-upload. Не считайте, что все последующие endpoints повторяют идемпотентные результаты. Сохраните полученный ID файла и проверяйте его состояние перед повторным завершением или отменой передачи.
Процесс загрузки MCP
Для агентов предпочтителен один инструмент:
drive_file_upload(space="account", local_path="/exports/report.pdf", folder_id=42)
Обертка MCP выполняет согласование, передачу, завершение и отмену при ошибке. Для особой логики доступны низкоуровневые инструменты, но большинству процессов они не нужны.
Правила именования и структуры папок
Используйте предсказуемые имена, чтобы людям было удобно просматривать Drive:
Reports/2026/05/monthly-summary.pdfClients/Acme/contracts/acme-renewal-2026.pdfInvoices/2026/INV-2026-0042.pdf
Если агент загружает разные версии, добавляйте временные метки или номера версий. Не скрывайте смысл, загружая final.pdf каждую неделю.
Обработка сбоев
Предусмотрите следующие случаи:
| Проблема | Рекомендуемое действие |
|---|---|
| У токена нет области доступа | Остановитесь и запросите токен с недостающей областью Drive |
| Квота превышена | Сообщите текущее использование и дайте ссылку на документацию хранилища или дополнения |
| URL загрузки истек | Обновите части или перезапустите загрузку |
| Сбой сети во время передачи | Отмените резерв и повторите с тем же логическим ключом идемпотентности |
| Папка не найдена | Повторно получите дерево папок; создавайте папку только с разрешения рабочего процесса |
После загрузки
Для внешней передачи создайте ссылку с датой окончания и лимитом скачиваний. Внутренний файл оставьте обычным файлом Drive. В любом случае проверьте ИИ-агенты и API → Журнал аудита, чтобы подтвердить токен и последовательность действий.
Связанные статьи
Похожие статьи
Перейдите к близким руководствам, которые продолжают рабочий процесс.