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 업로드 흐름

에이전트에는 다음 한 가지 도구를 권장합니다.

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 → 감사 로그에서 토큰과 작업 순서를 확인하세요.