본문으로 건너뛰기

Folders API

폴더에 대한 동작입니다. 폴더와 파일이 공유하는 리소스 모델, 목록 endpoint, 폴더 트리는 Common conventions에 있습니다. 이 페이지는 폴더에만 해당하는 내용을 다룹니다.

Base URL과 scope​

/api/external/v1/folders

읽기 동작은 api:read가 필요합니다. 생성·삭제·이름 변경·이동은 api:write가 추가로 필요합니다.

폴더 생성​

api:write 필요
POST /api/external/v1/folders
파라미터Type필수설명
fnstringYes폴더 이름
pfslongNo부모 폴더 seq. ss를 보낼 때 필수
ssintegerNo공유 사용자 seq
Create folder
curl -X POST "https://drive.example.com/api/external/v1/folders" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"pfs": 5, "fn": "Contracts"}'
Create folder response
{
  "result": true,
  "code": 201,
  "message": "Created",
  "data": {
    "resourceSeq": 2056,
    "resourceName": "Contracts"
  }
}

pfs를 생략하면 드라이브 최상위에 만들어집니다. 만들기 전에 이름을 확인하려면 Common conventions의 이름 중복 확인 endpoint를 사용합니다.

폴더 이름 변경​

api:write 필요
PATCH /api/external/v1/folders/{resourceSeq}/rename
파라미터Type필수설명
resourceSeqlongYespath 파라미터 - 이름을 바꿀 폴더
rnstringYes새 이름
ssintegerNo공유 사용자 seq. 공유 폴더면 필수
pfslongNo부모 폴더 seq. 공유 폴더면 필수
Rename folder
curl -X PATCH "https://drive.example.com/api/external/v1/folders/{resourceSeq}/rename" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"ss": 21, "pfs": 5, "rn": "Signed contracts"}'

파일 이름 변경 endpoint와 달리 이름 충돌 정책 파라미터가 없습니다.

폴더 이동​

api:write 필요
POST /api/external/v1/folders/{resourceSeq}/move
파라미터Type필수설명
resourceSeqlongYespath 파라미터 - 이동할 폴더
tsintegerNo대상 사용자 seq. 공유 폴더면 필수
pfslongNo이동할 폴더 seq. 공유 폴더면 필수
ssintegerNo공유 사용자 seq
Move folder
curl -X POST "https://drive.example.com/api/external/v1/folders/{resourceSeq}/move" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"ts": 1, "ss": 21, "pfs": 5}'

폴더를 옮기면 그 안의 내용도 함께 이동합니다.

폴더 삭제​

api:write 필요
PATCH /api/external/v1/folders/{resourceSeq}/delete
파라미터Type필수설명
resourceSeqlongYespath 파라미터 - 삭제할 폴더

폴더와 그 안의 내용은 완전히 제거되지 않고 휴지통으로 이동합니다. 삭제에 실패하면 RESOURCE_001을 반환합니다.

폴더 다운로드​

폴더는 두 단계를 거쳐 ZIP 아카이브로 내려받습니다. 먼저 토큰을 발급합니다.

GET /api/external/v1/folders/{resourceSeq}/download-token
파라미터Type필수설명
resourceSeqlongYespath 파라미터 - 내려받을 폴더
ssintegerNo공유 사용자 seq
Folder token response
{
  "result": true,
  "code": 200,
  "message": "OK",
  "data": {
    "linkUrl": "/folders/download?dt={token}"
  }
}

그다음 반환된 경로로 브라우저를 보냅니다.

GET /api/external/v1/folders/download?dt={dt}
HTTP 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="archive.zip"

고정 폴더​

사용자는 빠른 접근을 위해 폴더를 고정할 수 있습니다. 고정 폴더는 사용자별로 관리되며 최대 3개입니다.

고정은 읽기 scope로 동작함

고정 폴더 등록과 삭제는 쓰기 동작으로 취급되지 않습니다. api:read만 가진 키로도 고정 목록을 바꿀 수 있습니다.

고정 폴더 목록​

GET /api/external/v1/pinned-folders

파라미터가 없습니다. 결과는 고정한 순서로 정렬됩니다. 원본 폴더가 삭제되면 목록에서 자동으로 빠집니다.

FieldType의미
pinnedFolderSeqlong고정 항목의 식별자. 해제할 때 사용
resourceSeqlong고정된 폴더
sharedByUserSeqinteger폴더 소유자의 사용자 seq. 본인 폴더면 본인 seq
resourceNamestring폴더 이름
resourceTypeenum항상 FOLDER

폴더 고정​

POST /api/external/v1/pinned-folders
파라미터Type필수설명
rslongYes폴더 리소스 seq. 파일 seq를 보내면 RESOURCE_005로 실패
ssintegerNo폴더 소유자의 사용자 seq. 공유받은 폴더를 고정할 때 필수
Pin folder
curl -X POST "https://drive.example.com/api/external/v1/pinned-folders" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"rs": 17466, "ss": 43}'

폴더의 조회 권한을 검사합니다. 공유받지 않은 폴더는 PERMISSION_001, 접근할 수 없는 폴더는 PERMISSION_002로 실패합니다. 같은 폴더를 다시 고정하면 PINNED_FOLDER_002, 3개를 초과하면 PINNED_FOLDER_003으로 실패합니다.

고정 해제​

DELETE /api/external/v1/pinned-folders/{pinnedFolderSeq}
파라미터Type필수설명
pinnedFolderSeqlongYespath 파라미터 - 해제할 고정 항목

본인 것이 아니거나 이미 사라진 고정 항목을 해제하면 PINNED_FOLDER_001을 반환합니다. 폴더 자체는 영향을 받지 않습니다.

에러​

이 endpoint들이 반환하는 코드 전체 목록은 Errors를 참고합니다.