Cada arquivo, pasta e drive compartilhado do Google Drive tem recursos associados
permissions. Cada recurso
identifica a permissão para um
type (user,
group, domain, anyone) e
role (owner,
organizer, fileOrganizer, writer, commenter, reader). Por exemplo, um
arquivo pode ter uma permissão que concede a um usuário específico (type=user) acesso somente leitura (role=reader), enquanto outra permissão concede aos membros de um grupo específico (type=group) a capacidade de adicionar comentários a um arquivo (role=commenter).
Para conferir uma lista completa de papéis e as operações permitidas por cada um, consulte Papéis e permissões.
Como as permissões funcionam
As listas de permissões de uma pasta são propagadas para baixo. Todos os arquivos e pastas filhos herdam permissões do pai. Sempre que as permissões ou a hierarquia são alteradas, a propagação ocorre de forma recursiva em todas as pastas aninhadas. Por exemplo, se um arquivo existir em uma pasta e essa pasta for movida para outra, as permissões da nova pasta serão propagadas para o arquivo. Se a nova pasta conceder ao usuário do arquivo um novo papel, como "gravador", ela vai substituir o papel antigo.
Por outro lado, se um arquivo herdar role=writer de uma pasta e for movido para outra que forneça um papel de "leitor", o arquivo vai herdar role=reader.
As permissões herdadas não podem ser removidas ou reduzidas em nenhum item. Em vez disso, essas permissões precisam ser ajustadas no pai de onde se originam ou uma pasta na hierarquia precisa ativar a configuração de acesso limitado.
As permissões herdadas podem ser aumentadas em um item. Se uma permissão for aumentada em um filho, a mudança da permissão de um pai não vai afetar a permissão do filho, a menos que a nova permissão do pai seja maior que a do filho.
Não há suporte para operações de permissões simultâneas no mesmo arquivo. Somente a última atualização é aplicada.
Entender as capacidades de arquivos
O recurso permissions não determina a capacidade do usuário atual de realizar ações em um arquivo ou pasta.
Em vez disso, o recurso files contém uma coleção
de campos booleanos capabilities
usados para indicar se uma ação pode ser realizada em um arquivo ou pasta.
A API Google Drive define esses campos com base no recurso permissions do usuário atual associado ao arquivo ou pasta.
Por exemplo, quando Alex faz login no seu app e tenta compartilhar um arquivo, o papel de Alex é verificado para permissões no arquivo. Se o papel permitir que ele compartilhe um arquivo, as capabilities relacionadas ao arquivo, como canShare, serão definidas em relação ao papel. Se Alex quiser compartilhar o arquivo, seu app vai verificar as capabilities para garantir que canShare esteja definido como true.
Receber capacidades de arquivos
Quando o app abre um arquivo, ele precisa verificar as capacidades do arquivo e renderizar a interface para refletir as permissões do usuário atual. Por exemplo, se o usuário não tiver a capacidade canComment no arquivo, a capacidade de comentar deverá ser desativada na interface.
Para verificar as capacidades, chame o get
método no recurso files com o parâmetro de caminho fileId
e o parâmetro fields definido como o campo capabilities. Para
mais informações sobre como retornar campos usando o fields parâmetro, consulte
Retornar campos específicos.
O exemplo de código a seguir mostra como verificar as permissões do usuário. A resposta retorna uma lista de capacidades que o usuário tem no arquivo. Cada capacidade corresponde a uma ação refinada que um usuário pode realizar. Alguns campos só são preenchidos para itens em drives compartilhados.
Solicitação
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=capabilitiesResposta
{ "capabilities": { "canAcceptOwnership": false, "canAddChildren": false, "canAddMyDriveParent": false, "canChangeCopyRequiresWriterPermission": true, "canChangeItemDownloadRestriction": true, "canChangeSecurityUpdateEnabled": false, "canChangeViewersCanCopyContent": true, "canComment": true, "canCopy": true, "canDelete": true, "canDisableInheritedPermissions": false, "canDownload": true, "canEdit": true, "canEnableInheritedPermissions": true, "canListChildren": false, "canModifyContent": true, "canModifyContentRestriction": true, "canModifyEditorContentRestriction": true, "canModifyOwnerContentRestriction": true, "canModifyLabels": true, "canMoveChildrenWithinDrive": false, "canMoveItemIntoTeamDrive": true, "canMoveItemOutOfDrive": true, "canMoveItemWithinDrive": true, "canReadLabels": true, "canReadRevisions": true, "canRemoveChildren": false, "canRemoveContentRestriction": false, "canRemoveMyDriveParent": true, "canRename": true, "canShare": true, "canTrash": true, "canUntrash": true } }
Cenários para compartilhar recursos do Drive
Há cinco tipos diferentes de cenários de compartilhamento:
Para compartilhar um arquivo no Meu Drive, o usuário precisa ter
role=writerourole=owner.Se o valor booleano
writersCanShareestiver definido comofalsepara o arquivo, o usuário precisará terrole=owner.Se o usuário com
role=writertiver acesso temporário regido por uma data e hora de validade, ele não poderá compartilhar o arquivo. Para mais informações, consulte Definir uma data de validade para limitar o acesso a itens.
Para compartilhar uma pasta no Meu Drive, o usuário precisa ter
role=writerourole=owner.Se o valor booleano
writersCanShareestiver definido comofalsepara o arquivo, o usuário precisará ter orole=ownermais permissivo.O acesso temporário (regido por uma data e hora de validade) só é permitido em pastas com
role=reader. Para mais informações, consulte consulte Definir uma data de validade para limitar o acesso a itens.
Para compartilhar um arquivo em um drive compartilhado, o usuário precisa ter
role=writer,role=fileOrganizerourole=organizer.- A configuração
writersCanSharenão se aplica a itens em drives compartilhados. Ela é tratada como se estivesse sempre definida comotrue.
- A configuração
Para compartilhar uma pasta em um drive compartilhado, o usuário precisa ter
role=organizer.- Se a
sharingFoldersRequiresOrganizerPermissionrestrição em um drive compartilhado estiver definida comofalse, os usuários comrole=fileOrganizerpoderão compartilhar pastas nesse drive compartilhado.
- Se a
Para gerenciar a participação em drives compartilhados, o usuário precisa ter
role=organizer. Somente usuários e grupos podem ser membros de drives compartilhados.
Usar o parâmetro "fields"
Se você quiser especificar os campos a serem retornados na resposta, defina o
fields parâmetro
do sistema
com qualquer método do recurso permissions. Se você omitir o parâmetro fields, o servidor vai retornar um conjunto padrão de campos específicos do método.
Por exemplo, o list método retorna
apenas os campos id, type, kind e role para cada arquivo. Para retornar
campos diferentes, consulte Retornar campos específicos.
Criar uma permissão
Os dois campos a seguir são necessários ao criar uma permissão:
type: Otypeidentifica o escopo da permissão (user,group,domain, ouanyone). Uma permissão comtype=userse aplica a um usuário específico, enquanto uma permissão comtype=domainse aplica a todos em um domínio específico.role: o camporoleidentifica as operações que otypepode realizar. Por exemplo, uma permissão comtype=usererole=readerconcede a um usuário específico acesso somente leitura ao arquivo ou pasta. Ou, uma permissão comtype=domainerole=commenterpermite que todos no domínio adicionem comentários a um arquivo. Para conferir uma lista completa de papéis e as operações permitidas por cada um, consulte Papéis e permissões.
Ao criar uma permissão em que type=user ou type=group, você também precisa
fornecer um
emailAddress
para vincular o usuário ou grupo específico à permissão.
Ao criar uma permissão em que type=domain, você também precisa fornecer um
domain para vincular um
domínio específico à permissão.
Para criar uma permissão:
- Use o
createmétodo nopermissionsrecurso com ofileIdparâmetro de caminho para o arquivo ou pasta associado. - No corpo da solicitação, especifique o
typee orole. - Se
type=useroutype=group, forneça umemailAddress. Setype=domain, forneça umdomain.
O exemplo de código a seguir mostra como criar uma permissão. A resposta retorna uma instância de um recurso permissions, incluindo o permissionId atribuído.
Solicitação
POST https://www.googleapis.com/drive/v3/files/FILE_ID/permissions{ "requests": [ { "type": "user", "role": "commenter", "emailAddress": "alex@altostrat.com" } ] }
Resposta
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "commenter"
}Usar públicos-alvo
Os públicos-alvo são grupos de pessoas, como departamentos ou equipes, que você recomenda para os usuários compartilharem itens. Você pode incentivar os usuários a compartilhar itens com um público mais específico ou limitado, em vez de toda a organização. Os públicos-alvo podem ajudar a melhorar a segurança e a privacidade dos seus dados e facilitar o compartilhamento adequado para os usuários. Para mais informações, consulte Sobre públicos-alvo.
Para usar públicos-alvo:
No Google Admin Console, acesse Menu > Diretório > Públicos-alvo.
Você precisa fazer login com uma conta com privilégios de superadministrador para essa tarefa.
Na lista de públicos-alvo, clique no nome do público-alvo. Para criar um público-alvo, consulte Criar um público alvo.
Copie o ID exclusivo do URL do público-alvo:
https://admin.google.com/ac/targetaudiences/ID.Crie uma permissão com
type=domaine defina o campodomaincomoID.audience.googledomains.com.
Para saber como os usuários interagem com os públicos-alvo, consulte Experiência do usuário para compartilhamento de links.
Receber uma permissão
Para receber uma permissão, use o get método
no recurso permissions com os
fileId e permissionId parâmetros de caminho. Se você não souber o ID da permissão, poderá listar todas as permissões usando o método list.
O exemplo de código a seguir mostra como receber uma permissão por ID. A resposta retorna uma instância de um recurso permissions.
Solicitação
GET https://www.googleapis.com/drive/v3/files/FILE_ID/permissionsPERMISSION_ID
Resposta
{
"kind": "drive#permissionList",
"permissions": [
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "commenter"
}
]
}Listar todas as permissões
Para listar permissões de um arquivo, pasta ou drive compartilhado, use o list método no permissions recurso com o fileId parâmetro de caminho.
Transmita os seguintes parâmetros de consulta para personalizar a paginação ou filtrar permissões:
pageSize: o número máximo de permissões a serem retornadas por página. Se não estiver definido para arquivos em um drive compartilhado, no máximo 100 resultados serão retornados. Se não estiver definido para arquivos que não estão em um drive compartilhado, a lista inteira será retornada.pageToken: um token de página, recebido de uma chamada de lista anterior. Forneça esse token para recuperar a página subsequente.supportsAllDrives: indica se o app solicitante oferece suporte ao Meu Drive e aos drives compartilhados.useDomainAdminAccess: defina comotruepara emitir a solicitação como um administrador de domínio. Se o parâmetrofileIdse referir a um drive compartilhado e o solicitante for um administrador do domínio a que o drive compartilhado pertence. Para mais informações, consulte Gerenciar drives compartilhados como administradores.includePermissionsForView: as permissões da visualização adicional a serem incluídas na resposta. Somentepublishedé compatível.
O exemplo de código a seguir mostra como receber todas as permissões. A resposta retorna uma lista de permissões para um arquivo, pasta ou drive compartilhado.
Solicitação
GET https://www.googleapis.com/drive/v3/files/FILE_ID/permissionsResposta
{
"kind": "drive#permissionList",
"permissions": [
{
"id": "PERMISSION_ID",
"type": "user",
"kind": "drive#permission",
"role": "commenter"
}
]
}Atualizar permissões
Para atualizar as permissões de um arquivo ou pasta, você pode mudar o papel atribuído. Para mais informações sobre como encontrar a origem da função, consulte Determinar a origem da função.
Chame o
updatemétodo nopermissionsrecurso com ofileIdparâmetro de caminho definido como o arquivo, pasta ou drive compartilhado associado e opermissionIdparâmetro de caminho definido como a permissão a ser alterada. Para encontrar opermissionId, use olistmétodo no recursopermissionscom o parâmetro de caminhofileId.Na solicitação, identifique o novo
role.
Você pode conceder permissões em arquivos ou pastas individuais em um drive compartilhado, mesmo que o usuário ou grupo já seja um membro. Por exemplo, Alex tem role=commenter como parte da participação em um drive compartilhado. No entanto, seu app pode conceder a Alex role=writer para um arquivo em um drive compartilhado. Nesse caso, como o novo papel é mais permissivo do que o papel concedido pela participação, a nova permissão se torna o papel efetivo para o arquivo ou pasta.
Você pode aplicar atualizações usando a semântica de patch, o que significa que é possível fazer modificações parciais em um recurso. É necessário definir explicitamente os campos que você pretende modificar na solicitação. Todos os campos não incluídos na solicitação mantêm os valores atuais. Para mais informações, consulte Trabalhar com recursos parciais.
O exemplo de código a seguir mostra como mudar as permissões de um arquivo ou pasta de commenter para writer. A resposta retorna uma instância de um recurso permissions.
Solicitação
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID
{
"role": "writer"
}Resposta
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "writer"
}Determinar a origem do papel
Para mudar o papel em um arquivo ou pasta, você precisa saber a origem do papel. Para drives compartilhados, a origem de um papel pode ser baseada na participação no drive compartilhado, no papel em uma pasta ou no papel em um arquivo.
Para determinar a origem do papel de um drive compartilhado ou de itens nesse drive,
chame o get método no
permissions recurso com os fileId e
permissionId parâmetros de caminho, e o fields parâmetro definido como o
permissionDetails campo.
Para encontrar o permissionId, use o
list método no permissions
recurso com o fileId parâmetro de caminho. Para buscar o permissionDetails
campo na solicitação list, defina o parâmetro fields como
permissions/permissionDetails.
Esse campo enumera todas as permissões de arquivo herdadas e diretas para o usuário, grupo ou domínio.
O exemplo de código a seguir mostra como determinar a origem do papel. A resposta retorna o permissionDetails de um recurso permissions. O campo inheritedFrom fornece o ID do item de que a permissão é herdada.
Solicitação
GET https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID?fields=permissionDetails&supportsAllDrives=true
Resposta
{
"permissionDetails": [
{
"permissionType": "member",
"role": "commenter",
"inheritedFrom": "INHERITED_FROM_ID",
"inherited": true
},
{
"permissionType": "file",
"role": "writer",
"inherited": false
}
]
}Atualizar várias permissões com solicitações em lote
Recomendamos o uso de solicitações em lote para modificar várias permissões.
Confira a seguir um exemplo de como realizar uma modificação de permissão em lote com uma biblioteca de cliente.
Java
Python
Node.js
PHP
.NET
Excluir uma permissão
Para revogar o acesso a um arquivo ou pasta, chame o
delete método no
permissions recurso com os fileId e
os permissionId parâmetros de caminho definidos para excluir a permissão.
As permissões herdadas não podem ser revogadas. Atualize ou exclua a permissão na pasta mãe. A exclusão de uma permissão em uma pasta também revoga qualquer acesso equivalente em itens filhos.
A redução de permissões em comparação com um pai exige o uso da configuração de acesso limitado.
O exemplo de código a seguir mostra como revogar o acesso excluindo um permissionId. Se não houver nenhum problema, o corpo da resposta será um objeto JSON vazio. Para confirmar se a permissão foi removida, use o list método no recurso permissions com o parâmetro de caminho fileId.
Solicitação
DELETE https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID
Definir uma data de validade para limitar o acesso a itens
Ao trabalhar com pessoas em um projeto sensível, talvez você queira restringir o acesso delas a determinados itens no Drive após um período. Para arquivos e pastas, é possível definir uma data de validade para limitar ou remover o acesso a esse item.
Para definir a data de validade:
Use o
createmétodo nopermissionsrecurso e defina oexpirationTimecampo (junto com os outros campos obrigatórios). Para mais informações, consulte Criar uma permissão.Use o
updatemétodo nopermissionsrecurso e defina oexpirationTimecampo (junto com os outros campos obrigatórios). Para mais informações, consulte Atualizar permissões.
O
expirationTime
campo indica quando a permissão expira usando RFC 3339
data e hora. Os horários de validade têm as seguintes restrições:
- Só podem ser definidos em permissões de usuário e grupo.
- O horário precisa ser no futuro.
- O horário não pode ser mais de um ano no futuro.
- Somente o papel
readeré qualificado para acesso temporário em uma pasta.
Para mais informações sobre a data de validade, consulte os seguintes artigos:
Temas relacionados
- Gerenciar propostas de acesso pendentes
- Gerenciar pastas com acesso limitado e expansivo
- Transferir a propriedade de arquivos
- Proteger o conteúdo do arquivo
- Acessar arquivos de drive compartilhados por link usando chaves de recurso
- Papéis e permissões