API/MCP를 통한 Drive 대량 파일 작업

대량 작업을 사용하면 통합에서 한 번의 요청으로 여러 Drive 파일과 폴더에 작업을 수행할 수 있습니다. 오래된 폴더를 보관하거나, 잘못된 정리를 복구하거나, 생성된 보고서를 이동하거나, 검토를 마친 휴지통을 비울 때 유용합니다.

대량 작업은 많은 데이터에 영향을 줄 수 있으므로 보수적인 범위, 미리 보기 및 감사 검토를 포함해 설계하세요.

대량 작업으로 할 수 있는 일

Drive는 다음 대량 작업을 지원합니다.

• 파일과 폴더를 휴지통으로 이동합니다.
• 휴지통에서 파일과 폴더를 복원합니다.
• 파일과 폴더를 대상 폴더로 이동합니다.
• 휴지통에 있는 파일과 폴더를 영구 삭제합니다.

대량 요청에는 선택한 ID를 최대 5,000개까지 포함할 수 있습니다. 더 큰 정리 작업은 제한 없는 단일 작업 대신 검토를 마친 여러 배치로 실행하세요.

ID 선택

탐색, 폴더 트리, 검색 또는 전체 선택 도우미를 사용해 ID 목록을 만드세요. MCP에는 에이전트가 수동으로 페이지를 넘기지 않고도 "이 폴더의 모든 항목"이 필요한 워크플로를 위한 drive_select_all_ids가 포함되어 있습니다.

파괴적인 배치를 실행하기 전에 에이전트가 계획된 작업을 요약하도록 하세요.

• 대상 Drive 공간.
• 파일 및 폴더 수.
• 이동하는 경우 대상 폴더.
• 작업을 복구할 수 있는지 여부.
• 필요한 범위 및 MCP 안전 게이트.

REST 엔드포인트

POST /api/v1/drive/spaces/{space}/bulk:trash
POST /api/v1/drive/spaces/{space}/bulk:restore
POST /api/v1/drive/spaces/{space}/bulk:move
POST /api/v1/drive/spaces/{space}/bulk:purge

모든 대량 요청에 Idempotency-Key 헤더를 사용하세요. 재시도가 발생하면 TrekMail은 배치를 반복하는 대신 원래 결과를 반환할 수 있습니다.

MCP 도구

drive_bulk_trash
drive_bulk_restore
drive_bulk_move
drive_bulk_purge

drive_bulk_purge는 영구적인 작업이며 일치하는 영구 삭제 범위가 필요합니다. 로컬에서 호스팅하는 MCP 서버에서는 이 도구를 제공하기 전에 관리자가 TREKMAIL_ALLOW_DESTRUCTIVE=true를 요구할 수도 있습니다.

안전한 정리 패턴

대부분의 자동화에는 2단계 정리를 사용하세요.

1. 오래된 파일을 Archive 폴더나 휴지통으로 이동합니다.
2. 영구 삭제하기 전에 사람의 검토 또는 별도로 예약된 유지 관리 작업을 기다립니다.

이렇게 하면 복구 옵션을 유지하면서 일상적으로 사용하는 에이전트의 유용성을 지킬 수 있습니다.

권한 설계

영구 삭제 권한은 별도의 토큰에 보관하세요. 워크플로가 파일을 보관하기만 한다면 영구 삭제 권한은 전혀 필요하지 않습니다.