개발자를 위한 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"

응답에는 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를 우선 사용하세요. 시작, 전송, 완료, 중단 단계를 하나의 도구로 처리합니다.

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 명세에서 요구하면 멱등성 키를 사용하세요. 이 흐름에서는 폴더 생성, 업로드 시작, 공유 링크 생성에 필요합니다.
• 개발 후 테스트 토큰을 취소하세요.