Drive 공유 링크 API 및 MCP 가이드

공유 링크를 사용하면 큰 이메일 첨부 파일을 보내지 않고도 TrekMail 계정 외부에 Drive 파일을 전달할 수 있습니다. API와 MCP 도구는 링크를 생성하고, 파일의 링크를 조회하고, 액세스를 종료해야 할 때 링크를 취소할 수 있습니다.

고객에게 전달할 결과물, 청구서, 동영상 파일, 내보내기 묶음 및 이메일에 첨부하기에는 너무 크거나 일시적인 파일에 공유 링크를 사용하세요.

필수 범위

계정 Drive 파일에는 drive:account:share를 사용하세요. 사서함 Drive 파일에는 drive:mailbox:share를 사용하세요. 대부분의 워크플로에서는 공유하기 전에 파일을 찾아야 하므로 읽기 범위도 유용합니다.

공유 범위는 업로드, 이름 변경, 이동, 휴지통으로 이동, 복원 또는 완전 삭제를 허용하지 않습니다. 에이전트의 유일한 작업이 파일 전달이라면 이러한 권한을 다른 권한과 분리하세요.

REST로 링크 생성하기

curl -s -X POST "https://trekmail.net/api/v1/drive/files/{FILE_ID}/share-links" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: share-{FILE_ID}-client-a" \
  -d '{"expires_at":"2026-06-01T00:00:00Z","max_downloads":25}'

응답에는 공개 URL이 포함됩니다. 원본 공유 토큰은 생성 시에만 반환됩니다. 토큰을 잃어버린 경우 링크를 취소하고 새 링크를 생성하세요.

MCP로 링크 생성하기

drive_share_create(file_id=123, expires_at="2026-06-01T00:00:00Z", max_downloads=25)

에이전트가 최종 답변에 URL을 반환하고 만료일과 다운로드 한도를 명시하도록 요청하세요.

링크 조회 및 취소

목록 endpoint 또는 drive_share_list를 사용하여 파일의 활성 링크와 이전 링크를 확인하세요. 링크가 잘못된 사람에게 전송되었거나, 계약이 더 이상 유효하지 않거나, 임시 전달 기간이 종료된 경우 링크를 취소하세요.

drive_share_revoke(link_id=456)

취소는 즉시 적용됩니다. 액세스를 복원해야 한다면 새 링크를 생성하세요.

권장 기본값

무제한 링크는 편리하지만 나중에 상황을 판단하기가 더 어렵습니다. 만료일을 설정하지 않기로 했다면 그 이유를 설명하는 메모를 자체 시스템에 추가하세요.

보안 동작

공유 링크는 URL을 가진 모든 사람에게 공개됩니다. TrekMail 로그인이 아니라 추측할 수 없는 토큰으로 보호됩니다. 조직에서 이 모델을 허용하지 않는다면 지정된 수신자만 액세스해야 하는 파일에 공개 링크를 보내지 마세요.

다운로드 페이지는 불필요한 계정 세부 정보를 노출하지 않습니다. 만료되었거나 취소되었거나 한도를 모두 사용한 링크는 비공개 파일 정보를 노출하지 않고 실패합니다.

감사 추적

공유 링크 생성과 취소는 API 토큰 ID와 함께 감사 기록에 남습니다. 에이전트가 고객을 위해 링크를 생성한다면 감사 로그를 주기적으로 검토하고 팀의 담당 업무가 변경될 때 토큰을 교체하세요.