Shares API

파일이나 폴더를 공유하고, 접근할 수 있는 대상과 대상별 권한을 설정합니다. 이 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`	링크를 가진 모든 사람

상위·하위 관계에 있는 리소스는 모두 같은 공유 유형을 사용해야 합니다. 공유를 만들기 전에 공유 유형 조회 endpoint를 호출해 해당 리소스에 허용된 공유 유형을 확인하세요.

권한 값

권한은 다섯 개의 boolean 값으로 지정하며, 두 가지 단위로 설정합니다. 하나는 공유 전체에 적용되는 권한(요청 body의 cv~cs)이고, 다른 하나는 ts에 지정하는 대상별 권한입니다.

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

다른 권한을 부여하려면 cv가 true여야 합니다. cv가 false이면 다른 권한 값과 관계없이 PERMISSION_003으로 실패합니다.
ORG_LINK와 PUBLIC_LINK는 공유 전체에 적용되는 권한을 사용하며 다섯 값을 모두 보내야 합니다. 하나라도 생략하면 생성은 SHARE_009로, 변경은 SHARE_005(500)로 실패합니다. 해당 공유 유형에서 허용하지 않는 권한을 true로 보내면 PERMISSION_005(403)로 실패합니다.
SPECIFIC_USERS는 공유 전체에 적용되는 권한을 사용하거나 검증하지 않으며, 대상별 권한만 적용합니다.
대상별 권한에는 공유 유형의 제한이 적용되지 않습니다. 단, 파일에는 업로드 권한을 부여할 수 없습니다.

응답에서는 같은 권한을 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-USER-API-KEY"

cv의 두 가지 의미

이 endpoint의 query 파라미터에서 cv는 페이지네이션의 cursor value입니다. 공유 요청 body의 cv는 보기 권한입니다. 한 요청에서 두 의미가 함께 사용되지는 않습니다.

각 항목에는 리소스 정보, 소유자와 tenant, 공유 시각, 호출한 계정에 실제로 적용되는 권한, 공유를 생성하거나 마지막으로 변경한 사용자가 포함됩니다. isStarred와 starredSeq도 포함되므로 공유받은 항목도 다른 리소스와 마찬가지로 중요 표시를 할 수 있습니다.

sb와 so를 지정하지 않으면 공유된 시각(share) 내림차순으로 정렬합니다. 정렬 조건과 관계없이 폴더가 항상 파일보다 먼저 표시됩니다. hasNext가 true이면 응답에 nextCursor(마지막 항목의 resourceSeq), nextCursorValue(정렬 기준 값), nextCursorType(리소스 유형)이 포함됩니다. 다음 페이지를 요청할 때 이 값을 각각 ci, cv, ct로 보냅니다. 자세한 내용은 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": "특정 사용자만",
        "allowedPermissions": ["DOWNLOAD", "EDIT", "SHARE", "VIEW"]
      },
      {
        "code": "ORG_LINK",
        "name": "조직 내부 공개",
        "allowedPermissions": ["DOWNLOAD", "EDIT", "VIEW"]
      },
      {
        "code": "PUBLIC_LINK",
        "name": "전체 공개",
        "allowedPermissions": ["DOWNLOAD", "EDIT", "VIEW"]
      }
    ]
  }
}

name은 언어와 관계없이 고정된 문자열입니다.

allowedPermissions는 관리자 설정과 관계없이 공유 유형과 리소스 종류에 따라 고정된 값입니다. 업로드 권한은 폴더에만 있고 PUBLIC_LINK에는 없으며, 재공유 권한은 SPECIFIC_USERS에만 있습니다. 위 예시는 파일을 조회한 결과이므로 UPLOAD가 없습니다. 이 제한은 링크 공유에서 공유 전체에 적용되는 권한에만 적용되며 대상별 권한에는 적용되지 않습니다. tenant 설정에 따라 달라지는 값은 allowSpecificUsers, allowOrgLink, allowPublic입니다.

공유 생성

api:write 필요

리소스 소유자만 공유를 만들 수 있으며, 소유자가 아니면 RESOURCE_005로 실패합니다. 공유를 만들기 전에 허용된 공유 유형을 조회하세요.

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	공유 대상. tenant 설정에서 `SPECIFIC_USERS`를 허용하면 공유 유형과 관계없이 지정 가능(허용하지 않으면 `SHARE_011`)

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-USER-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면 공유 유형을 변경할 수 없으며, 대부분 상위·하위 관계에 있는 다른 리소스에 이미 공유 유형이 지정되어 있기 때문입니다.

공유 변경

api:write 필요

공유를 만든 사용자만 공유를 변경할 수 있으며, 다른 사용자가 요청하면 SHARE_004로 실패합니다. 대상은 공유 유형과 관계없이 지정할 수 있지만, tenant 설정에서 SPECIFIC_USERS를 허용해야 합니다(허용하지 않으면 SHARE_011).

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-USER-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}]}'

ts로 기존 대상 전체를 교체함

ts를 생략하거나 빈 목록을 보내면 기존 대상이 모두 삭제되고, 삭제된 대상에게 공유 해제 알림이 발송됩니다. 공유 유형이나 권한만 변경할 때도 기존 대상을 ts에 다시 보내야 합니다.

공유 대상 설정

api:write 필요

공유 유형과 공유 전체에 적용되는 권한은 유지하고 대상 목록만 교체합니다. 공유 변경 endpoint와 달리 재공유 권한을 받은 사용자도 호출할 수 있습니다.

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

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

보낸 목록이 기존 대상에 추가되지 않고 기존 목록 전체를 대체합니다. 목록에 포함하지 않은 대상은 접근 권한을 잃습니다. ts를 생략하거나 빈 목록을 보내면 기존 대상이 모두 삭제되고, 삭제된 대상에게 공유 해제 알림이 발송됩니다.

tenant의 공유 기능이 비활성화되어 있으면 SHARE_012로, 기존 공유 유형이 현재 tenant 설정에서 허용되지 않으면 SHARE_013으로 실패합니다.

공유 해제

api:write 필요

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

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

공유를 만든 사용자만 공유를 해제할 수 있으며, 다른 사용자가 요청하면 SHARE_004로 실패합니다.

공유를 해제하면 모든 대상의 접근 권한이 사라지고 공유 링크도 더 이상 열리지 않습니다. 리소스는 삭제되지 않습니다.

공유 대상 조회

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

공유의 현재 대상 목록을 id·이름·상태·tenant 정보와 함께 반환합니다. 호출한 계정이 소유자가 아니면 ss를 보냅니다.

공유 대상으로 추가할 사용자를 찾으려면 사용자 검색 endpoint를 사용합니다. 이미 생성된 공유에는 첫 번째 endpoint를, 아직 생성하지 않은 공유에는 두 번째 endpoint를 사용합니다.

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에 포함됩니다. 호출하려면 리소스에 대한 공유(SHARE) 권한이 있어야 합니다. 공유 기능이 비활성화되어 있으면 SHARE_012로, SPECIFIC_USERS를 허용하지 않으면 SHARE_011로 실패합니다. 결과에는 소유자 본인을 제외한 활성(ACTIVE) 일반 사용자(USER)만 포함됩니다. 외부 공유를 허용하지 않으면 같은 tenant의 사용자만 반환합니다.

공유 링크 확인

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

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

링크가 가리키는 리소스, 소유자, isPublicLink, 브라우저에서 이동할 redirectUrl을 반환합니다. 공유 링크는 Common conventions의 공유 링크 조회 endpoint로 가져옵니다.

공개 링크도 API Key가 필요함

Drive 웹 앱에서는 이 기능을 익명으로 사용할 수 있지만, 이 endpoint는 익명 접근을 허용하지 않습니다. 항상 API Key가 필요하며, API Key를 발급받은 계정을 기준으로 보기 권한을 검사합니다. PUBLIC_LINK 공유도 마찬가지입니다. 브라우저에서 익명으로 열 수 있는 링크라도 API Key의 계정이 리소스를 볼 수 없으면 PERMISSION_002를 반환합니다. 존재하지 않거나 폐기된 토큰은 SHARE_007을 반환합니다.

오류

요청이 실패하면 공통 실패 구조로 응답합니다.

Share failure
{
  "result": false,
  "code": 403,
  "errorCode": "SHARE_011",
  "message": "..."
}

Code	Status	의미
`REQUEST_001`	400	요청 값 검증 실패
`RESOURCE_005`	404	리소스가 없거나, 본인 소유가 아닌 리소스의 공유를 생성함
`PERMISSION_002`	403	리소스에 접근 권한이 없음
`PERMISSION_003`	400	`cv`가 `false`
`PERMISSION_004`	-	권한 검사 실패
`PERMISSION_005`	403	해당 공유 유형에서 허용하지 않는 권한을 `true`로 보냄
`SHARE_004`	404	공유가 없거나, 호출한 계정이 공유를 만든 사용자가 아님
`SHARE_005`	500	공유 변경 실패
`SHARE_007`	404	토큰에 해당하는 공유 링크가 없음
`SHARE_008`	400	상위 또는 하위 리소스에 다른 유형의 공유가 있음
`SHARE_009`	500	공유 등록 실패
`SHARE_011`	403	tenant 설정에서 `SPECIFIC_USERS`를 허용하지 않음
`SHARE_012`	403	tenant의 공유 기능이 비활성화됨
`SHARE_013`	403	tenant 설정에서 해당 공유 유형이 허용되지 않음
`SHARE_014`	403	외부 공유가 허용되지 않음
`SHARE_TARGET_001`	500	공유 대상 등록 실패
`RESPONSE_001`	500	예기치 않은 서버 오류

대상이 소유자 본인이거나 존재하지 않는 사용자면 생성은 SHARE_009로, 변경은 SHARE_005로, 대상 설정은 SHARE_TARGET_001로 실패합니다. 다른 tenant의 사용자를 대상으로 지정하려면 외부 공유가 허용되어야 합니다 (SHARE_014). 전체 오류 코드는 Errors를 참고하세요.

Base URL과 scope​

공유 유형​

권한 값​

공유받은 항목 목록​

리소스에 허용된 공유 유형 조회​

공유 생성​

공유 조회​

공유 변경​

공유 대상 설정​

공유 해제​

공유 대상 조회​

공유 링크 확인​

오류​

Base URL과 scope

공유 유형

권한 값

공유받은 항목 목록

리소스에 허용된 공유 유형 조회

공유 생성

공유 조회

공유 변경

공유 대상 설정

공유 해제

공유 대상 조회

공유 링크 확인

오류