Drive API によるファイルアップロードの自動化

アップロードの自動化は、Drive API で特に役立つワークフローです。レポート、請求書、生成したエクスポート、署名済み PDF、サポート添付ファイルを、手動操作なしで適切な TrekMail Drive フォルダーに保存できます。

安全な手順は、容量の確認、フォルダーの作成または選択、アップロードの開始、バイトの転送、アップロードの完了、監査証跡の記録です。

推奨スコープ

アカウント Drive へのアップロードには次を使用します。

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

メールボックス Drive へのアップロードには次を使用します。

• drive:mailbox:read
• drive:mailbox:write

同じワークフローで本当に必要な場合を除き、共有と完全削除のスコープは避けてください。公開リンクも作る場合は、対応する共有スコープを追加します。

事前確認

大きなファイルの前に、ストレージ概要または使用量 endpoint を呼び出します。「容量超過」はクラッシュではなく通常の業務結果として処理してください。

保存先フォルダーの存在も確認します。存在しない場合は冪等性キーを使って作成し、再試行による重複を防ぎます。

REST アップロードフロー

1. ファイル名、サイズ、任意のフォルダー ID、MIME タイプを指定して POST /api/v1/drive/spaces/{space}/uploads:initiate を送信します。
2. 返されたアップロード URL またはマルチパート URL にバイトを送信します。
3. 転送成功後に POST /api/v1/drive/uploads/{file}:complete を送信します。
4. 失敗時は POST /api/v1/drive/uploads/{file}:abort を呼び出して予約を解放します。

容量を予約する開始リクエストには Idempotency-Key を使います。論理ファイルごとに invoice-2026-05-001-upload のような安定したキーを使ってください。後続 endpoint が必ず冪等な結果を再現するとは限りません。返されたファイル ID を保存し、完了の再試行や中止の前に状態を確認します。

MCP アップロードフロー

エージェントには 1 つのツールを推奨します。

drive_file_upload(space="account", local_path="/exports/report.pdf", folder_id=42)

MCP ラッパーが交渉、転送、完了、エラー時の中止を処理します。低レベルツールもありますが、多くのワークフローでは不要です。

名前とフォルダーの規則

後で探しやすい予測可能な名前を使います。

• Reports/2026/05/monthly-summary.pdf
• Clients/Acme/contracts/acme-renewal-2026.pdf
• Invoices/2026/INV-2026-0042.pdf

複数バージョンには時刻やバージョンラベルを含めます。毎週 final.pdf をアップロードして意味を失わないでください。

障害処理

次のケースに備えます。

アップロード後

外部配信用なら有効期限とダウンロード上限付きの共有リンクを作ります。内部用なら通常の Drive ファイルのままにします。AI エージェントと API → 監査ログでトークンと操作順序を確認してください。