開発者向け Drive API クイックスタート

このガイドでは、統合の構想から実際の Drive API 呼び出しまでを最も安全に進める方法を説明します。権限を限定したトークンを作成し、Drive スペースを一覧表示して、ファイルを1つアップロードし、有効期限付きの公開共有リンクを作成します。

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"

レスポンスには Account Drive と、トークンが参照できるメールボックスの Drive スペースが含まれます。以降の例では Account Drive に account を使用します。

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 を優先してください。開始、転送、完了、中止の各手順が1つのツールにまとめられています。

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 → 監査ログを開き、トークンで絞り込みます。フォルダー作成、アップロード、完了、共有リンク作成が表示されます。統合が想定したトークンとスコープを使用しているかを最短で確認できます。

本番環境のチェックリスト

• 統合ごとに1つのトークンを使用します。
• 読み取り、書き込み、共有を個別に付与し、日常のワークフローから完全消去を除外します。
• 公開リンクに有効期限とダウンロード回数の上限を設定します。
• エンドポイントのドキュメントまたは OpenAPI 仕様で必要な場合は冪等性キーを使います。このフローではフォルダー作成、アップロード開始、共有リンク作成が該当します。
• 開発後にテスト用トークンを取り消します。