Быстрый старт с Drive API для разработчиков

В этом руководстве показан самый безопасный путь от идеи интеграции до рабочего вызова Drive API. Вы создадите токен с узкими правами, получите список пространств Drive, загрузите файл и создадите общедоступную ссылку со сроком действия.

1. Создайте токен Drive

Откройте ИИ-агенты и API → Токены → Создать токен. Дайте токену понятное имя, например drive-report-uploader. Выберите только те права, которые нужны вашему рабочему процессу.

Для этого руководства используйте:

• drive:account:read
• drive:account:write
• drive:account:share

Не добавляйте права необратимого удаления в первую интеграцию. Для окончательного удаления используйте отдельный служебный токен.

Скопируйте токен сразу после создания. TrekMail показывает его открытое значение один раз и хранит только безопасный хеш.

2. Задайте базовый URL и токен

export TREKMAIL_BASE_URL="https://trekmail.net"
export TREKMAIL_API_TOKEN="tm_live_your_token"

Каждый запрос использует один и тот же заголовок bearer:

-H "Authorization: Bearer $TREKMAIL_API_TOKEN"

3. Получите список доступных пространств Drive

curl -s "$TREKMAIL_BASE_URL/api/v1/drive/spaces" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN"

Ответ содержит Drive аккаунта и пространства Drive почтовых ящиков, доступные токену. В следующих примерах используйте account для Drive аккаунта.

4. Создайте папку

Операции записи должны включать ключ идемпотентности. Если сеть повторит запрос, TrekMail сможет вернуть исходный результат вместо создания дубликатов.

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/spaces/account/folders" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: folder-$(date +%s)" \
  -d '{"name":"API Uploads","color":"#2563eb"}'

Сохраните идентификатор созданной папки.

5. Загрузите файл

REST API отделяет согласование загрузки от передачи файла. Сначала начните загрузку:

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/spaces/account/uploads:initiate" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: upload-report-001" \
  -d '{"name":"report.pdf","size_bytes":123456,"folder_id":42,"client_mime":"application/pdf"}'

TrekMail вернет инструкции. Отправьте байты на полученный URL загрузки, затем вызовите:

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/uploads/{FILE_ID}:complete" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Если вы используете MCP, выбирайте drive_file_upload. Этот инструмент объединяет запуск, передачу, завершение и отмену загрузки.

6. Создайте общедоступную ссылку

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/files/{FILE_ID}/share-links" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: share-report-001" \
  -d '{"expires_at":"2026-06-01T00:00:00Z","max_downloads":25}'

Открытое значение токена ссылки показывается только в возвращенном общедоступном URL. Сохраните его сейчас, если планируете отправить позже.

7. Проверьте журнал аудита

Откройте ИИ-агенты и API → Журнал аудита и отфильтруйте записи по токену. Вы должны увидеть создание папки, загрузку, завершение и создание ссылки. Так проще всего убедиться, что интеграция использует ожидаемые токен и права.

Контрольный список для рабочей среды

• Используйте отдельный токен для каждой интеграции.
• Выдавайте права чтения, записи и общего доступа отдельно; исключите необратимое удаление из повседневных процессов.
• Устанавливайте срок действия и лимит скачиваний для общедоступных ссылок.
• Используйте ключ идемпотентности, когда этого требует документация конечной точки или спецификация OpenAPI. Здесь он нужен при создании папки, запуске загрузки и создании ссылки.
• Отзывайте тестовые токены после разработки.

Связанные статьи

• Обзор Drive API
• Автоматизация загрузки файлов через Drive API
• Руководство по API и MCP для общедоступных ссылок