Todos os arquivos, pastas e drives compartilhados do Google Drive têm recursos de
permissões associados. Cada recurso
identifica a permissão para um type
(usuário, grupo, domínio, qualquer pessoa)
e role
específicos, como "comentador" ou "leitor". Por exemplo, um arquivo pode ter uma
permissão que concede acesso somente leitura a um usuário específico (type=user
)
(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 uma lista completa de papéis e as operações permitidas por cada um, consulte Papéis e permissões.
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
estiver definido comoFalse
para o arquivo, o usuário precisará terrole=owner
.Se o usuário com
role=writer
tiver um acesso temporário regido por uma data e hora de validade, ele não vai poder compartilhar o arquivo. Para mais informações, consulte Definir uma data de validade para limitar o acesso ao arquivo.
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 (gerenciado 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 aos itens nos drives compartilhados. É 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
.- Quando a restrição
sharingFoldersRequiresOrganizerPermission
em um drive compartilhado está definida comoFalse
, os usuários comrole=fileOrganizer
podem compartilhar pastas nesse drive compartilhado.
- Quando a restrição
Para gerenciar a associação ao drive compartilhado, o usuário precisa ter
role=organizer
. Somente usuários e grupos podem participar de drives compartilhados.
Defina uma data de validade para limitar o acesso a um arquivo
Ao trabalhar com pessoas em um projeto confidencial, é recomendável restringir o acesso delas a determinados arquivos no Drive após um período. Nos arquivos em "Meu Drive", é possível definir uma data de validade para limitar ou remover o acesso a eles.
Para definir a data de validade, siga estas etapas:
- Use o método
permissions.create
e defina o campopermissions.expirationTime
com os outros campos obrigatórios. Para ver mais informações, consulte Criar uma permissão. - Use o método
permissions.update
e defina o campopermissions.expirationTime
(com os outros campos obrigatórios). Para ver mais informações, consulte Mudar permissões.
O campo expirationTime
indica quando a permissão expira usando a data e hora RFC 3339 (link em inglês). Os prazos de validade têm as seguintes restrições:
- Elas só podem ser definidas para permissões de usuário e grupo.
- A hora 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 os seguintes artigos:
Propagação da permissão
As listas de permissões para uma pasta se propagam para baixo, e todos os arquivos filhos e as pastas herdam as permissões do pai. Sempre que as permissões ou a hierarquia são alteradas, a propagação ocorre de maneira recursiva em todas as pastas aninhadas. Por exemplo, se um arquivo existir em uma pasta e essa pasta for movida para outra pasta, as permissões na nova pasta serão propagadas para o arquivo. Se a nova pasta conceder ao usuário do arquivo um novo papel, como "gravador", ela substituirá o papel antigo.
Por outro lado, se um arquivo herdar role=writer
de uma pasta e for movido para
outra pasta que forneça um papel de "leitor", o arquivo agora herdará
role=reader
.
Não é possível remover as permissões herdadas de um arquivo ou uma pasta em um drive compartilhado. Em vez disso, essas permissões precisam ser ajustadas no pai direto ou indireto de que foram herdadas. As permissões herdadas podem ser removidas dos itens em "Meu Drive" ou "Compartilhados comigo".
Por outro lado, as permissões herdadas podem ser substituídas em um arquivo ou uma pasta no Meu
Drive. Portanto, se um arquivo herdar role=writer
de uma pasta "Meu Drive", você poderá definir role=reader
no arquivo para reduzir o nível de permissão.
Recursos
O recurso Permissions não
determina a capacidade do usuário atual de executar ações em um arquivo ou uma pasta.
Em vez disso, um recurso Files contém um conjunto de
campos capabilities
booleanos usados para indicar se uma ação pode ser
realizada em um arquivo ou uma pasta. A API Google Drive define esses campos com base no recurso de permissões do usuário associado ao arquivo ou pasta.
Por exemplo, quando Alex faz login no seu aplicativo e tenta compartilhar um arquivo, o papel de Alex
é verificado quanto às permissões no arquivo. Se o papel permitir que eles compartilhem um arquivo,
os capabilities
relacionados ao arquivo, como canShare
, serão preenchidos
em relação ao papel. Se Alex quiser compartilhar o arquivo, seu app vai verificar
capabilities
para garantir que canShare
esteja definido como true
.
Para ver um exemplo de como recuperar o arquivo capabilities
, consulte Verificar permissões
do usuário.
Criar uma permissão
Os dois campos a seguir são necessários ao 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 realizar. 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 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 a ela.
Ao criar uma permissão em que type=domain
, você também precisa fornecer um
domain
para vincular um domínio específico
a ela.
Para criar uma permissão:
- Use o método
permissions.create
comfileId
para a pasta ou o arquivo associado. - 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 a seguir 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 ajudam a melhorar a segurança e a privacidade dos dados, além de facilitar o compartilhamento adequado dos usuários. Para mais informações, consulte Sobre públicos-alvo.
Para usar públicos-alvo, faça o seguinte:
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 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 ver como os usuários interagem com públicos-alvo, consulte Experiência do usuário para compartilhamento de link.
Recuperar todas as permissões de um arquivo, uma pasta ou um drive compartilhado
Use o método permissions.list
para
recuperar todas as permissões de um arquivo, pasta ou drive compartilhado.
Mostrar um exemplo
O exemplo de código a seguir 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"
}
]
}
Verificar as permissões do usuário
Quando o app abre um arquivo, ele precisa verificar os recursos desse arquivo e renderizar
a IU 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
precisará ser desativada na interface.
Para saber mais sobre capabilities
, consulte a seção Recursos
acima.
Para conferir os recursos, chame files.get
com
o 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 para um arquivo.
Mostrar um exemplo
O exemplo de código a seguir mostra como verificar as permissões do usuário. A resposta retorna uma lista de recursos que o usuário tem no arquivo. Cada recurso corresponde a uma ação refinada que o usuário pode realizar. Alguns campos são preenchidos apenas 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 } }
Determinar a origem da função em arquivos e pastas do drive compartilhado
Para alterar a função em um arquivo ou uma pasta, você precisa saber a origem dela. Nos drives compartilhados, a origem de um papel pode ser baseada na associação ao drive compartilhado, no papel em uma pasta ou em um arquivo.
Para determinar a origem da função de um drive compartilhado ou dos itens nele, chame permissions.get
com os parâmetros fileId
, permissionId
e fields
definidos no campo permissionDetails
. Para encontrar o permissionId
, use
permissions.list
com a fileId
. Para
buscar o campo permissionDetails
na solicitação permissions.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 a seguir mostra como determinar a origem do papel. A resposta retorna o permissionDetails
de um recurso Permission
. O campo inheritedFrom
fornece o ID do item do qual 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
}
]
}
Mudar permissões
Para mudar as permissões em um arquivo ou uma pasta, mude a função atribuída:
Chame
permissions.update
com opermissionId
da permissão para mudar e ofileId
do arquivo, pasta ou drive compartilhado associado. Para encontrar opermissionId
, usepermissions.list
com afileId
.Na solicitação, identifique o novo
role
.
Você pode conceder permissões em arquivos ou pastas individuais de um drive compartilhado, mesmo que o usuário ou grupo já seja um participante. Por exemplo, Alex tem role=commenter
como parte da associação a 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 assinatura, 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 alterar permissões de comentarista para gravador em um arquivo ou pasta. A resposta retorna uma instância de um recurso Permission
.
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"
}
Revogar acesso a um arquivo ou uma pasta
Para revogar o acesso a um arquivo ou pasta, chame
delete
com o fileId
e o
permissionId
para excluir a permissão.
Para os 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.
No caso de itens em um drive compartilhado, as permissões herdadas não podem ser revogadas. Atualize ou revogue a permissão na pasta ou no arquivo pai.
A operação delete
também é usada para excluir permissões aplicadas diretamente a um
arquivo ou uma pasta de um drive compartilhado.
Mostrar um exemplo
O exemplo de código a seguir mostra como revogar o acesso excluindo um permissionId
. Se a solicitação for concluída, o corpo da resposta estará vazio. Para confirmar se a permissão foi removida, use permissions.list
com o fileId
.
Solicitação
DELETE https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions/PERMISSION_ID
Transferir a propriedade de arquivos para outra conta do Google Workspace na mesma organização
A propriedade dos arquivos em "Meu Drive" pode ser transferida de uma conta do Google Workspace para outra na mesma organização. Os arquivos de um drive compartilhado pertencem à uma organização. Portanto, as transferências de propriedade não estão disponíveis para arquivos e pastas nos drives compartilhados. Os organizadores de um drive compartilhado podem mover itens dele para o "Meu Drive", o que transfere a propriedade para eles.
Para transferir a propriedade de um arquivo em "Meu Drive", siga um destes procedimentos:
Crie uma permissão de arquivo para conceder acesso de proprietário (
role=owner
) a um usuário específico (type=user
).Atualizar a permissão de um arquivo existente com
role=owner
e transferir a propriedade para o usuário especificado (transferOwnership=true
).
Transferir a propriedade de arquivos de uma conta pessoal para outra
A propriedade dos arquivos pode ser transferida de uma conta pessoal para outra. No entanto, o Drive não transfere a propriedade de um arquivo entre duas contas de consumidor até que o novo proprietário em potencial concorde explicitamente com a transferência. Para transferir a propriedade de arquivos de uma conta pessoal para outra:
O proprietário atual inicia uma transferência de propriedade criando ou atualizando a permissão de arquivo do novo proprietário em potencial. A permissão precisa incluir estas configurações:
role=writer
,type=user
ependingOwner=true
. Se o novo proprietário estiver criando uma permissão para o proprietário em potencial, uma notificação por e-mail será enviada a ele indicando que receberá uma solicitação para assumir a propriedade do arquivo.O novo proprietário aceita a solicitação de transferência de propriedade ao criar ou atualizar a permissão do arquivo. A permissão precisa incluir estas configurações:
role=owner
etransferOwnership=true
. Se o novo proprietário estiver criando uma nova permissão, uma notificação por e-mail será enviada para o proprietário anterior indicando que a propriedade foi transferida.
Quando um arquivo é transferido, a função do proprietário anterior é rebaixada para writer
.
Alterar 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.