Access to files & folders is determined by an access control list (ACL). An ACL is a list of permissions that determine whether or not users can perform actions on a file such as read or write. See the permissions guide for additional details about permissions and roles along with the reference guide.
Retrieving permissions
Use the permissions.list
to retrieve
permissions for an item in Drive.
Permissions in Team Drives
Therole
and additionalRoles
fields of a permission reflect the effective
roles the user, group, or domain have for a given item. To determine the source of
the effective roles, use the teamDrivePermissionDetails
field.
This field enumerates all inherited and direct file permissions for the user,
group, or domain.
Manipulating permissions
Use permissions.insert
to grant additional permissions to a user, group, or domain. To change the assigned
role, permissions.update
.
Permissions may be granted on individual items in a Team Drive even if the target user or group is already a member. If the new role is more permissive than the role granted via their membership, the new permission becomes the effective role for the selected items.
Revoking access
To revoke access to an item, delete
the permission. This is also used to delete any direct file access permissions
on a Team Drive item.
For items in "My Drive", it is possible to delete an inherited permission. Doing so revokes access to the item and child items, if any.
For items in a Team Drive, inherited permissions can not be revoked. Update or revoke the permission on the parent item instead.
Transferring ownership
To transfer ownership of a file, insert or update a permission with
the owner
role and set the transerOwnership
query parameter to true
. When
a file is transferred, the previous owner's role is downgraded to writer
.
Ownership transfers are not supported for items in Team Drives. Ownership transfers are implicit when a user moves an item in or out of a Team Drive.
Manipulating permissions with batch requests
We strongly recommend using batch requests to modify multiple permissions.
Examples
Here are examples of performing a batch permission modification with our Drive API client libraries.
Java
String fileId = "1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ";
JsonBatchCallback<Permission> callback = new JsonBatchCallback<Permission>() {
@Override
public void onFailure(GoogleJsonError e,
HttpHeaders responseHeaders)
throws IOException {
// Handle error
System.err.println(e.getMessage());
}
@Override
public void onSuccess(Permission permission,
HttpHeaders responseHeaders)
throws IOException {
System.out.println("Permission ID: " + permission.getId());
}
};
BatchRequest batch = driveService.batch();
Permission userPermission = new Permission()
.setType("user")
.setRole("writer")
.setValue("user@example.com");
driveService.permissions().insert(fileId, userPermission)
.setFields("id")
.queue(batch, callback);
Permission domainPermission = new Permission()
.setType("domain")
.setRole("reader")
.setValue("example.com");
driveService.permissions().insert(fileId, domainPermission)
.setFields("id")
.queue(batch, callback);
batch.execute();
Python
file_id = '1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ'
def callback(request_id, response, exception):
if exception:
# Handle error
print exception
else:
print "Permission Id: %s" % response.get('id')
batch = drive_service.new_batch_http_request(callback=callback)
user_permission = {
'type': 'user',
'role': 'writer',
'value': 'user@example.com'
}
batch.add(drive_service.permissions().insert(
fileId=file_id,
body=user_permission,
fields='id',
))
domain_permission = {
'type': 'domain',
'role': 'reader',
'value': 'example.com'
}
batch.add(drive_service.permissions().insert(
fileId=file_id,
body=domain_permission,
fields='id',
))
batch.execute()
PHP
$fileId = '1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ';
$driveService->getClient()->setUseBatch(true);
try {
$batch = $driveService->createBatch();
$userPermission = new Google_Service_Drive_Permission(array(
'type' => 'user',
'role' => 'writer',
'value' => 'user@example.com'
));
$request = $driveService->permissions->insert(
$fileId, $userPermission, array('fields' => 'id'));
$batch->add($request, 'user');
$domainPermission = new Google_Service_Drive_Permission(array(
'type' => 'domain',
'role' => 'reader',
'value' => 'example.com'
));
$request = $driveService->permissions->insert(
$fileId, $domainPermission, array('fields' => 'id'));
$batch->add($request, 'domain');
$results = $batch->execute();
foreach ($results as $result) {
if ($result instanceof Google_Service_Exception) {
// Handle error
printf($result);
} else {
printf("Permission ID: %s\n", $result->id);
}
}
} finally {
$driveService->getClient()->setUseBatch(false);
}
.NET
var fileId = "1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ";
var batch = new BatchRequest(driveService);
BatchRequest.OnResponse<Permission> callback = delegate (
Permission permission,
RequestError error,
int index,
System.Net.Http.HttpResponseMessage message)
{
if (error != null)
{
// Handle error
Console.WriteLine(error.Message);
}
else
{
Console.WriteLine("Permission ID: " + permission.Id);
}
};
Permission userPermission = new Permission()
{
Type = "user",
Role = "writer",
Value = "user@example.com"
};
var request = driveService.Permissions.Insert(userPermission, fileId);
request.Fields = "id";
batch.Queue(request, callback);
Permission domainPermission = new Permission()
{
Type = "domain",
Role = "reader",
Value = "example.com"
};
request = driveService.Permissions.Insert(domainPermission, fileId);
request.Fields = "id";
batch.Queue(request, callback);
var task = batch.ExecuteAsync();
Ruby
file_id = '1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ'
callback = lambda do |res, err|
if err
# Handle error...
puts err.body
else
puts "Permission ID: #{res.id}"
end
end
drive_service.batch do
user_permission = {
type: 'user',
role: 'writer',
value: 'user@example.com'
}
drive_service.insert_permission(file_id,
user_permission,
fields: 'id',
&callback)
domain_permission = {
type: 'domain',
role: 'reader',
value: 'example.com'
}
drive_service.insert_permission(file_id,
domain_permission,
fields: 'id',
&callback)
end
Node.js
var fileId = '1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ';
var permissions = [
{
'type': 'user',
'role': 'writer',
'value': 'user@example.com'
}, {
'type': 'domain',
'role': 'writer',
'value': 'example.com'
}
];
// Using the NPM module 'async'
async.eachSeries(permissions, function (permission, permissionCallback) {
drive.permissions.insert({
resource: permission,
fileId: fileId,
fields: 'id',
}, function (err, res) {
if (err) {
// Handle error...
console.error(err);
permissionCallback(err);
} else {
console.log('Permission ID:', res.id)
permissionCallback();
}
});
}, function (err) {
if (err) {
// Handle error
console.error(err);
} else {
// All permissions inserted
}
});