모든 Google Drive 파일, 폴더, 공유 드라이브에는 연결된 permissions 리소스가 있습니다. 각 리소스는 특정 type (user, group, domain, anyone) 및 role (owner, organizer, fileOrganizer, writer, commenter, reader)의 권한을 식별합니다. 예를 들어 한 파일에는 특정 사용자 (type=user)에게 읽기 전용 액세스 권한 (role=reader)을 부여하는 권한이 있을 수 있고, 다른 권한은 특정 그룹 (type=group)의 구성원에게 파일에 댓글을 추가할 수 있는 권한 (role=commenter)을 부여할 수 있습니다.
역할 및 각 역할에 허용된 작업의 전체 목록은 역할 및 권한을 참고하세요.
권한이 전파되는 방식
권한은 상위 폴더에서 모든 하위 항목으로 하향 전파됩니다.
- 기본적으로 상속됨: 모든 하위 파일과 폴더는 상위 폴더의 권한을 자동으로 상속받습니다.
- 자녀 항목에서 축소할 수 없음: 자녀 항목에서 상속된 권한을 삭제하거나 축소할 수 없습니다. 변경사항은 원본 상위 항목에서 적용해야 하며, 폴더는 제한된 액세스 설정을 사용해야 합니다.
- 하위 요소에서 확장 가능: 하위 항목은 더 허용적인 역할을 부여할 수 있습니다. 예를 들어 사용자가
role=reader권한을 가진 폴더 내 파일에role=writer권한을 부여할 수 있습니다. - 이동 시 재평가: 항목을 새 상위 폴더로 이동하면 새 상위 폴더의 권한이 항목과 하위 항목에 재평가되어 적용됩니다.
파일 링크 및 액세스 제어
특정 사용자 또는 그룹과 파일이나 폴더를 공유하면 항목에 액세스하는 URL이 변경되지 않으며 각 사용자에 대해 고유한 링크가 생성되지 않습니다.
대신 항목에는 fileId에 기반한 단일한 상수 링크가 있습니다.
드라이브는 항목의 ACL을 평가하여 액세스를 제어합니다. 사용자가 링크를 열려고 하면 Drive에서 인증된 ID를 ACL에 대해 확인합니다. 권한이 취소되거나 만료일에 도달하면 사용자가 ACL에서 삭제됩니다. 사용자가 링크를 다시 방문하려고 하면 Drive에서 액세스를 거부합니다.
파일 기능 이해하기
permissions 리소스는 액세스 권한이 있는 사용자 (ACL)를 정의하지만 현재 사용자가 애플리케이션의 UI에서 특정 작업을 실행할 수 있는지 여부를 직접 나타내지는 않습니다.
대신 files 리소스에는 Google Drive API가 사용자의 역할과 항목 설정을 기반으로 동적으로 계산하는 불리언 capabilities 필드 (예: canComment, canShare, canDelete)의 컬렉션이 포함됩니다.
파일 기능 가져오기
앱의 UI를 렌더링할 때는 권한을 직접 파싱하는 대신 files.capabilities를 확인하세요.
fields=capabilities를 사용하여files.get메서드를 호출합니다. 자세한 내용은 특정 필드 반환을 참고하세요.- 반환된 불리언 플래그를 사용하여 인터페이스에서 해당 작업을 사용 설정하거나 사용 중지합니다. 예를 들어
canComment이false이면 댓글을 사용 중지합니다.
Drive 리소스 공유 시나리오
다음 표에는 여러 위치와 항목 유형 간에 Drive 리소스를 공유하는 데 필요한 역할과 조건이 나와 있습니다.
| 위치 | 항목 | 필요한 역할 | 주요 제약 조건 |
|---|---|---|---|
| 내 드라이브 | 파일 또는 폴더 | owner 또는 writer |
writersCanShare=false인 경우 owner가 필요합니다.폴더의 임시 액세스를 만료하려면 reader이 필요합니다 (만료일 설정하기 참고). |
| 공유 드라이브 | 파일 | organizer, fileOrganizer, writer |
writersCanShare는 항상 true로 취급됩니다. |
| 공유 드라이브 | 폴더 | organizer |
fileOrganizer는 sharingFoldersRequiresOrganizerPermission이 false인 경우에도 공유할 수 있습니다. |
| 공유 드라이브 | 멤버십 | organizer |
user 또는 group에만 적용됩니다 (도메인에는 적용되지 않음). |
권한 관리
다음 표에는 permissions 리소스에서 사용할 수 있는 메서드가 요약되어 있습니다.
| 메서드 | API 엔드포인트 | 주요 매개변수 | 참조 |
|---|---|---|---|
| 만들기 | POST https://www.googleapis.com/drive/v3/files/{fileId}/permissions |
role, type, emailAddress 또는 domain |
permissions.create |
| 가져오기 | GET https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} |
fields |
permissions.get |
| 목록 | GET https://www.googleapis.com/drive/v3/files/{fileId}/permissions |
pageSize, supportsAllDrives, pageToken |
permissions.list |
| 업데이트 | PATCH https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} |
role, allowFileDiscovery |
permissions.update |
| 삭제 | DELETE https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} |
supportsAllDrives |
permissions.delete |
권한 만들기
파일, 폴더 또는 공유 드라이브를 공유하려면 fileId를 사용하여 permissions 리소스에서 create 메서드를 호출합니다.
권한을 만들면 항목에 새 ACL 항목이 추가되고 할당된 permissionId이 반환됩니다.
요청 본문에 다음 필드를 제공합니다.
role: 부여할 액세스 수준입니다 (예:reader,commenter,writer). 전체 목록은 역할 및 권한을 참고하세요.type: 수혜자의 범위 (user,group,domain또는anyone)입니다.- 수혜자 식별자 (
type에 따라 필수):emailAddress:type이user또는group인 경우 필수입니다.domain:type이domain인 경우 필수입니다.
다음 코드 샘플은 권한을 만드는 방법을 보여줍니다. 응답은 할당된 permissionId를 포함하여 permissions 리소스의 인스턴스를 반환합니다.
요청
POST https://www.googleapis.com/drive/v3/files/FILE_ID/permissions{ "role": "commenter", "type": "user", "emailAddress": "alex@altostrat.com" }
응답
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "commenter"
}공유 대상 그룹과 공유
공유 대상 그룹은 사용자에게 항목을 공유하도록 권장할 수 있는 사용자 그룹(부서, 팀 등)입니다. 사용자가 전체 조직이 아닌 특정 대상 또는 제한된 대상과 항목을 공유하도록 할 수 있습니다. 공유 대상 그룹을 사용하면 데이터의 보안 및 개인 정보 보호를 개선하고 사용자가 적절하게 공유할 수 있습니다.
타겟 잠재고객과 공유하려면 type=domain를 설정하고 domain을 <TARGET_AUDIENCE_ID>.audience.googledomains.com로 설정합니다. Google 관리 콘솔에서 공유 대상 그룹을 찾거나 만드는 방법에 대한 자세한 내용은 공유 대상 그룹 정보를 참고하세요.
사용자가 타겟 잠재고객과 상호작용하는 방식을 확인하려면 링크 공유의 사용자 환경을 참고하세요.
권한 가져오기
권한을 가져오려면 fileId 및 permissionId 경로 매개변수를 사용하여 permissions 리소스에서 get 메서드를 호출합니다. 권한 ID를 모르는 경우 먼저 모든 권한을 나열합니다.
권한 나열
파일, 폴더 또는 공유 드라이브의 권한을 나열하려면 필요한 fileId 경로 매개변수와 함께 permissions 리소스에서 list 메서드를 호출합니다.
다음 선택적 쿼리 매개변수를 포함하여 응답을 페이지로 나누거나 필터링할 수 있습니다.
pageSize(선택사항): 페이지당 반환할 최대 권한 수입니다. 공유 드라이브의 파일에 설정되지 않은 경우 최대 100개의 결과가 반환됩니다. 공유 드라이브에 없는 파일에 대해 설정되지 않은 경우 전체 목록이 반환됩니다.pageToken(선택사항): 후속 페이지를 가져오기 위한 이전 목록 호출의 페이지 토큰입니다.supportsAllDrives(선택사항): 요청하는 앱이 내 드라이브와 공유 드라이브를 모두 지원하는지 여부입니다.useDomainAdminAccess(선택사항): 도메인 관리자로 요청을 실행하려면true로 설정합니다.fileId매개변수가 공유 드라이브를 참조하고 요청자가 공유 드라이브가 속한 도메인의 관리자인 경우 요청자에게 액세스 권한이 부여됩니다. 자세한 내용은 도메인 관리자로 공유 드라이브 관리하기를 참고하세요.includePermissionsForView(선택사항): 응답에 포함할 추가 보기 권한입니다.published만 지원됩니다.fields(선택사항): 응답에 반환할 특정 필드입니다. 기본적으로list는id,type,kind,role만 반환합니다.permissionDetails와 같은 추가 필드를 반환하려면 이 매개변수를 사용하여 지정합니다. 자세한 내용은 특정 필드 반환을 참고하세요.
역할 소스 확인
파일 또는 폴더의 역할을 변경하려면 역할의 소스를 알아야 합니다. 공유 드라이브의 경우 역할의 소스는 공유 드라이브의 멤버십, 폴더의 역할 또는 파일의 역할을 기반으로 할 수 있습니다.
공유 드라이브 또는 드라이브 내 항목의 역할 소스를 확인하려면 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
}
]
}권한 업데이트
파일 또는 폴더의 권한을 업데이트하려면 할당된 역할을 변경하면 됩니다. 역할 소스를 찾는 방법에 대한 자세한 내용은 역할 소스 확인을 참고하세요.
fileId경로 매개변수가 연결된 파일, 폴더 또는 공유 드라이브로 설정되고permissionId경로 매개변수가 변경할 권한으로 설정된permissions리소스에서update메서드를 호출합니다.permissionId를 찾으려면fileId경로 매개변수와 함께permissions리소스에서list메서드를 사용합니다.요청에서 새
role를 식별합니다.
사용자 또는 그룹이 이미 멤버인 경우에도 공유 드라이브의 개별 파일 또는 폴더에 대한 권한을 부여할 수 있습니다. 예를 들어 Alex는 공유 드라이브의 멤버십에 role=commenter가 포함되어 있습니다. 하지만 앱은 공유 드라이브의 파일에 대해 Alex에게 role=writer를 부여할 수 있습니다. 이 경우 새 역할이 멤버십을 통해 부여된 역할보다 더 허용적이므로 새 권한이 파일 또는 폴더의 유효한 역할이 됩니다.
패치 시맨틱을 통해 업데이트를 적용할 수 있습니다. 즉, 리소스를 부분적으로 수정할 수 있습니다. 요청에서 수정하려는 필드를 명시적으로 설정해야 합니다. 요청에 포함되지 않은 필드는 기존 값을 유지합니다. 자세한 내용은 부분 리소스 작업을 참고하세요.
역할을 변경하는 것 외에도 권한 type이 domain 또는 anyone인 경우 항목의 검색 가능성을 수정할 수 있습니다. 공유 파일을 검색 가능하게 하거나 목록에서 제외하려면 패치 요청에 allowFileDiscovery 불리언 필드를 포함하세요. 이 값을 true로 설정하면 직접 링크가 제공되지 않은 경우에도 지정된 잠재고객의 검색 결과에 항목이 표시됩니다. 이 설정을 변경하기 위해 권한을 삭제하고 다시 만들 필요는 없습니다.
다음 코드 샘플은 파일 또는 폴더의 권한을 commenter에서 writer로 변경하는 방법을 보여줍니다. 응답은 permissions 리소스의 인스턴스를 반환합니다.
요청
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID
{
"role": "writer"
}응답
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "writer"
}일괄 요청으로 여러 권한 업데이트
동일한 파일, 폴더 또는 공유 드라이브에 대한 동시 권한 수정은 지원되지 않습니다. 이 제한은 동일한 수신자의 권한을 수정하는지 아니면 다른 수신자의 권한을 수정하는지, 요청이 단일 앱에서 시작되는지 아니면 여러 사용자로부터 시작되는지에 관계없이 모든 변경 작업 (예: 업데이트 또는 삭제)에 적용됩니다.
Drive는 항목의 권한을 단일 ACL로 평가하고 업데이트합니다. 동시 작업으로 인해 '마지막 쓰기가 적용'되는 경합 상태가 발생하여 권한 변경사항이 자동으로 덮어쓰여지거나 sharingRateLimitExceeded 오류가 트리거될 수 있습니다.
충돌을 방지하려면 동일한 항목에 대한 권한 변경사항을 순차적으로 실행하거나 일괄 요청을 사용하여 단일 요청에서 여러 권한을 수정하세요.
다음은 클라이언트 라이브러리를 사용하여 일괄 권한 수정을 실행하는 예입니다.
자바
Python
Node.js
PHP
.NET
권한 삭제
파일 또는 폴더에 대한 액세스 권한을 취소하려면 fileId 및 permissionId 경로 매개변수를 사용하여 permissions 리소스에서 delete 메서드를 호출합니다.
상속된 권한은 하위 항목에서 직접 취소할 수 없습니다. 대신 상위 폴더의 권한을 업데이트하거나 삭제하세요 (또는 액세스 권한이 제한된 설정 사용).
상위 항목에서 사용자의 액세스 권한을 삭제하면 해당 상위 항목에서 상속된 권한만 취소됩니다. 사용자에게 하위 항목에 대한 직접 권한도 부여된 경우 해당 직접 액세스는 유지됩니다. 권한이 삭제되었는지 확인하려면 fileId로 list를 호출합니다.
만료일 설정
파일 또는 폴더에 대한 임시 액세스 권한을 부여하려면 create 또는 update 메서드를 호출할 때 expirationTime 필드 (RFC 3339 날짜-시간)를 설정합니다.
만료 시간에는 다음과 같은 제한사항이 있습니다.
user및group권한에만 설정할 수 있습니다 (domain또는anyone에는 설정할 수 없음).- 시간은 현재로부터 최대 1년 이내여야 합니다.
- 폴더의 경우 임시 액세스는
reader역할에서만 지원됩니다.
관련 주제
- 대기 중인 액세스 제안 관리하기
- 액세스가 제한된 폴더와 광범위한 액세스 권한이 있는 폴더 관리하기
- 파일 소유권 이전하기
- 파일 콘텐츠 보호하기
- 리소스 키를 사용하여 링크로 공유된 Drive 파일에 액세스하기
- 역할 및 권한