Shares API

파일이나 폴더를 공유하고, 누가 접근할 수 있는지와 각 대상이 무엇을 할 수 있는지를 정합니다. base 경로가 두 개입니다. shared는 나에게 공유된 항목의 목록이고, shares는 내가 제공하는 공유를 관리합니다.

Base URL과 scope

/api/external/v1/shared
/api/external/v1/shares

목록 조회, 공유 조회, 사용자 검색, 공유 유형 조회는 api:read가 필요합니다. 공유 등록·변경·해제와 대상 설정은 api:write가 추가로 필요합니다.

공유 유형

공유는 유형을 하나 가지며, 유형이 누가 리소스에 접근할 수 있는지를 결정합니다.

유형	접근할 수 있는 대상
`SPECIFIC_USERS`	대상으로 지정한 사용자만
`ORG_LINK`	조직 내부의 모든 사용자
`PUBLIC_LINK`	링크를 가진 모든 사람

같은 hierarchy에 속한 리소스는 모두 같은 공유 유형을 써야 합니다. 공유를 만들기 전에 공유 유형 조회 endpoint를 호출해 해당 리소스가 허용하는 유형을 확인합니다.

권한 플래그

권한은 다섯 개의 boolean이며, 공유 전체와 각 대상 모두에 같은 방식으로 쓰입니다.

플래그	권한
`cv`	보기
`ce`	수정
`cd`	다운로드
`cu`	업로드
`cs`	재공유

cv는 나머지의 선행 조건입니다. ce, cd, cu, cs 중 하나라도 true이면 cv가 true여야 합니다. 다른 권한이 켜진 상태에서 cv를 끄면 PERMISSION_003으로 실패합니다. ORG_LINK와 PUBLIC_LINK는 cv가 true여야 하고 나머지 네 개를 명시적으로 보내야 합니다.

응답에서는 같은 권한이 긴 이름으로 나타납니다. canView, canEdit, canDownload, canUpload, canDelete, canShare입니다.

나에게 공유된 항목 목록

GET /api/external/v1/shared

파라미터	Type	필수	설명
`ps`	integer	Yes	페이지 크기, 최소 `1`
`rt`	enum	No	`FILE` 또는 `FOLDER`
`ft`	enum	No	파일 유형 - `document`, `spreadsheet`, `presentation`, `pdf`, `image`, `note`
`oi`	string	No	소유자 id, 최대 254자
`sd`	date	No	수정일 범위 시작. `ed`를 함께 보내지 않으면 무시
`ed`	date	No	수정일 범위 종료. `sd`를 함께 보내지 않으면 무시
`sb`	enum	No	정렬 기준 - `name`, `size`, `update`, `open`, `share`. `so`를 함께 보내지 않으면 무시
`so`	enum	No	정렬 순서. `sb`를 함께 보내지 않으면 무시
`ci`	long	No	이전 페이지의 cursor id
`cv`	object	No	이전 페이지의 cursor value
`ct`	enum	No	이전 페이지의 cursor type

List shared
curl -X GET "https://drive.example.com/api/external/v1/shared?ps=10" \
  -H "Authorization: Bearer replace-with-your-api-key"

cv는 두 가지 의미로 쓰임

이 endpoint의 query 파라미터에서 cv는 페이지네이션 cursor value입니다. 공유 요청 body에서 cv는 보기 권한입니다. 두 용법이 한 요청에 같이 나오는 경우는 없습니다.

각 항목은 리소스, 소유자와 tenant, 공유 시각, 나의 실질 권한, 공유를 등록하거나 마지막으로 변경한 사람을 알려줍니다. isStarred와 starredSeq도 함께 담겨 있어 공유받은 항목도 다른 리소스처럼 중요 표시를 할 수 있습니다. 이 endpoint는 cursor 페이지네이션을 씁니다. Common conventions를 참고합니다.

리소스가 허용하는 공유 유형 조회

GET /api/external/v1/shares/{resourceSeq}/share-types

파라미터	Type	필수	설명
`resourceSeq`	long	Yes	path 파라미터 - 확인할 리소스
`ss`	integer	No	소유자 seq. 본인 리소스면 `null`

Share types response
{
  "result": true,
  "code": 200,
  "message": "OK",
  "data": {
    "editable": true,
    "allowSpecificUsers": true,
    "allowOrgLink": true,
    "allowPublic": true,
    "shareTypes": [
      {
        "code": "SPECIFIC_USERS",
        "name": "Specific users",
        "allowedPermissions": ["DOWNLOAD", "EDIT", "SHARE", "VIEW"]
      },
      {
        "code": "ORG_LINK",
        "name": "Anyone in the organization",
        "allowedPermissions": ["DOWNLOAD", "EDIT", "VIEW"]
      },
      {
        "code": "PUBLIC_LINK",
        "name": "Anyone with the link",
        "allowedPermissions": ["DOWNLOAD", "EDIT", "VIEW"]
      }
    ]
  }
}

allowedPermissions는 관리자가 그 유형에 허용한 범위이며, 공유는 이보다 넓은 권한을 줄 수 없습니다. ORG_LINK와 PUBLIC_LINK에는 재공유가 없습니다.

공유 생성

api:write 필요

리소스 소유자만 공유를 만들 수 있습니다. 먼저 허용되는 공유 유형을 조회합니다.

POST /api/external/v1/shares

파라미터	Type	필수	설명
`rs`	long	Yes	공유할 파일 또는 폴더
`st`	enum	Yes	공유 유형 - `SPECIFIC_USERS`, `ORG_LINK`, `PUBLIC_LINK`
`cv`	boolean	No	보기 권한. `ORG_LINK`, `PUBLIC_LINK`는 `true` 필수
`ce`	boolean	No	수정 권한. `ORG_LINK`, `PUBLIC_LINK`는 필수
`cd`	boolean	No	다운로드 권한. `ORG_LINK`, `PUBLIC_LINK`는 필수
`cu`	boolean	No	업로드 권한. `ORG_LINK`, `PUBLIC_LINK`는 필수
`cs`	boolean	No	재공유 권한. `ORG_LINK`, `PUBLIC_LINK`는 필수
`ts`	array	No	공유 대상. `st`가 `SPECIFIC_USERS`일 때 사용

ts의 각 항목은 대상 한 명과 그 권한을 지정합니다.

Field	Type	필수	설명
`us`	integer	Yes	대상 사용자 seq
`cv`	boolean	Yes	보기 권한. `true` 필수
`ce`	boolean	Yes	수정 권한
`cd`	boolean	Yes	다운로드 권한
`cu`	boolean	Yes	업로드 권한
`cs`	boolean	Yes	재공유 권한
`se`	boolean	No	이 대상에게 알림 메일 발송 여부

Create share
curl -X POST "https://drive.example.com/api/external/v1/shares" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"rs": 5125, "st": "SPECIFIC_USERS", "cv": true, "ce": true, "cd": false, "cu": true, "cs": false, "ts": [{"us": 21, "cv": true, "ce": true, "cd": false, "cu": false, "cs": false, "se": true}]}'

응답은 새 shareSeq와 적용된 권한을 반환합니다. 이후 이 공유에 대한 모든 동작이 shareSeq를 쓰므로 보관합니다.

공유 조회

GET /api/external/v1/shares/{shareSeq}

파라미터	Type	필수	설명
`shareSeq`	long	Yes	path 파라미터 - 조회할 공유
`ss`	integer	No	소유자 seq. 본인이 소유자가 아니면 필수

공유 유형, 공유 단위 권한, password와 isPasswordEnabled, expireDate, 그리고 대상별 권한과 tenant가 담긴 targets 배열을 반환합니다.

modifiable은 공유 유형을 아직 바꿀 수 있는지를 알려줍니다. false면 유형이 고정된 상태이며, 보통 같은 hierarchy의 다른 리소스가 이미 유형을 정했기 때문입니다.

공유 변경

api:write 필요

리소스 소유자만 공유를 변경할 수 있습니다. 대상은 유형이 SPECIFIC_USERS일 때만 지정할 수 있습니다.

PATCH /api/external/v1/shares/{shareSeq}

파라미터	Type	필수	설명
`shareSeq`	long	Yes	path 파라미터 - 변경할 공유
`st`	enum	Yes	공유 유형
`cv`	boolean	No	보기 권한. `ORG_LINK`, `PUBLIC_LINK`는 `true` 필수
`ce`	boolean	No	수정 권한. `ORG_LINK`, `PUBLIC_LINK`는 필수
`cd`	boolean	No	다운로드 권한. `ORG_LINK`, `PUBLIC_LINK`는 필수
`cu`	boolean	No	업로드 권한. `ORG_LINK`, `PUBLIC_LINK`는 필수
`cs`	boolean	No	재공유 권한. `ORG_LINK`, `PUBLIC_LINK`는 필수
`ts`	array	No	공유 대상. 생성과 같은 형태

Change share
curl -X PATCH "https://drive.example.com/api/external/v1/shares/36" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"st": "SPECIFIC_USERS", "cv": true, "ce": true, "cd": true, "cu": true, "cs": false, "ts": [{"us": 25, "cv": true, "ce": true, "cd": true, "cu": false, "cs": false, "se": true}]}'

공유 대상 설정

api:write 필요

공유 유형과 공유 단위 권한은 그대로 두고 대상 목록만 교체합니다. 변경 endpoint와 달리, 재공유 권한을 받은 사용자도 호출할 수 있습니다.

PUT /api/external/v1/shares/{shareSeq}/targets

파라미터	Type	필수	설명
`shareSeq`	long	Yes	path 파라미터 - 대상을 설정할 공유
`ts`	array	No	공유 대상. 생성과 같은 형태
`ss`	integer	No	공유 사용자 seq. 본인 리소스면 `null`

이 목록은 추가가 아니라 교체입니다. 빠뜨린 대상은 접근 권한을 잃습니다.

공유 해제

api:write 필요

DELETE /api/external/v1/shares/{shareSeq}

파라미터	Type	필수	설명
`shareSeq`	long	Yes	path 파라미터 - 해제할 공유

모든 대상이 접근 권한을 잃고, 이 공유의 링크도 더 이상 열리지 않습니다. 리소스 자체는 영향을 받지 않습니다.

공유 대상 찾기

GET /api/external/v1/shares/{shareSeq}/users

공유의 현재 대상을 id·이름·상태·tenant와 함께 반환합니다. 본인이 소유자가 아니면 ss를 보냅니다.

추가할 수 있는 사용자를 찾을 때는 검색을 씁니다. 공유가 이미 있으면 첫 번째 형태를, 아직 만들고 있는 중이면 두 번째 형태를 씁니다.

GET /api/external/v1/shares/{shareSeq}/users/search
GET /api/external/v1/shares/users/search

파라미터	Type	필수	설명
`sk`	string	Yes	검색 키워드 - 이메일 주소 또는 계정 이름
`ss`	integer	No	소유자 seq. 본인이 소유자가 아니면 필수

결과는 data.items에 담깁니다.

공유 링크 확인

GET /api/external/v1/shares/link/{token}

파라미터	Type	필수	설명
`token`	string	Yes	path 파라미터 - 공유 URL의 토큰

링크가 가리키는 리소스, 소유자, isPublicLink, 그리고 브라우저를 보낼 redirectUrl을 반환합니다. 링크 자체는 Common conventions의 공유 링크 endpoint에서 얻습니다.

전체 공개 링크도 여기서는 키가 필요함

이 동작의 내부 경로는 익명 접근을 허용하지만, 이 외부 endpoint는 허용하지 않습니다. 항상 API Key가 필요하고, 키가 대표하는 계정을 기준으로 보기 권한을 검사합니다. PUBLIC_LINK 공유도 마찬가지입니다. 브라우저에서는 익명으로 열리는 링크라도, 키의 계정이 리소스를 볼 수 없으면 여기서는 PERMISSION_002를 반환합니다. 알 수 없거나 폐기된 토큰은 SHARE_007을 반환합니다.

에러

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

Base URL과 scope​

공유 유형​

권한 플래그​

나에게 공유된 항목 목록​

리소스가 허용하는 공유 유형 조회​

공유 생성​

공유 조회​

공유 변경​

공유 대상 설정​

공유 해제​

공유 대상 찾기​

공유 링크 확인​

에러​

Base URL과 scope

공유 유형

권한 플래그

나에게 공유된 항목 목록

리소스가 허용하는 공유 유형 조회

공유 생성

공유 조회

공유 변경

공유 대상 설정

공유 해제

공유 대상 찾기

공유 링크 확인

에러