모든 Google Drive 파일, 폴더, 공유 드라이브에는 연결된 permissions
리소스가 있습니다. 각 리소스는 특정 type
(user
, group
, domain
, anyone
) 및 role
(owner
, organizer
, fileOrganizer
, writer
, commenter
, reader
)의 권한을 식별합니다. 예를 들어 파일에 특정 사용자 (type=user
)에게 읽기 전용 액세스 권한 (role=reader
)을 부여하는 권한이 있는 반면 다른 권한은 특정 그룹 (type=group
)의 구성원에게 파일에 주석을 추가할 수 있는 권한 (role=commenter
)을 부여할 수 있습니다.
역할 및 각 역할에서 허용되는 작업의 전체 목록은 역할 및 권한을 참고하세요.
Drive 리소스 공유 시나리오
공유 시나리오에는 다음과 같은 5가지 유형이 있습니다.
내 드라이브에서 파일을 공유하려면 사용자에게
role=writer
또는role=owner
권한이 있어야 합니다.파일의
writersCanShare
불리언 값이false
로 설정된 경우 사용자에게role=owner
가 있어야 합니다.role=writer
사용자에게 만료일 및 시간에 따라 제한되는 임시 액세스 권한이 있는 경우 파일을 공유할 수 없습니다. 자세한 내용은 만료일을 설정하여 파일 액세스 제한하기를 참고하세요.
내 드라이브에서 폴더를 공유하려면 사용자에게
role=writer
또는role=owner
권한이 있어야 합니다.파일의
writersCanShare
불리언 값이false
로 설정된 경우 사용자는 더 관대한role=owner
를 보유해야 합니다.role=writer
가 있는 내 드라이브 폴더에는 임시 액세스 (만료일 및 만료 시간에 따라 관리됨)가 허용되지 않습니다. 자세한 내용은 만료일을 설정하여 파일 액세스 제한하기를 참고하세요.
공유 드라이브에서 파일을 공유하려면 사용자에게
role=writer
,role=fileOrganizer
또는role=organizer
권한이 있어야 합니다.writersCanShare
설정은 공유 드라이브의 항목에는 적용되지 않습니다. 항상true
로 설정된 것처럼 처리됩니다.
공유 드라이브에서 폴더를 공유하려면 사용자에게
role=organizer
가 있어야 합니다.- 공유 드라이브의
sharingFoldersRequiresOrganizerPermission
제한이false
로 설정된 경우role=fileOrganizer
권한이 있는 사용자는 해당 공유 드라이브의 폴더를 공유할 수 있습니다.
- 공유 드라이브의
공유 드라이브 멤버십을 관리하려면 사용자에게
role=organizer
가 있어야 합니다. 사용자와 그룹만 공유 드라이브의 구성원이 될 수 있습니다.
파일 액세스 권한을 제한하기 위한 만료일 설정하기
민감한 프로젝트에서 다른 사용자와 협업하는 경우 일정 기간이 지나면 Drive의 특정 파일에 대한 액세스 권한을 제한해야 할 수 있습니다. 내 드라이브 파일에 대해 파일 액세스 권한의 만료일을 설정하여 액세스 권한을 제한 또는 삭제할 수 있습니다.
만료일을 설정하려면 다음 단계를 따르세요.
permissions
리소스에서create()
메서드를 사용하고 다른 필수 필드와 함께expirationTime
필드를 설정합니다. 자세한 내용은 권한 만들기를 참고하세요.permissions
리소스에서update()
메서드를 사용하고 다른 필수 필드와 함께expirationTime
필드를 설정합니다. 자세한 내용은 권한 변경을 참고하세요.
expirationTime
필드는 RFC 3339 날짜-시간을 사용하여 권한이 만료되는 시점을 나타냅니다. 만료 시간에는 다음과 같은 제한사항이 있습니다.
- 사용자 및 그룹 권한에만 설정할 수 있습니다.
- 시간은 미래여야 합니다.
- 1년 이상 미래의 시간은 사용할 수 없습니다.
만료일에 관한 자세한 내용은 다음 도움말을 참고하세요.
권한 전파
폴더의 권한 목록은 아래쪽으로 전파되며 모든 하위 파일과 폴더는 상위 요소의 권한을 상속받습니다. 권한 또는 계층 구조가 변경될 때마다 모든 중첩 폴더를 통해 전파가 재귀적으로 발생합니다. 예를 들어 폴더에 파일이 있고 해당 폴더가 다른 폴더 내에서 이동하면 새 폴더의 권한이 파일로 전파됩니다. 새 폴더가 파일 사용자에게 '작성자'와 같은 새 역할을 부여하면 이전 역할이 재정의됩니다.
반대로 파일이 폴더에서 role=writer
를 상속받고 '읽기 권한 사용자' 역할을 제공하는 다른 폴더로 이동하면 이제 파일은 role=reader
를 상속받습니다.
상속된 권한은 공유 드라이브의 파일 또는 폴더에서 삭제할 수 없습니다. 대신 이러한 권한은 상속된 직접 또는 간접 상위 요소에서 조정해야 합니다. '내 드라이브' 또는 '공유 문서함'의 항목에서 상속된 권한을 삭제할 수 있습니다.
반대로 상속된 권한은 내 드라이브의 파일 또는 폴더에서 재정의할 수 있습니다. 따라서 파일이 내 드라이브 폴더에서 role=writer
를 상속하는 경우 파일에 role=reader
를 설정하여 권한 수준을 낮출 수 있습니다.
기능
permissions
리소스는 궁극적으로 현재 사용자가 파일이나 폴더에 작업을 실행할 수 있는지 여부를 결정하지 않습니다. 대신 files
리소스에는 파일 또는 폴더에서 작업을 실행할 수 있는지 여부를 나타내는 불리언 capabilities
필드 모음이 포함되어 있습니다. Google Drive API는 파일 또는 폴더와 연결된 현재 사용자의 권한 리소스를 기반으로 이러한 필드를 설정합니다.
예를 들어 알렉스가 앱에 로그인하여 파일을 공유하려고 하면 알렉스의 역할에 따라 파일에 대한 권한이 확인됩니다. 역할에서 파일 공유가 허용되는 경우 파일과 관련된 capabilities
(예: canShare
)가 역할에 따라 채워집니다. 알렉스가 파일을 공유하려고 하면 앱은 capabilities
를 확인하여 canShare
가 true
로 설정되어 있는지 확인합니다.
capabilities
파일을 검색하는 예는 사용자 권한 확인을 참고하세요.
권한 만들기
권한을 만들 때 다음 두 필드가 필요합니다.
type
:type
는 권한 범위 (user
,group
,domain
또는anyone
)를 식별합니다.type=user
가 있는 권한은 특정 사용자에게 적용되는 반면type=domain
가 있는 권한은 특정 도메인의 모든 사용자에게 적용됩니다.role
:role
필드는type
가 실행할 수 있는 작업을 식별합니다. 예를 들어type=user
및role=reader
가 있는 권한은 특정 사용자에게 파일 또는 폴더에 대한 읽기 전용 액세스 권한을 부여합니다. 또는type=domain
및role=commenter
권한을 사용하면 도메인의 모든 사용자가 파일에 댓글을 추가할 수 있습니다. 역할 및 각 역할에서 허용되는 작업의 전체 목록은 역할 및 권한을 참고하세요.
type=user
또는 type=group
인 위치에서 권한을 만들 때는 특정 사용자 또는 그룹을 권한에 연결하는 emailAddress
도 제공해야 합니다.
type=domain
인 위치에서 권한을 만들 때는 특정 도메인을 권한에 연결하는 domain
도 제공해야 합니다.
권한을 만들려면 다음 단계를 따르세요.
- 연결된 파일 또는 폴더의
fileId
경로 매개변수와 함께create()
메서드를 사용합니다. - 요청 본문에서
type
및role
를 지정합니다. type=user
또는type=group
인 경우emailAddress
을 제공합니다.type=domain
인 경우domain
를 제공합니다.
예 보기
다음 코드 샘플은 권한을 만드는 방법을 보여줍니다. 응답은 할당된 permissionId
를 포함하여 Permission
리소스의 인스턴스를 반환합니다.
요청
POST https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions
{ "requests": [ { "type": "user", "role": "commenter", "emailAddress": "alex@altostrat.com" } ] }
응답
{
"kind": "drive#permission",
"id": "PERMISSION_ID
",
"type": "user",
"role": "commenter"
}
공유 대상 그룹 사용
공유 대상 그룹은 사용자에게 항목을 공유하도록 권장할 수 있는 부서나 팀 등의 사용자 그룹입니다. 사용자가 조직 전체가 아닌 특정 대상 또는 제한된 대상과 항목을 공유하도록 할 수 있습니다. 공유 대상 그룹을 사용하면 데이터의 보안 및 개인 정보 보호를 개선하고 사용자가 더 쉽게 적절하게 공유할 수 있습니다. 자세한 내용은 타겟팅 잠재고객 정보를 참고하세요.
공유 대상 그룹을 사용하려면 다음 단계를 따르세요.
Google 관리 콘솔에서 메뉴 > 디렉터리 > 공유 대상 그룹으로 이동합니다.
이 작업을 수행하려면 최고 관리자 권한이 있는 계정으로 로그인해야 합니다.
공유 대상 그룹 목록에서 공유 대상 그룹의 이름을 클릭합니다. 공유 대상 그룹을 만들려면 공유 대상 그룹 만들기를 참고하세요.
공유 대상 그룹 URL(
https://admin.google.com/ac/targetaudiences/ID
)에서 고유 ID를 복사합니다.type=domain
로 권한을 만들고domain
필드를ID.audience.googledomains.com
로 설정합니다.
사용자가 타겟층과 상호작용하는 방식을 보려면 링크 공유 사용자 환경을 참고하세요.
파일, 폴더 또는 공유 드라이브의 모든 권한 검색
permissions
리소스의 list()
메서드를 사용하여 파일, 폴더 또는 공유 드라이브의 모든 권한을 검색합니다.
예 보기
다음 코드 샘플은 모든 권한을 가져오는 방법을 보여줍니다. 응답은 권한 목록을 반환합니다.
요청
GET https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions
응답
{
"kind": "drive#permissionList",
"permissions": [
{
"id": "PERMISSION_ID
",
"type": "user",
"kind": "drive#permission",
"role": "commenter"
}
]
}
사용자 권한 확인
앱이 파일을 열면 파일의 기능을 확인하고 현재 사용자의 권한을 반영하도록 UI를 렌더링해야 합니다. 예를 들어 사용자에게 파일에 대한 canComment
기능이 없는 경우 UI에서 댓글 작성 기능을 사용 중지해야 합니다.
capabilities
에 대한 자세한 내용은 기능 섹션을 참고하세요.
기능을 확인하려면 fileId
경로 매개변수와 fields
매개변수를 capabilities
필드로 설정하여 files
리소스에서 get()
메서드를 호출합니다. fields
매개변수를 사용하여 필드를 반환하는 방법에 관한 자세한 내용은 파일의 특정 필드 반환을 참고하세요.
예 보기
다음 코드 샘플은 사용자 권한을 확인하는 방법을 보여줍니다. 응답은 사용자가 파일에 대해 보유한 기능 목록을 반환합니다. 각 기능은 사용자가 취할 수 있는 세분화된 작업에 해당합니다. 일부 입력란은 공유 드라이브의 항목에 대해서만 채워집니다.
요청
GET https://www.googleapis.com/drive/v3/files/FILE_ID
?fields=capabilities
응답
{ "capabilities": { "canAcceptOwnership": false, "canAddChildren": false, "canAddMyDriveParent": false, "canChangeCopyRequiresWriterPermission": true, "canChangeSecurityUpdateEnabled": false, "canComment": true, "canCopy": true, "canDelete": true, "canDownload": true, "canEdit": true, "canListChildren": false, "canModifyContent": true, "canModifyContentRestriction": true, "canModifyLabels": true, "canMoveChildrenWithinDrive": false, "canMoveItemOutOfDrive": true, "canMoveItemWithinDrive": true, "canReadLabels": true, "canReadRevisions": true, "canRemoveChildren": false, "canRemoveMyDriveParent": true, "canRename": true, "canShare": true, "canTrash": true, "canUntrash": true } }
공유 드라이브 파일 및 폴더의 역할 소스 확인
파일 또는 폴더의 역할을 변경하려면 역할의 소스를 알아야 합니다. 공유 드라이브의 경우 역할 소스는 공유 드라이브 멤버십, 폴더의 역할 또는 파일의 역할에 따라 달라질 수 있습니다.
공유 드라이브 또는 해당 드라이브 내 항목의 역할 소스를 확인하려면 fileId
및 permissionId
경로 매개변수와 fields
매개변수를 permissionDetails
필드로 설정하여 permissions
리소스에서 get()
메서드를 호출합니다.
permissionId
를 찾으려면 fileId
경로 매개변수를 사용하여 permissions
리소스에서 list()
메서드를 사용합니다. list
요청에서 permissionDetails
필드를 가져오려면 fields
매개변수를 permissions/permissionDetails
로 설정합니다.
이 필드는 사용자, 그룹 또는 도메인의 모든 상속 및 직접 파일 권한을 열거합니다.
예 보기
다음 코드 샘플은 역할 소스를 확인하는 방법을 보여줍니다. 응답은 permissions
리소스의 permissionDetails
를 반환합니다. inheritedFrom
필드는 권한이 상속된 항목의 ID를 제공합니다.
요청
GET https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions/PERMISSION_ID
?fields=permissionDetails&supportsAllDrives=true
응답
{
"permissionDetails": [
{
"permissionType": "member",
"role": "commenter",
"inheritedFrom": "INHERITED_FROM_ID
",
"inherited": true
},
{
"permissionType": "file",
"role": "writer",
"inherited": false
}
]
}
권한 변경
파일 또는 폴더의 권한을 변경하려면 할당된 역할을 변경하면 됩니다.
permissionId
경로 매개변수를 변경 권한으로 설정하고fileId
경로 매개변수를 연결된 파일, 폴더 또는 공유 드라이브로 설정하여permissions
리소스에서update()
메서드를 호출합니다.permissionId
를 찾으려면fileId
경로 매개변수를 사용하여permissions
리소스에서list()
메서드를 사용합니다.요청에서 새
role
를 식별합니다.
사용자 또는 그룹이 이미 공유 드라이브의 구성원인 경우에도 공유 드라이브의 개별 파일 또는 폴더에 대한 권한을 부여할 수 있습니다. 예를 들어 앨릭스는 공유 드라이브 멤버십의 일부로 role=commenter
를 보유하고 있습니다. 하지만 앱은 Alex에게 공유 드라이브의 파일에 대한 role=writer
권한을 부여할 수 있습니다. 이 경우 새 역할이 멤버십을 통해 부여된 역할보다 관대한 권한이므로 새 권한이 파일 또는 폴더의 유효한 역할이 됩니다.
예 보기
다음 코드 샘플은 파일 또는 폴더의 권한을 댓글 작성자에서 작성자로 변경하는 방법을 보여줍니다. 응답은 permissions
리소스의 인스턴스를 반환합니다.
요청
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions/PERMISSION_ID
{ "requests": [ { "role": "writer" } ] }
응답
{
"kind": "drive#permission",
"id": "PERMISSION_ID
",
"type": "user",
"role": "writer"
}
대기 중인 액세스 제안서 나열 및 해결
액세스 제안서는 수신자에게 Drive 항목에 대한 액세스 권한을 부여하기 위해 요청자가 승인자에게 제출하는 제안서입니다.
승인자는 Drive 파일에서 해결되지 않은 모든 액세스 제안을 검토하고 조치를 취할 수 있습니다. 즉, 프로그래매틱 방식으로 액세스 제안을 쿼리한 후 해결하여 승인 절차를 가속화할 수 있습니다. 또한 승인자가 제안서를 집계하여 볼 수 있습니다.
Drive API는 대기 중인 액세스 제안을 보고 해결할 수 있도록 accessproposals
리소스를 제공합니다. accessproposals
리소스의 메서드는 파일, 폴더, 공유 드라이브 내 파일에는 작동하지만 공유 드라이브에는 작동하지 않습니다.
다음 용어는 액세스 제안서에만 해당합니다.
- 요청자: Drive 항목에 대한 액세스 제안을 시작한 사용자입니다.
- 수신자: 액세스 제안이 승인된 경우 파일에 대한 추가 권한을 받는 사용자입니다. 수신자가 요청자와 동일한 경우가 많지만 항상 그런 것은 아닙니다.
- 승인자: 액세스 제안을 승인 (또는 거부)할 책임이 있는 사용자입니다. 이는 일반적으로 문서의 소유자이거나 문서를 공유할 수 있기 때문입니다.
대기 중인 액세스 제안서 나열
Drive 항목에서 대기 중인 모든 액세스 제안을 나열하려면 accessproposals
리소스에서 list()
메서드를 호출하고 fileId
경로 매개변수를 포함합니다.
파일의 승인자만 파일에 대기 중인 제안을 표시할 수 있습니다. 승인자는 파일에 대한 can_approve_access_proposals
기능이 있는 사용자입니다. 요청자가 승인자가 아닌 경우 빈 목록이 반환됩니다. capabilities
에 관한 자세한 내용은 기능 섹션을 참고하세요.
응답 본문은 파일에서 해결되지 않은 액세스 제안 목록을 나타내는 AccessProposal
객체로 구성됩니다.
AccessProposal
객체에는 요청자, 수신자, 요청자가 추가한 메시지와 같은 각 제안서에 관한 정보가 포함됩니다. 또한 요청자의 제안된 role
를 view
로 그룹화하는 AccessProposalRoleAndView
객체도 포함됩니다. role
는 반복 필드이므로 각 제안서에 여러 개가 있을 수 있습니다. 예를 들어 제안서에는 role=reader
및 view=published
의 AccessProposalRoleAndView
객체와 role=writer
값만 있는 추가 AccessProposalRoleAndView
객체가 있을 수 있습니다. 자세한 내용은 뷰를 참고하세요.
다음 쿼리 매개변수를 전달하여 액세스 제안서의 페이징을 맞춤설정하거나 필터링합니다.
pageToken
: 이전 목록 호출에서 수신된 페이지 토큰입니다. 후속 페이지를 검색하려면 이 토큰을 입력합니다.pageSize
: 페이지당 반환할 최대 액세스 제안서 수입니다.
대기 중인 액세스 제안 해결
Drive 항목에서 대기 중인 모든 액세스 제안을 해결하려면 accessproposals
리소스에서 resolve()
메서드를 호출하고 fileId
및 proposalId
경로 매개변수를 포함합니다.
resolve()
메서드에는 제안서에 취할 작업을 나타내는 action
쿼리 매개변수가 포함됩니다. Action
객체는 제안서의 상태 변경을 추적하여 제안서가 승인 또는 거부되었는지 확인합니다.
resolve()
메서드에는 선택적 쿼리 매개변수인 role
및 view
도 포함됩니다. 지원되는 역할은 writer
, commenter
, reader
뿐입니다. 역할이 지정되지 않으면 기본값은 reader
입니다. 선택적 쿼리 매개변수 send_notification
를 추가하면 제안서가 수락되거나 거부될 때 요청자에게 이메일 알림을 보낼 수 있습니다.
list()
메서드와 마찬가지로 제안을 해결하는 사용자는 파일에 can_approve_access_proposals
기능이 있어야 합니다. capabilities
에 관한 자세한 내용은 기능 섹션을 참고하세요.
제안은 Drive 리소스 공유 시나리오에 나열된 것과 동일한 패턴을 사용하여 해결됩니다. 동일한 사용자에 대해 역할이 서로 다른 제안이 여러 개 있는 경우 다음이 적용됩니다.
- 한 제안은 수락되고 다른 제안은 거부된 경우 수락된 역할이 Drive 항목에 적용됩니다.
- 두 제안이 동시에 수락되면 권한이 더 높은 제안 (예:
role=writer
대role=reader
)이 적용됩니다. 다른 액세스 제안은 항목에서 삭제됩니다.
resolve()
메서드에 제안서를 전송하면 공유 작업이 완료됩니다. AccessProposal
가 더 이상 list()
메서드를 통해 반환되지 않습니다. 제안이 승인되면 사용자는 permissions
모음을 사용하여 파일 또는 폴더의 권한을 업데이트해야 합니다. 자세한 내용은 권한 변경 섹션을 참고하세요.
파일 또는 폴더에 대한 액세스 권한 취소하기
파일 또는 폴더에 대한 액세스 권한을 취소하려면 권한을 삭제하도록 설정된 fileId
및 permissionId
경로 매개변수를 사용하여 permissions
리소스에서 delete()
메서드를 호출합니다.
'내 드라이브'의 항목의 경우 상속된 권한을 삭제할 수 있습니다. 상속된 권한을 삭제하면 항목 및 하위 항목(있는 경우)에 대한 액세스 권한이 취소됩니다.
공유 드라이브의 항목의 경우 상속된 권한을 취소할 수 없습니다. 대신 상위 파일 또는 폴더의 권한을 업데이트하거나 취소합니다.
delete()
메서드는 공유 드라이브 파일 또는 폴더에 직접 적용된 권한을 삭제하는 데도 사용됩니다.
예 보기
다음 코드 샘플은 permissionId
를 삭제하여 액세스 권한을 취소하는 방법을 보여줍니다. 성공한 경우 응답 본문은 비어 있습니다. 권한이 삭제되었는지 확인하려면 permissions
리소스에서 fileId
경로 매개변수를 사용하여 list()
메서드를 사용합니다.
요청
DELETE https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions/PERMISSION_ID
동일한 조직의 다른 Google Workspace 계정으로 파일 소유권 이전하기
'내 드라이브'에 있는 파일의 소유권은 한 Google Workspace 계정에서 동일한 조직의 다른 계정으로 이전할 수 있습니다. 공유 드라이브를 소유한 조직이 그 안에 있는 파일을 소유합니다. 따라서 공유 드라이브의 파일 및 폴더에는 소유권 이전이 지원되지 않습니다. 공유 드라이브의 주최자는 공유 드라이브에서 자신의 '내 드라이브'로 항목을 이동하여 소유권을 이전할 수 있습니다.
'내 드라이브'에서 파일의 소유권을 이전하려면 다음 중 하나를 실행합니다.
특정 사용자(
type=user
)에게 소유자 액세스 권한 (role=owner
)을 부여하는 파일 권한을 만듭니다.role=owner
를 사용하여 기존 파일의 권한을 업데이트하고 지정된 사용자 (transferOwnership=true
)에게 소유권을 이전합니다.
한 소비자 계정에서 다른 소비자 계정으로 파일 소유권 이전하기
파일의 소유권은 한 소비자 계정에서 다른 계정으로 이전할 수 있습니다. 그러나 Drive에서는 향후 소유자가 이전에 명시적으로 동의할 때까지 두 소비자 계정 간에 파일 소유권을 이전하지 않습니다. 파일 소유권을 한 소비자 계정에서 다른 소비자 계정으로 이전하려면 다음 단계를 따르세요.
현재 소유자는 향후 소유자의 파일 권한을 생성하거나 업데이트하여 소유권 이전을 시작합니다. 권한에는
role=writer
,type=user
,pendingOwner=true
설정이 포함되어야 합니다. 현재 소유자가 향후 소유자를 위해 권한을 만드는 경우 향후 소유자에게 파일 소유권을 가져오라는 알림 이메일이 전송됩니다.예비 소유자는 파일 권한을 생성하거나 업데이트하여 소유권 이전 요청을 수락합니다. 권한에는
role=owner
및transferOwnership=true
설정이 포함되어야 합니다. 신규 소유자가 새 권한을 만드는 경우 이전 소유자에게 소유권이 이전되었음을 알리는 이메일 알림이 전송됩니다.
파일이 이전되면 이전 소유자의 역할이 writer
로 다운그레이드됩니다.
일괄 요청으로 여러 권한 변경
여러 권한을 수정하려면 일괄 요청을 사용하는 것이 좋습니다.
다음은 클라이언트 라이브러리로 일괄 권한 수정을 실행하는 예입니다.