Todos os arquivos, pastas e drives compartilhados do Google Drive têm recursos
permissions
associados. 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 (type=group
).role=commenter
Para conferir 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 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
for 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 sempre fossetrue
.
- 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 compartilhado.
- Se a restrição
Para gerenciar a associação ao drive compartilhado, o usuário precisa ter
role=organizer
. Somente usuários e grupos podem ser membros de drives compartilhados.
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. Você pode definir uma data de validade para os arquivos no "Meu Drive" para limitar ou remover o acesso a eles.
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 Mudar permissões.
O campo expirationTime
indica quando a permissão expira usando o RFC 3339
de data e hora. Os prazos de validade 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 os seguintes artigos:
Propagação da permissão
As listas de permissões para uma pasta são propagadas para baixo, e todos os arquivos e pastas filhos herdam as permissões da mãe. Sempre que as permissões ou a hierarquia são alteradas, a propagação ocorre de forma recursiva em todos os diretórios aninhados. 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", ele substitui o papel 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 pai direto ou indireto de que 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.
Recursos
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 app e tenta compartilhar um arquivo, o papel dele
é verificado quanto a 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 um exemplo de recuperação do arquivo capabilities
, consulte Verificar permissões
do usuário.
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 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 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
, também é necessário
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 segmentação.
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 conferir como os usuários interagem com os públicos-alvo, consulte Experiência do usuário para compartilhamento de link.
Extrair todas as permissões de um arquivo, pasta ou drive compartilhado
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"
}
]
}
Verificar as permissões do usuário
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 fazer comentários
precisará estar desativada na interface.
Para mais informações sobre capabilities
, consulte a seção
Capabilities.
Para conferir 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 de 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 capability corresponde a uma ação detalhada que um usuário pode realizar. Alguns campos só são preenchidos para itens nos 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 de função dos arquivos e pastas do drive compartilhado
Para alterar o papel em um arquivo ou uma pasta, você precisa saber a origem do papel. Nos drives compartilhados, a origem de um papel pode ser baseada na associação ao drive compartilhado, no papel em uma pasta ou no papel 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 a seguir 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
}
]
}
Alterar permissões
Para mudar as permissões de um arquivo ou uma pasta, mude a função atribuída:
Chame o método
update()
no recursopermissions
com o parâmetro de caminhopermissionId
definido como a permissão a ser alterada 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 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 aquele 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 mudar as permissões de um arquivo ou pasta de comentador 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"
}
Listar e resolver propostas de acesso pendentes
Uma proposta de acesso é uma proposta de um solicitante para um aprovador para conceder a um destinatário acesso a um item do Drive.
Um aprovador pode analisar e realizar ações em todas as propostas de acesso não resolvidas nos arquivos do Drive. Isso significa que você pode acelerar o processo de aprovação fazendo consultas programáticas para propostas de acesso e resolvendo-as. Ele também permite que as propostas sejam visualizadas em conjunto por um aprovador.
A API Drive fornece o
recurso accessproposals
para que você possa visualizar e resolver propostas de acesso pendentes. Os métodos do
recurso accessproposals
funcionam em arquivos, pastas e arquivos em um drive
compartilhado, mas não no drive compartilhado.
Os termos a seguir são específicos para propostas de acesso:
- Solicitante: o usuário que inicia a proposta de acesso a um item do Drive.
- Destinatário: o usuário que recebe as permissões adicionais em um arquivo se a proposta de acesso for concedida. Muitas vezes, o destinatário é o mesmo que o solicitante, mas nem sempre.
- Aprovador: o usuário responsável por aprovar (ou negar) a proposta de acesso. Isso geralmente acontece porque a pessoa é proprietária do documento ou tem permissão para compartilhar o documento.
Listar propostas de acesso pendentes
Para listar todas as propostas de acesso pendentes em um item do Drive, chame o método
list()
no
recurso accessproposals
e inclua o parâmetro de caminho fileId
.
Somente os aprovadores em um arquivo podem listar as propostas pendentes em um arquivo. Um aprovador
é um usuário com a capacidade can_approve_access_proposals
no arquivo. Se o
solicitante não for um aprovador, uma lista vazia será retornada. Para mais informações
sobre capabilities
, consulte a seção Recursos.
O corpo
da resposta
consiste em um objeto
AccessProposal
que representa uma lista de propostas de acesso não resolvidas no arquivo.
O objeto AccessProposal
inclui informações sobre cada proposta, como o
solicitante, o destinatário e a mensagem que o solicitante adicionou. Ele também
inclui um objeto
AccessProposalRoleAndView
que agrupa o role
proposto pelo solicitante com um view
. Como role
é um campo repetido, cada proposta pode ter vários valores. Por exemplo, uma
proposta pode ter um objeto AccessProposalRoleAndView
de role=reader
e
view=published
, além de um objeto AccessProposalRoleAndView
adicional com
apenas o valor role=writer
. Para mais informações, consulte
Visualizações.
Transmita os seguintes parâmetros de consulta para personalizar a paginação ou filtrar propostas de acesso:
pageToken
: um token de página recebido de uma chamada de lista anterior. Informe este token para recuperar a página seguinte.pageSize
: o número máximo de propostas de acesso a serem retornadas por página.
Resolver propostas de acesso pendentes
Para resolver todas as propostas de acesso pendentes em um item do
Drive, chame o método
resolve()
no recurso accessproposals
e inclua os parâmetros de caminho fileId
e proposalId
.
O método resolve()
inclui um parâmetro de consulta action
que denota a
ação a ser realizada na proposta. O objeto
Action
rastreia a mudança de estado da proposta para sabermos se ela está sendo aceita
ou negada.
O método resolve()
também inclui os parâmetros de consulta opcionais de role
e
view
. Os únicos papéis aceitos são writer
, commenter
e reader
. Se o
papel não for especificado, o padrão será reader
. Um parâmetro de consulta opcional
adicional de send_notification
permite enviar uma notificação por e-mail ao
solicitante quando a proposta for aceita ou recusada.
Assim como no método list()
, os usuários que resolvem a proposta precisam ter o
recurso can_approve_access_proposals
no arquivo. Para mais informações
sobre capabilities
, consulte a seção Recursos.
As propostas são resolvidas usando os mesmos padrões listados em Cenários para compartilhar recursos do Drive. Se houver várias propostas para o mesmo usuário, mas com funções diferentes, o seguinte se aplica:
- Se uma proposta for aceita e outra for negada, o papel aceito será aplicado ao item do Drive.
- Se as duas propostas forem aceitas ao mesmo tempo, a proposta com a
permissão mais alta (por exemplo,
role=writer
em vez derole=reader
) será aplicada. A outra proposta de acesso será removida do item.
Depois de enviar uma proposta para o método resolve()
, a ação de compartilhamento será
concluída. O AccessProposal
não é mais retornado pelo método
list()
. Depois que a proposta for aceita, o usuário precisará usar a
coleção permissions
para atualizar
as permissões em um arquivo ou pasta. Para mais informações, consulte a seção Alterar
permissões.
Revogar acesso a um arquivo ou uma pasta
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 revogue 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 uma pasta de 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 se 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
Transferir a propriedade do arquivo para outra conta do Google Workspace na mesma organização
A propriedade dos arquivos no "Meu Drive" pode ser transferida de uma conta do Google Workspace para outra na mesma organização. Uma organização que tem um drive compartilhado é proprietária dos arquivos nele. Portanto, não é possível transferir a propriedade de arquivos e pastas em drives compartilhados. Os organizadores de um drive compartilhado podem mover itens desse drive para o "Meu Drive", o que transfere a propriedade para eles.
Para transferir a propriedade de um arquivo no "Meu Drive", faça o seguinte:
Crie uma permissão de arquivo concedendo acesso de proprietário (
role=owner
) a um usuário específico (type=user
).Atualize a permissão de um arquivo existente com
role=owner
e transfira a propriedade para o usuário especificado (transferOwnership=true
).
Transferir a propriedade de um arquivo de uma conta de consumidor para outra
A propriedade dos arquivos pode ser transferida de uma conta de consumidor para outra. No entanto, o Drive não transfere a propriedade de um arquivo entre as duas contas de consumidor até que o proprietário em potencial consinta explicitamente com a transferência. Para transferir a propriedade de um arquivo de uma conta de consumidor para outra, faça o seguinte:
O proprietário atual inicia uma transferência de propriedade criando ou atualizando a permissão de arquivo do proprietário em potencial. A permissão precisa incluir estas configurações:
role=writer
,type=user
ependingOwner=true
. Se o proprietário atual estiver criando uma permissão para o possível proprietário, uma notificação por e-mail será enviada para o possível proprietário indicando que ele precisa assumir a propriedade do arquivo.O possível proprietário aceita a solicitação de transferência de propriedade criando ou atualizando a permissão do arquivo. A permissão precisa incluir estas configurações:
role=owner
etransferOwnership=true
. Se o proprietário em potencial estiver criando uma nova permissão, uma notificação por e-mail será enviada ao proprietário anterior indicando que a propriedade foi transferida.
Quando um arquivo é transferido, o papel do proprietário anterior é rebaixado para writer
.
Mudar 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
Temas relacionados
- Proteger o conteúdo do arquivo
- Acessar arquivos do Drive compartilhados por link usando chaves de recurso
- Papéis e permissões