面向开发者的 Drive API 快速入门

本快速入门介绍从“我想进行集成”到成功调用 Drive API 的最安全路径。你将创建权限严格受限的令牌，列出 Drive 空间，上传一个文件，并创建带到期日期的公开共享链接。

1. 创建 Drive 令牌

打开 AI 代理与 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"}'

保存返回的文件夹 ID。

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. 检查审计记录

打开 AI 代理与 API → 审计日志，并按令牌筛选。你应看到文件夹创建、上传、完成和共享链接创建记录。这是确认集成使用预期令牌和权限范围的最快方法。

生产环境检查清单

• 每个集成使用一个令牌。
• 分别授予读取、写入和共享权限；不要在日常工作流中授予永久清除权限。
• 为公开链接添加到期时间和下载次数上限。
• 当端点文档或 OpenAPI 规范要求时使用幂等键。在此流程中，包括创建文件夹、发起上传和创建共享链接。
• 开发完成后撤销测试令牌。