Todos os arquivos, pastas e drives compartilhados do Google Drive têm recursos
permissions
associados. Cada recurso
identifica a permissão para um type
específico (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 as permissões da pasta mãe. 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 "escritor", ela vai substituir o antigo.
Por outro lado, se um arquivo herdar role=writer
de uma pasta e for movido para
outra pasta que fornece uma função "reader", o arquivo vai herdar
role=reader
.
As permissões herdadas não podem ser removidas de um arquivo ou pasta em um drive compartilhado. Em vez disso, essas permissões precisam ser ajustadas no item pai direto ou indireto de onde foram herdadas. As permissões herdadas podem ser removidas de itens em "Meu Drive" ou "Compartilhados comigo".
Por outro lado, as permissões herdadas podem ser substituídas em um arquivo ou pasta no Meu
Drive. Portanto, se um arquivo herdar role=writer
de uma pasta do Meu
Drive, você poderá definir role=reader
no arquivo para diminuir o
nível de permissão.
Entender os recursos de arquivo
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 capabilities
booleanos 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 de permissões do usuário atual associado ao arquivo ou à pasta.
Por exemplo, quando Alex faz login no seu app e tenta compartilhar um arquivo, a função
dele é verificada para verificar as permissões no arquivo. Se o papel permitir que eles compartilhem um arquivo,
o capabilities
relacionado ao arquivo, como canShare
, será preenchido
em relação ao papel. Se Alex quiser compartilhar o arquivo, o app vai verificar o
capabilities
para garantir que canShare
esteja definido como true
.
Para conferir um exemplo de como recuperar o arquivo capabilities
, consulte Receber
recursos de arquivo.
Conferir os recursos de arquivo
Quando o app abrir um arquivo, ele vai verificar os recursos do arquivo e renderizar
a interface para refletir as permissões do usuário atual. Por exemplo, se o usuário
não tiver um recurso canComment
no arquivo, a capacidade de comentar
será desativada na interface.
Para verificar os recursos, chame o método get()
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 parâmetro fields
, consulte
Retornar campos específicos.
Mostrar um exemplo
O exemplo de código abaixo mostra como verificar as permissões do usuário. A resposta retorna uma lista de recursos que o usuário tem no arquivo. Cada capability corresponde a uma ação detalhada 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=capabilities
Resposta
{ "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 } }
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=writer
ourole=owner
.Se o valor booleano
writersCanShare
for definido comofalse
para o arquivo, o usuário precisará terrole=owner
.Se o usuário com
role=writer
tiver acesso temporário regido por uma data e hora de expiração, ele não poderá compartilhar o arquivo. Para mais informações, consulte Definir uma data de validade para limitar o acesso a arquivos.
Para compartilhar uma pasta no Meu Drive, o usuário precisa ter
role=writer
ourole=owner
.Se o valor booleano
writersCanShare
estiver definido comofalse
para o arquivo, o usuário precisará ter orole=owner
mais permissivo.O acesso temporário (governado por uma data e hora de validade) não é permitido nas pastas do Meu Drive com
role=writer
. Para mais informações, consulte Definir uma data de validade para limitar o acesso a arquivos.
Para compartilhar um arquivo em um drive compartilhado, o usuário precisa ter
role=writer
,role=fileOrganizer
ourole=organizer
.- A configuração
writersCanShare
não se aplica a itens em drives compartilhados. Ele é tratado como se estivesse sempre definido comotrue
.
- A configuração
Para compartilhar uma pasta em um drive compartilhado, o usuário precisa ter
role=organizer
.- Se a restrição
sharingFoldersRequiresOrganizerPermission
em um drive compartilhado estiver definida comofalse
, os usuários comrole=fileOrganizer
poderão compartilhar pastas nesse drive.
- Se a restrição
Para gerenciar a participação no drive compartilhado, o usuário precisa ter
role=organizer
. Somente usuários e grupos podem ser membros de drives compartilhados.
Criar uma permissão
Os dois campos a seguir são necessários para criar uma permissão:
type
: otype
identifica o escopo da permissão (user
,group
,domain
ouanyone
). Uma permissão comtype=user
se aplica a um usuário específico, enquanto uma permissão comtype=domain
se aplica a todos em um domínio específico.role
: o camporole
identifica as operações que otype
pode executar. Por exemplo, uma permissão comtype=user
erole=reader
concede a um usuário específico acesso somente leitura ao arquivo ou à pasta. Ou uma permissão comtype=domain
erole=commenter
permite 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
, também é necessário fornecer um
domain
para vincular um domínio específico à
permissão.
Para criar uma permissão:
- Use o método
create()
com o parâmetro de caminhofileId
para o arquivo ou a pasta associada. - No corpo da solicitação, especifique
type
erole
. - Se for
type=user
outype=group
, forneça umemailAddress
. Setype=domain
, forneça umdomain
.
Mostrar um exemplo
O exemplo de código abaixo mostra como criar uma permissão. A resposta retorna uma instância de um recurso Permission
, 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ê pode recomendar 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 dos usuários. Para mais informações, consulte Sobre os públicos-alvo de destino.
Para usar públicos-alvo:
No Google Admin Console, acesse Menu > Diretório > Públicos-alvo.
Para realizar essa tarefa, você precisa fazer login usando uma conta com privilégios de superadministrador.
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=domain
e defina o campodomain
comoID.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.
Listar todas as permissões
Use o método list()
no
recurso permissions
para extrair todas
as permissões de um arquivo, pasta ou drive compartilhado.
Mostrar um exemplo
O exemplo de código abaixo mostra como receber todas as permissões. A resposta retorna uma lista de permissões.
Solicitação
GET https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions
Resposta
{
"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, mude o papel atribuído. Para mais informações sobre como encontrar a origem do papel, consulte Determinar a origem do papel.
Chame o método
update()
no recursopermissions
com o parâmetro de caminhopermissionId
definido como a permissão para mudar e o parâmetro de caminhofileId
definido como o arquivo, a pasta ou o drive compartilhado associado. Para encontrar opermissionId
, use o métodolist()
no recursopermissions
com o parâmetro de caminhofileId
.Na solicitação, identifique o novo
role
.
É possível conceder permissões em arquivos ou pastas individuais em um drive compartilhado, mesmo
se o usuário ou grupo já for participante. Por exemplo, Alex tem role=commenter
como parte da assinatura de 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 concedido pela associação, a nova
permissão se torna o papel efetivo do arquivo ou da pasta.
Mostrar um exemplo
O exemplo de código a seguir mostra como mudar as permissões de um arquivo ou pasta de comentarista para autor. 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
{ "requests": [ { "role": "writer" } ] }
Resposta
{
"kind": "drive#permission",
"id": "PERMISSION_ID
",
"type": "user",
"role": "writer"
}
Determinar a origem da função
Para mudar a função em um arquivo ou pasta, você precisa saber a origem dela. Para drives compartilhados, a origem de uma função pode ser baseada na participação no drive compartilhado, na função em uma pasta ou na função em um arquivo.
Para determinar a origem de função de uma unidade compartilhada ou itens dentro dela,
chame o método get()
no
recurso permissions
com os parâmetros de caminho fileId
e
permissionId
e o parâmetro fields
definido como o
campo permissionDetails
.
Para encontrar o permissionId
, use o método
list()
no recurso permissions
com o parâmetro de caminho fileId
. Para buscar o campo permissionDetails
na solicitação list
, defina o parâmetro fields
como
permissions/permissionDetails
.
Esse campo enumera todas as permissões de arquivo diretas e herdadas do usuário, grupo ou domínio.
Mostrar um exemplo
O exemplo de código abaixo mostra como determinar a origem da função. A resposta retorna o permissionDetails
de um recurso permissions
. O campo inheritedFrom
fornece o ID do item de onde 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
É altamente recomendável usar solicitações em lote para modificar várias permissões.
Confira abaixo 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 método
delete()
no recurso
permissions
com os parâmetros de caminho fileId
e
permissionId
definidos para excluir a permissão.
Para itens em "Meu Drive", é possível excluir uma permissão herdada. A exclusão de uma permissão herdada revoga o acesso ao item e aos itens filhos, se houver.
Para itens em um drive compartilhado, as permissões herdadas não podem ser revogadas. Atualize ou exclua a permissão no arquivo ou na pasta pai.
O método delete()
também é usado para excluir permissões aplicadas diretamente a um
arquivo ou pasta de um drive compartilhado.
Mostrar um exemplo
O exemplo de código abaixo mostra como revogar o acesso excluindo um permissionId
. Se a solicitação for concluída, o corpo da resposta estará vazio. Para confirmar que a permissão foi removida, use o método list()
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 arquivos
Quando você trabalha com pessoas em um projeto sensível, talvez queira restringir o acesso delas a determinados arquivos no Drive após um período de tempo. Nos arquivos no Meu Drive, você pode definir uma data de validade para limitar ou remover o acesso.
Para definir a data de validade:
Use o método
create()
no recursopermissions
e defina o campoexpirationTime
(junto com os outros campos obrigatórios). Para mais informações, consulte Criar uma permissão.Use o método
update()
no recursopermissions
e defina o campoexpirationTime
(junto com os outros campos obrigatórios). Para mais informações, consulte Atualizar permissões.
O campo expirationTime
indica quando a permissão expira usando o RFC 3339
de data e hora. Os tempos de expiração têm
as seguintes restrições:
- Elas só podem ser definidas nas permissões de usuários e grupos.
- O horário precisa estar no futuro.
- O horário não pode ser mais de um ano no futuro.
Para mais informações sobre a data de validade, consulte estes artigos:
Temas relacionados
- Gerenciar propostas de acesso pendentes
- Transferir a propriedade de arquivos
- Proteger o conteúdo do arquivo
- Acessar arquivos de drives compartilhados por link usando chaves de recurso
- Papéis e permissões