Nesta página, você verá como controlar o acesso a buckets e objetos usando listas de controle de acesso (ACLs). As ACLs são um mecanismo que pode ser usado para definir quem tem acesso a buckets e objetos, além do nível de acesso dessas pessoas.
Para saber mais sobre outras maneiras de controlar o acesso a buckets e objetos, leia este documento de visão geral.
Você precisa usar ACLs?
Na maioria dos casos, o gerenciamento de identidade e acesso (IAM, na sigla em inglês) é o método recomendado para controlar o acesso a recursos, porque oferece controle de acesso de nível empresarial em todo o Google Cloud. Ele possibilita que as permissões concedidas a recursos pai, como projetos, sejam herdadas por recursos filhos, como buckets e objetos. Veja guias sobre como trabalhar com o IAM no Cloud Storage em Como utilizar permissões do IAM.
As ACLs podem ser usadas para personalizar o acesso a objetos individuais de um bucket, porque as permissões do IAM são válidas para todos os objetos de um bucket. No entanto, ainda é necessário usar o IAM para qualquer acesso comum a todos os objetos de um bucket, porque isso reduz a necessidade de microgerenciamento.
Cuidado: as permissões podem ser concedidas por ACLs ou por políticas do IAM. Um usuário só precisa da permissão de uma delas para acessar um bucket ou objeto. Em geral, as permissões concedidas por políticas do IAM não aparecem nas ACLs, enquanto as permissões concedidas pelas ACLs não aparecem nas políticas do IAM. As únicas exceções são as ACLs aplicadas diretamente a um bucket e algumas políticas do IAM no nível do bucket, conforme descrito na Relação do IAM com ACLs.
Você precisa definir uma ACL?
Dependendo da permissão que você quer que um bucket ou objeto tenha, talvez não seja necessário definir uma ACL. Os buckets e objetos são criados com ACLs padrão que podem conter a permissão que você quer que o bucket ou objeto tenha.
Use as orientações a seguir para decidir se você precisa definir uma ACL.
Em buckets:
buckets novos são criados com a ACL predefinida project-private. Se seu bucket precisar de uma permissão diferente, defina uma ACL.
Blocos novos são adicionados como project-private. Se seu bucket precisar de uma permissão diferente, defina uma ACL.
Por padrão, buckets novos são adicionados como project-private. Se seu bucket precisar de uma permissão diferente, defina uma ACL.
Conforme dito acima, cada bucket tem uma ACL padrão de objetos, e essa ACL é aplicada a todos os objetos desse bucket que não tenham uma ACL predefinida ou (se estiver usando a API JSON) uma ACL especificada na solicitação. Saiba mais em ACLs de objeto padrão.
Em objetos:
No momento do upload, os objetos recebem as mesmas ACLs que o objeto do bucket, e a pessoa que fez o upload é adicionada à ACL como proprietário. Se o objeto precisar de uma permissão diferente, defina uma ACL.
Objetos novos são adicionados com a ACL padrão de objetos do bucket. Ao copiar um objeto já armazenado na nuvem, é possível modificar esse comportamento com a opção -p.
Por padrão, objetos novos são adicionados com a ACL padrão de objetos do bucket.
Objetos novos são adicionados com a ACL padrão de objetos do bucket.
Qual interface usar?
A seguir há exemplos de como configurar o controle de acesso usando o Console do Google Cloud, a ferramenta de linha de comando gsutil, as bibliotecas de cliente do Cloud Storage e as APIs XML e JSON. Use estas diretrizes para escolher qual usar:
Se você não tem familiaridade com o controle de acesso e quer apenas modificar ACLs para objetos individuais, use o Console do Cloud.
A ferramenta gsutil é adequada para quem não tem muita experiência com controle de acesso e quer modificar ACLs para buckets e objetos.
Quem já tiver experiência com bibliotecas de cliente do Cloud Storage pode usá-las para gerenciar as ACLs.
Para especificar ACLs usando uma API, é necessário ter experiência prévia com solicitações HTTP. É possível usar sua ferramenta ou aplicativo favorito para enviar as solicitações HTTP. Nos exemplos, usamos a ferramenta cURL (em inglês). É possível conseguir tokens de autorização para usar nos exemplos de cURL do OAuth 2.0 Playground (em inglês).
Como definir ACLs
A ferramenta ou API usada para definir e conseguir ACLs determina a sintaxe da ACL usada. As sintaxes de ACL são visualmente diferentes, mas contêm as mesmas informações: entradas que concedem permissões a escopos.
Observação: não é possível usar o Console do Cloud para definir ACLs em buckets. O Console só pode ser usado para definir ACLs em objetos individuais.
Acesse o navegador do Cloud Storage no Console do Cloud.
Navegue até o objeto com a ACL que você quer alterar.
Escolha Editar permissões no menu Mais ações ( ) associado ao objeto.
Será exibida uma caixa de diálogo de permissões semelhante a esta:
Essa captura de tela mostra uma ACL com quatro entradas:
Na primeira entrada, todos os proprietários de um projeto específico (com o número de projeto 867489140601) recebem acesso ou permissão de Proprietário para o objeto.
Na segunda entrada, todos os editores de um projeto específico (com o número de projeto 867489140601) também recebem acesso/permissão de Proprietário para o objeto.
Na terceira entrada, todos os leitores de um projeto específico (um deles com número de projeto 867489140601) recebem acesso/permissão "Leitor" para esse objeto.
Na quarta entrada, o usuário que fez o upload do objeto recebe acesso/permissão "Proprietário" para o objeto. Quem faz o upload do objeto é sempre definido como "Proprietário" e não pode ser removido.
Escolha o tipo de entidade que receberá a permissão.
A Entidade especifica o tipo de coisa que está recebendo a permissão (por exemplo, um usuário ou um grupo). Consulte Escopos de controle de acesso para ver a lista de valores aceitos em Entidade.
Digite um valor em Nome.
O Nome identifica um usuário, grupo ou outro tipo de entidade específico. Consulte Escopos de controle de acesso para ver a lista de valores aceitos em Nome.
Juntos, Entidade e Nome definem quem recebe a permissão.
Selecione um valor para Acesso.
O Acesso especifica a permissão que será definida para o objeto. Consulte Permissões de controle de acesso para ver a lista de valores aceitos em Acesso.
Use gsutil acl para especificar ACLs:
Para especificar concessões individuais:
Para especificar ACLs pré-configuradas:
Para especificar ACLs no formato JSON:
JSON_FILE contém ACLs especificadas no formato JSON.
Na amostra a seguir, uma ACL é adicionada a um bucket:
Na amostra a seguir, uma ACL é adicionada a um objeto:
Ao criar um bucket, é possível especificar a propriedade acl[] em uma solicitação insert. Em um bucket atual, especifique a propriedade acl[] em uma solicitação patch ou solicitação update.
Ao criar um objeto, é possível especificar a propriedade acl[] no corpo da solicitação ou o parâmetro de consulta predefinedAcl em uma solicitação insert. No caso de um objeto atual, especifique a propriedade acl[] ou o parâmetro de consulta predefinedAcl em uma solicitação patch ou update.
Para definições das propriedades de ACL de bucket e objeto, consulte os recursos BucketAccessControls e ObjectAccessControls, respectivamente.
Veja no exemplo a seguir diferentes entradas de ACL de bucket.
Na API XML, as ACLs estão no formato XML. É necessário anexar um documento XML ao corpo das solicitações para alterar ACLs de intervalos e objetos. Quando são obtidas ACLs de intervalos e objetos, é retornado um documento XML. Esse documento contém as entradas individuais da ACL de bucket ou de objeto.
Depois de criar um bucket com uma solicitação PUT Bucket, use uma segunda solicitação PUT Bucket com o parâmetro ?acl para alterar a ACL do bucket.
Depois de fazer upload de um objeto com uma solicitação PUT Object, altere a ACL com outra solicitação PUT usando o parâmetro ?acl ou o cabeçalho de solicitação x-googl-acl.
Use a sintaxe de ACL a seguir com a API XML.
AccessControlList Contêiner para elementos Entries e Owner.
Owner Contêiner para elementos DisplayName e ID. Esse elemento não é necessário para objetos, porque um objeto é sempre propriedade do usuário que fez o upload. Esse elemento é usado quando a sintaxe de ACL do Amazon S3 for usada em um cenário de migração.
Amazon Simple Storage Service™ e Amazon S3™ são marcas registradas da Amazon.com, Inc. ou de afiliadas nos Estados Unidos e/ou em outros países.
ID ID do Google Cloud Storage do proprietário do bucket.
DisplayName Não implementado no momento. O valor é sempre uma string vazia.
Entries Contêiner para nenhum ou mais elementos Entry.
Entry Contêiner para elementos Scope e Permission. É necessário que um Entry contenha apenas um elemento Scope e um Permission.
Scope Contêiner para um elemento ID, EmailAddress ou Domain que define o escopo da ACL. É necessário que esse elemento tenha um atributo type que contém um dos seguintes valores: UserByID, UserByEmail, GroupByID, GroupByEmail, GroupByDomain, AllUsers ou AllAuthenticatedUsers.
ID Identificador do beneficiário quando a entrada de permissão é especificada por ID.
EmailAddress Identificador do e-mail do beneficiário quando a entrada de permissão é especificada por e-mail.
Domain Identificador do domínio do beneficiário quando a entrada de permissão é especificada por domínio.
Name Elemento opcional que pode ser especificado ou adicionado automaticamente, se o escopo for UserByEmail ou GroupByEmail.
Permission Permissão concedida: READ, WRITE ou FULL_CONTROL.
Lembre-se dos pontos a seguir ao trabalhar com ACLs usando a API XML:
Apenas o formato XML descrito acima pode ser usado.
Não é possível definir escopos duplicados.
É possível ter muitas entradas no XML da ACL, mas não entradas com escopos duplicados. Por exemplo, não é possível ter duas entradas com o mesmo elemento de escopo de jane@example.com.
No exemplo a seguir, veja entradas diferentes de ACL de bucket:
Como configurar o elemento Name no XML da ACL
Quando uma ACL é recuperada de um bucket ou objeto, algumas entradas podem ter um elemento <Name> extra anexado. Por exemplo, talvez haja uma entrada semelhante a esta:
Esses elementos <Name> opcionais são preenchidos em duas circunstâncias:
Quando as ACLs de bucket ou objeto incluem <Name> como um elemento.
Ao definir as ACLs, é possível incluir o elemento <Name> com as entradas de ACL. É possível fornecer qualquer valor no elemento <Name>. O Cloud Storage se lembrará desses valores até que a ACL seja removida ou substituída. Isso pode ser útil ao usar identificadores difíceis de serem reconhecidos, como IDs do Google Cloud Storage.
Quando um escopo UserByEmail ou GroupByEmail contém um perfil público do Google.
Se um desses escopos for usado sem um elemento <Name>, o Cloud Storage verificará se o usuário ou o grupo do Google associado ao endereço de e-mail tem um perfil público do Google com um nome público. Nesse caso, o Cloud Storage preencherá automaticamente o elemento <Name> com o nome público.
Como aplicar uma ACL predefinida
Em vez de especificar toda a ACL uma entrada de cada vez (conforme mostrado acima), é possível usar uma ACL predefinida, que aplicará automaticamente várias entradas personalizadas a um cenário específico. É possível aplicar uma ACL predefinida a um bucket ou a um objeto usando a gsutil, a API JSON ou a API XML.
Em novos objetos
Para aplicar uma ACL predefinida a um objeto durante o upload do objeto:
Não é possível aplicar uma ACL predefinida usando o Console do Cloud. Use a gsutil.
Use a opção -a com o comando gsutil cp para aplicar a ACL predefinida:
Por exemplo, para aplicar a ACL predefinida bucket-owner-read durante o upload do objeto paris.jpg para o bucket example-travel-maps:
Use o parâmetro de string de consulta predefinedAcl em uma solicitação insert para aplicar a ACL predefinida.
Por exemplo, para aplicar a ACL predefinida bucketOwnerRead durante o upload do objeto paris.jpg para o bucket example-travel-maps:
A solicitação será semelhante ao exemplo a seguir:
Use o cabeçalho x-goog-acl em uma solicitação Put Object para aplicar a ACL predefinida.
Em buckets ou objetos
Também é possível aplicar uma ACL predefinida a um bucket ou objeto, o que é útil para mudar de uma ACL predefinida para outra ou atualizar as ACLs personalizadas para uma ACL predefinida.
Use o comando gsutil acl set para aplicar a ACL predefinida:
Por exemplo, para aplicar a ACL predefinida private ao objeto paris.jpg no bucket example-travel-maps:
Use o parâmetro de string de consulta predefinedAcl e especifique uma propriedade acl vazia em uma solicitação patch para aplicar a ACL predefinida.
Use o cabeçalho x-goog-acl com o parâmetro de string de consulta acl em uma solicitação Put Object, mas não inclua um documento XML nela.
Como definir ACLs padrão de objetos
Para que não seja necessário definir as ACLs toda vez que criar um novo objeto, é possível definir uma ACL padrão de objetos em um bucket. Depois disso, cada novo objeto adicionado a esse bucket sem uma ACL aplicada explicitamente passará a usar a ACL padrão. Por exemplo, isso pode ser usado para especificar que apenas um determinado grupo de usuários tenha acesso à maioria dos objetos em um determinado bucket. É possível alterar a ACL padrão de objetos e, em seguida, adicionar objetos ao bucket. A ACL padrão de objetos especificada será automaticamente aplicada a esses objetos adicionados, mas é possível atribuir diferentes ACLs a objetos específicos. Nesse caso, a ACL padrão não será aplicada a esses objetos.
Importante: se você alterar a ACL padrão de objetos em um bucket, a alteração poderá levar um tempo para se propagar, e os novos objetos criados no bucket ainda poderão receber a ACL padrão de objetos antiga por um curto período de tempo (consulte "Consistência"). Para garantir que os novos objetos criados no bucket recebam a ACL padrão de objetos atualizada, é necessário aguardar pelo menos 30 segundos entre a alteração da ACL e a criação dos objetos.
Para visualizar e alterar a ACL padrão de objetos de um bucket:
Não é possível definir ACLs padrão de objetos usando o Console do Cloud. Use a gsutil.
Use gsutil defacl para recuperar a ACL padrão de objetos:
Use gsutil defacl ch ou gsutil defacl set para modificar a ACL padrão de objetos.
Por exemplo, o comando a seguir adiciona jane@gmail.com à ACL padrão de objetos do bucket example-travel-maps:
Também é possível especificar a ACL padrão de objetos usando um arquivo. Para mais informações, consulte a ajuda de gsutil defacl.
Na amostra a seguir, uma ACL padrão do objeto é adicionada a um bucket:
Na amostra a seguir, uma ACL padrão de objetos é excluída de um bucket:
Na amostra a seguir, a ACL padrão do objeto é impressa em um bucket:
Recupere a ACL padrão de objetos com uma solicitação GET. Exemplo:
Use uma solicitação patch para substituir a ACL padrão de objetos. Por exemplo, a solicitação a seguir substitui a ACL padrão de objetos por outra especificada em defacls.json no bucket example-travel-maps:
Um exemplo de defacls.json:
Recupere a ACL padrão de objetos com uma solicitação GET no escopo do bucket e do parâmetro ?defaultObjectAcl. Exemplo:
Use uma solicitação PUT no escopo do bucket com o parâmetro ?defaultObjectAcl para substituir a ACL padrão de objetos pela especificada em acls.xml. Por exemplo:
Um exemplo de acls.xml:
A sintaxe das ACLs é discutida em Como definir ACLs. Também é possível especificar uma ACL predefinida como a ACL padrão de objetos.
Para definir uma ACL predefinida como a ACL padrão de objetos em um bucket:
Use o comando gsutil defacl com o nome da ACL predefinida.
Por exemplo, para definir a ACL padrão de objetos como project-private para o bucket example-travel-maps:
Use uma solicitação PUT e o parâmetro predefinedAcl.
Use uma solicitação PUT no escopo do bucket com o parâmetro ?defaultObjectAcl e o cabeçalho x-goog-acl.
ACLs padrão de objetos para um bucket recém-criado:
As ACLs padrão de objetos para um bucket recém-criado são mostradas abaixo. Compare-as com as ACLs padrão de objetos do bucket para ver se as ACLs padrão de objetos do bucket foram modificadas.
Não é possível trabalhar com ACLs padrão de objetos usando o Console do Cloud. Use a gsutil.
No exemplo abaixo, o código do projeto é "123412341234". O código do seu projeto será diferente.
No exemplo abaixo, os IDs de papel do projeto começam com "00b4903a97...". Os IDs do seu projeto serão diferentes.
A ACL padrão de objetos de um bucket recém-criado é equivalente à ACL predefinida projectPrivate.
Como recuperar ACLs
Para a ACL de um bucket ou objeto:
Observação: não é possível usar o Console do Cloud para acessar ACLs nos buckets. O Console só pode ser usado para acessar ACLs em objetos individuais.
Navegue até o objeto com a ACL que você quer visualizar.
Selecione Editar permissões no menu suspenso do objeto.
Será exibida uma caixa de diálogo com as permissões do objeto.
Use gsutil acl get para retornar a ACL de um objeto.
Por exemplo, para retornar a ACL do objeto paris.jpg no bucket example-travel-maps:
Para retornar a ACL de um intervalo:
Quando a gsutil retorna ACLs de buckets e objetos com gsutil acl get, elas estão no mesmo formato JSON que pode ser usado para defini-las. As ACLs no formato JSON usam os nomes de propriedade da API JSON, como entity e role.
Consulte a sintaxe da API JSON para mais informações sobre como interpretar a saída ou executar gsutil help acls.
Na amostra a seguir, uma ACL de bucket é recebida:
Na amostra a seguir, uma ACL de objeto é recebida:
Verifique se você tem a permissão OWNER no bucket ou objeto.
Recupere a ACL do bucket ou do objeto com uma solicitação GET.
A ACL de objetos é retornada no formato JSON, anexada ao corpo da resposta.
Você verá uma resposta semelhante a esta:
Você também pode usar o método GET do recurso objectAccessControls para retornar entradas individuais na ACL de um objeto.
Verifique se você tem a permissão FULL_CONTROL no bucket ou objeto.
Recupere a ACL do bucket ou objeto usando o parâmetro de string de consulta acl em uma solicitação GET Object.
As ACLs são descritas em XML, anexadas ao corpo da resposta.
Também é possível usar o método GET em JSON do recurso ObjectAccessControls para retornar uma entrada de ACL específica.
Cuidado: as ACLs funcionam de maneira independente das permissões do IAM. É possível usar esses dois métodos de controle de acesso para personalizar as permissões. No entanto, se as permissões do IAM forem usadas para conceder acesso a buckets e objetos, essas permissões não aparecerão nas ACLs de buckets ou objetos individuais, exceto para papéis legacyBucket.
Como alterar ACLs
Para alterar a ACL de um objeto ou bucket:
Observação: não é possível usar o Console do Cloud para alterar ACLs em buckets. O Console só pode ser usado para alterar ACLs em objetos individuais.
Veja no exemplo a seguir mostra como conceder a permissão OWNER à usuária jane@gmail.com e a permissão READER aos membros do grupo gs-announce no objeto paris.jpg:
Defina as ACLs em um arquivo.
Transmita o arquivo de ACLs para gsutil acl set e especifique para que objeto as ACLs serão definidas.
Por exemplo, para aplicar as ACLs do arquivo acls.txt em um objeto chamado paris.jpg no bucket example-travel-maps:
O conteúdo de acl.txt é mostrado abaixo. Essas ACLs concedem aos proprietários do projeto 867489160491 e à usuária jane@gmail.com a permissão OWNER no objeto paris.jpg. Elas também concedem aos membros do grupo gs-announce a permissão READER nesse objeto:
Além disso, é possível definir a mesma ACL desse objeto para conceder permissões individuais. Por exemplo, para conceder à usuária jane@gmail.com o acesso READER, use:
Na amostra a seguir, uma ACL é removida de um bucket:
Na amostra a seguir, uma ACL é removida de um objeto:
Defina as ACLs de um arquivo JSON.
Envie uma solicitação patch com o arquivo JSON e especifique o objeto no qual serão definidas as ACLs.
Por exemplo, o comando cURL a seguir aplica um payload JSON do documento acls.json a um objeto chamado paris.jpg no bucket example-travel-maps:
Se a ACL conceder aos proprietários do projeto 867489160491 e à usuária jane@gmail.com a permissão OWNER, além de conceder aos membros do grupo gs-announce a permissão READER, a solicitação será semelhante ao exemplo a seguir:
Defina as ACLs em um documento XML.
Envie uma solicitação PUT Object usando o parâmetro de string de consulta acl e o documento XML correspondente.
O comando cURL a seguir aplica um payload XML do documento acls.xml a um objeto chamado paris.jpg no bucket example-travel-maps:
Se a ACL conceder ao usuário jane@gmail.com a permissão FULL_CONTROL e aos membros do grupo gs-announce a permissão READ, a solicitação será semelhante ao exemplo a seguir: