Como criar e gerenciar listas de controle de acesso (ACLs)

Acessar conceitos

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.

Antes de começar

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:

Console

buckets novos são criados com a ACL predefinida project-private. Se seu bucket precisar de uma permissão diferente, defina uma ACL.

gsutil

Blocos novos são adicionados como project-private. Se seu bucket precisar de uma permissão diferente, defina uma ACL.

API JSON

Por padrão, buckets novos são adicionados como project-private. Se seu bucket precisar de uma permissão diferente, defina uma ACL.

API XML

Blocos 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:

Console

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.

gsutil

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.

API JSON

Por padrão, objetos novos são adicionados com a ACL padrão de objetos do bucket.

API XML

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.

Console

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.

1. Acesse o navegador do Cloud Storage no Console do Cloud.
   Acessar o navegador do Cloud Storage

2. Navegue até o objeto com a ACL que você quer alterar.

3. 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.

4. Clique em Adicionar item.

5. 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.

6. 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.

7. 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.

8. Clique em Save.

Para informações detalhadas sobre erros de operações com falha no navegador do Cloud Storage, consulte Solução de problemas.

gsutil

Use gsutil acl para especificar ACLs:

• Para especificar concessões individuais:

  gsutil acl ch -u USER_EMAIL:PERMISSION gs://BUCKET_NAME

• Para especificar ACLs pré-configuradas:

  gsutil acl set CANNED_ACL_NAME gs://BUCKET_NAME

• Para especificar ACLs no formato JSON:

  gsutil acl set JSON_FILE gs://BUCKET_NAME

  JSON_FILE contém ACLs especificadas no formato JSON.

Amostras de código

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage para C++.

Na amostra a seguir, uma ACL é adicionada a um bucket:

Ver no GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& entity) {
  StatusOr<gcs::BucketAccessControl> patched_acl =
      client.PatchBucketAcl(bucket_name, entity,
                            gcs::BucketAccessControlPatchBuilder().set_role(
                                gcs::BucketAccessControl::ROLE_OWNER()));

  if (!patched_acl) throw std::runtime_error(patched_acl.status().message());
  std::cout << "ACL entry for " << patched_acl->entity() << " in bucket "
            << patched_acl->bucket() << " is now " << *patched_acl << "\n";
}

Na amostra a seguir, uma ACL é adicionada a um objeto:

Ver no GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name, std::string const& entity) {
  StatusOr<gcs::ObjectAccessControl> patched_acl =
      client.CreateObjectAcl(bucket_name, object_name, entity,
                             gcs::ObjectAccessControl::ROLE_OWNER());

  if (!patched_acl) throw std::runtime_error(patched_acl.status().message());
  std::cout << "ACL entry for " << patched_acl->entity() << " in object "
            << patched_acl->object() << " in bucket " << patched_acl->bucket()
            << " is now " << *patched_acl << "\n";
}

C#

Para mais informações, consulte a documentação de referência da API Cloud Storage para C#.

Na amostra a seguir, uma ACL é adicionada a um bucket:

Ver no GitHub Feedback

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;
using System.Collections.Generic;

public class AddBucketOwnerSample
{
    public Bucket AddBucketOwner(
        string bucketName = "your-unique-bucket-name",
        string userEmail = "[e-mail]")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName, new GetBucketOptions { Projection = Projection.Full });

        bucket.Acl ??= new List<BucketAccessControl>();

        bucket.Acl.Add(new BucketAccessControl
        {
            Bucket = bucketName,
            Entity = $"user-{userEmail}",
            Role = "OWNER",
        });
        var updatedBucket = storage.UpdateBucket(bucket);
        Console.WriteLine($"Added user { userEmail } as an owner on bucket { bucketName }.");
        return updatedBucket;
    }
}

Na amostra a seguir, uma ACL é adicionada a um objeto:

Ver no GitHub Feedback

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class AddFileOwnerSample
{
    public Google.Apis.Storage.v1.Data.Object AddFileOwner(
        string bucketName = "your-unique-bucket-name",
        string objectName = "my-file-name",
        string userEmail = "[e-mail]")
    {
        var storage = StorageClient.Create();
        var storageObject = storage.GetObject(bucketName, objectName, new GetObjectOptions
        {
            Projection = Projection.Full
        });

        storageObject.Acl.Add(new ObjectAccessControl
        {
            Bucket = bucketName,
            Entity = $"user-{userEmail}",
            Role = "OWNER",
        });
        var updatedObject = storage.UpdateObject(storageObject);
        Console.WriteLine($"Added user { userEmail} as an owner on file { objectName}.");
        return updatedObject;
    }
}

Go

Para mais informações, consulte a documentação de referência da API Cloud Storage para Go.

Na amostra a seguir, uma ACL é adicionada a um bucket:

Ver no GitHub Feedback

import (
	"context"
	"fmt"

	"cloud.google.com/go/storage"
)

// addBucketOwner adds ACL to the specified bucket.
func addBucketOwner(bucket string, entity storage.ACLEntity) error {
	// bucket := "bucket-name"
	// entity := storage.AllUsers
	role := storage.RoleOwner

	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	acl := client.Bucket(bucket).ACL()
	if err := acl.Set(ctx, entity, role); err != nil {
		return fmt.Errorf("ACLHandle.Set: %v", err)
	}
	return nil
}

Na amostra a seguir, uma ACL é adicionada a um objeto:

Ver no GitHub Feedback

import (
	"context"
	"fmt"

	"cloud.google.com/go/storage"
)

// addFileOwner adds ACL to the specified object.
func addFileOwner(bucket, object string, entity storage.ACLEntity) error {
	// bucket := "bucket-name"
	// object := "object-name"
	// entity := storage.AllUsers
	role := storage.RoleOwner

	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	acl := client.Bucket(bucket).Object(object).ACL()
	if err := acl.Set(ctx, entity, role); err != nil {
		return fmt.Errorf("ACLHandle.Set: %v", err)
	}
	return nil
}

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage para Java.

Na amostra a seguir, uma ACL é adicionada a um bucket:

Ver no GitHub Feedback

Acl acl = storage.createAcl(bucketName, Acl.of(User.ofAllAuthenticatedUsers(), Role.READER));

Na amostra a seguir, uma ACL é adicionada a um objeto:

Ver no GitHub Feedback

BlobId blobId = BlobId.of(bucketName, blobName, blobGeneration);
Acl acl = storage.createAcl(blobId, Acl.of(User.ofAllAuthenticatedUsers(), Role.READER));

Node.js

Para mais informações, consulte a documentação de referência da API Cloud Storage para Node.js.

Na amostra a seguir, uma ACL é adicionada a um bucket:

Ver no GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The email address of the user to add
// const userEmail = 'user-email-to-add';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function addBucketOwner() {
  // Makes the user an owner of the bucket. You can use addAllUsers(),
  // addDomain(), addProject(), addGroup(), and addAllAuthenticatedUsers()
  // to grant access to different types of entities. You can also use "readers"
  // and "writers" to grant different roles.
  await storage.bucket(bucketName).acl.owners.addUser(userEmail);

  console.log(`Added user ${userEmail} as an owner on bucket ${bucketName}.`);
}

addBucketOwner().catch(console.error);

Na amostra a seguir, uma ACL é adicionada a um objeto:

Ver no GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The name of the file to access
// const fileName = 'file.txt';

// The email address of the user to add
// const userEmail = 'user-email-to-add';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function addFileOwner() {
  await storage
    .bucket(bucketName)
    .file(fileName)
    .acl.owners.addUser(userEmail);

  console.log(`Added user ${userEmail} as an owner on file ${fileName}.`);
}

addFileOwner().catch(console.error);

PHP

Para mais informações, consulte a documentação de referência da API Cloud Storage para PHP.

Na amostra a seguir, uma ACL é adicionada a um bucket:

Ver no GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * Add an entity and role to a bucket's ACL.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 * @param string $entity The entity to update access controls for.
 * @param string $role The permissions to add for the specified entity. May
 *        be one of 'OWNER', 'READER', or 'WRITER'.
 * @param array $options
 *
 * @return void
 */
function add_bucket_acl($bucketName, $entity, $role, $options = [])
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $acl = $bucket->acl();
    $acl->add($entity, $role, $options);
    printf('Added %s (%s) to gs://%s ACL' . PHP_EOL, $entity, $role, $bucketName);
}

Na amostra a seguir, uma ACL é adicionada a um objeto:

Ver no GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * Add an entity and role to an object's ACL.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 * @param string $objectName the name of your Cloud Storage object.
 * @param string $entity The entity to update access controls for.
 * @param string $role The permissions to add for the specified entity. May
 *        be one of 'OWNER', 'READER', or 'WRITER'.
 * @param array $options
 *
 * @return void
 */
function add_object_acl($bucketName, $objectName, $entity, $role, $options = [])
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $acl = $object->acl();
    $acl->add($entity, $role, $options);
    printf('Added %s (%s) to gs://%s/%s ACL' . PHP_EOL, $entity, $role, $bucketName, $objectName);
}

Python

Para mais informações, consulte a documentação de referência da API Cloud Storage para Python.

Na amostra a seguir, uma ACL é adicionada a um bucket:

Ver no GitHub Feedback

from google.cloud import storage

def add_bucket_owner(bucket_name, user_email):
    """Adds a user as an owner on the given bucket."""
    # bucket_name = "your-bucket-name"
    # user_email = "[e-mail]"

    storage_client = storage.Client()

    bucket = storage_client.bucket(bucket_name)

    # Reload fetches the current ACL from Cloud Storage.
    bucket.acl.reload()

    # You can also use `group()`, `domain()`, `all_authenticated()` and `all()`
    # to grant access to different types of entities.
    # You can also use `grant_read()` or `grant_write()` to grant different
    # roles.
    bucket.acl.user(user_email).grant_owner()
    bucket.acl.save()

    print(
        "Added user {} as an owner on bucket {}.".format(
            user_email, bucket_name
        )
    )

Na amostra a seguir, uma ACL é adicionada a um objeto:

Ver no GitHub Feedback

from google.cloud import storage

def add_blob_owner(bucket_name, blob_name, user_email):
    """Adds a user as an owner on the given blob."""
    # bucket_name = "your-bucket-name"
    # blob_name = "your-object-name"
    # user_email = "[e-mail]"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)

    # Reload fetches the current ACL from Cloud Storage.
    blob.acl.reload()

    # You can also use `group`, `domain`, `all_authenticated` and `all` to
    # grant access to different types of entities. You can also use
    # `grant_read` or `grant_write` to grant different roles.
    blob.acl.user(user_email).grant_owner()
    blob.acl.save()

    print(
        "Added user {} as an owner on blob {} in bucket {}.".format(
            user_email, blob_name, bucket_name
        )
    )

Ruby

Para mais informações, consulte a documentação de referência da API Cloud Storage para Ruby.

Na amostra a seguir, uma ACL é adicionada a um bucket:

Ver no GitHub Feedback

# The ID of your GCS bucket
# bucket_name = "your-unique-bucket-name"
# email       = "Google Cloud Storage ACL Entity email"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name

bucket.acl.add_owner email

puts "Added OWNER permission for #{email} to #{bucket_name}"

Na amostra a seguir, uma ACL é adicionada a um objeto:

Ver no GitHub Feedback

# The ID of your GCS bucket
# bucket_name = "your-unique-bucket-name"
# file_name   = "Name of a file in the Storage bucket"
# email       = "Google Cloud Storage ACL Entity email"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name
file    = bucket.file file_name

file.acl.add_owner email

puts "Added OWNER permission for #{email} to #{file_name}"

API JSON

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.

"acl": [
{
"kind": "storage#bucketAccessControl",
"id": "example-bucket/project-owners-123412341234",
"selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/project-owners-123412341234",
"bucket": "example-bucket",
"entity": "project-owners-123412341234",
"role": "OWNER",
"projectTeam": {
       "projectNumber": "123412341234",
       "team": "owners"
},
"etag": "CDk="
},
{
"kind": "storage#bucketAccessControl",
"id": "example-bucket/project-editors-123412341234",
"selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/project-editors-123412341234",
"bucket": "example-bucket",
"entity": "project-editors-123412341234",
"role": "OWNER",
"projectTeam": {
     "projectNumber": "123412341234",
     "team": "editors"
},
"etag": "CDk="
},
{
"kind": "storage#bucketAccessControl",
"id": "example-bucket/project-viewers-123412341234",
"selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/project-viewers-123412341234",
"bucket": "example-bucket",
"entity": "project-viewers-123412341234",
"role": "READER",
"projectTeam": {
     "projectNumber": "123412341234",
     "team": "viewers"
},
"etag": "CDk="
},
{
"kind": "storage#bucketAccessControl",
"id": "example-bucket/[e-mail]",
"selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/[e-mail]",
"bucket": "example-bucket",
"entity": "[e-mail]",
"role": "READER",
"email": "[e-mail]",
"etag": "CDk="
},
{
"kind": "storage#bucketAccessControl",
"id": "example-bucket/[e-mail]",
"selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/[e-mail]",
"bucket": "example-bucket",
"entity": "[e-mail]",
"role": "READER",
"email": "[e-mail]",
"etag": "CDk="
},
{
"kind": "storage#bucketAccessControl",
"id": "example-bucket/allUsers",
"selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/allUsers",
"bucket": "example-bucket",
"entity": "allUsers",
"role": "READER",
"etag": "CDk="
},
{
"kind": "storage#bucketAccessControl",
"id": "example-bucket/allAuthenticatedUsers",
"selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/allAuthenticatedUsers",
"bucket": "example-bucket",
"entity": "allAuthenticatedUsers",
"role": "READER",
"etag": "CDk="
}
]

API XML

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.

Elemento	Descrição
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 [e-mail].

No exemplo a seguir, veja entradas diferentes de ACL de bucket:

<?xml version="1.0" encoding="UTF-8"?>
<AccessControlList>
<Owner>
    <ID>00b4903a9721...</ID>
</Owner>
<Entries>
    <Entry>
      <Scope type="GroupById">
        <ID>00b4903a9722...</ID>
      </Scope>
      <Permission>FULL_CONTROL</Permission>
    </Entry>
    <Entry>
      <Scope type="GroupById">
        <ID>00b4903a9723...</ID>
      </Scope>
      <Permission>FULL_CONTROL</Permission>
    </Entry>
    <Entry>
      <Scope type="GroupById">
        <ID>00b4903a9724...</ID>
      </Scope>
      <Permission>READ</Permission>
    </Entry>
    <Entry>
      <Scope type="GroupByDomain">
        <Domain>example.com</Domain>
      </Scope>
      <Permission>READ</Permission>
    </Entry>
    <Entry>
      <Scope type="GroupByEmail">
        <EmailAddress>[e-mail]</EmailAddress>
      </Scope>
      <Permission>READ</Permission>
    </Entry>
    <Entry>
      <Scope type="UserByEmail">
        <EmailAddress>[e-mail]</EmailAddress>
        <Name>jane</Name>
      </Scope>
      <Permission>READ</Permission>
    </Entry>
    <Entry>
      <Scope type="AllUsers"/>
      <Permission>READ</Permission>
    </Entry>
    <Entry>
      <Scope type="AllAuthenticatedUsers"/>
      <Permission>READ</Permission>
    </Entry>
</Entries>
</AccessControlList>

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:

<Entry>
    <Scope type="UserByEmail">
      <EmailAddress>[e-mail]</EmailAddress>
      <Name>Jane</Name>
    </Scope>
    <Permission>FULL_CONTROL</Permission>
</Entry>

Esses elementos <Name> opcionais são preenchidos em duas circunstâncias:

1. 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.

2. 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:

Console

Não é possível aplicar uma ACL predefinida usando o Console do Cloud. Use a gsutil.

gsutil

Use a opção -a com o comando gsutil cp para aplicar a ACL predefinida:

gsutil cp -a PREDEFINED_ACL OBJECT gs://BUCKET_NAME

Por exemplo, para aplicar a ACL predefinida bucket-owner-read durante o upload do objeto paris.jpg para o bucket example-travel-maps:

gsutil cp -a bucket-owner-read paris.jpg gs://example-travel-maps

API JSON

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:

curl -X POST --data-binary @paris.jpg -H "Content-Type: image/jpeg" 

     -H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg"  

     "https://storage.googleapis.com/upload/storage/v1/b/example-travel-maps/o?name=paris.jpg&predefinedAcl=bucketOwnerRead"

A solicitação será semelhante ao exemplo a seguir:

POST /upload/storage/v1/b/example-travel-maps/o?name=paris.jpg&amppredefinedAcl=bucketOwnerRead HTTP/1.1
Host: www.googleapis.com
Content-Type: image/jpeg
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
Content-Length: 12345
Date: Fri, 10 Oct 2014 00:02:38 GMT

API XML

Use o cabeçalho x-goog-acl em uma solicitação Put Object 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:

curl -X PUT --upload-file paris.jpg -H "x-goog-acl: bucket-owner-read" 

     -H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg"  

     https://storage.googleapis.com/example-travel-maps/paris.jpg

A solicitação será semelhante ao exemplo a seguir:

PUT /paris.jpg HTTP/1.1
Host: example-travel-maps.storage.googleapis.com
Date: Thu, 09 Oct 2014 23:06:08 GMT
Content-Length: 12345
Content-Type: image/jpg
x-goog-acl: bucket-owner-read
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
 
12345 bytes in entity body

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.

Console

Não é possível aplicar uma ACL predefinida usando o Console do Cloud. Use a gsutil.

gsutil

Use o comando gsutil acl set para aplicar a ACL predefinida:

gsutil acl set PREDEFINED_ACL gs://BUCKET_NAME/OBJECT_NAME

Por exemplo, para aplicar a ACL predefinida private ao objeto paris.jpg no bucket example-travel-maps:

gsutil acl set private gs://example-travel-maps/paris.jpg

API JSON

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.

Por exemplo, para aplicar a ACL predefinida private ao objeto paris.jpg no bucket example-travel-maps:

curl -X PATCH --data '{"acl": []}'  -H "Content-Type: application/json" 

     -H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg"  

     https://storage.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg?predefinedAcl=private

A solicitação será semelhante ao exemplo a seguir:

PATCH /storage/v1/b/example-travel-maps/o/paris.jpg?predefinedAcl=private HTTP/1.1
Host: www.googleapis.com
Content-Type: application/json
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
Content-Length: 11
Date: Fri, 10 Oct 2014 18:57:59 GMT

API XML

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.

Por exemplo, para aplicar a ACL predefinida private ao objeto paris.jpg no bucket example-travel-maps:

curl -X PUT -H "Content-Length: 0" 

    -H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg" 

    -H "x-goog-acl: private" https://storage.googleapis.com/example-travel-maps/paris.jpg?acl

A solicitação será semelhante ao exemplo a seguir:

PUT /paris.jpg?acl HTTP/1.1
Host: example-travel-maps.storage.googleapis.com
Date: Thu, 09 Oct 2014 23:14:59 GMT
Content-Length: 0
x-goog-acl: private
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
 
empty entity body

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:

Console

Não é possível definir ACLs padrão de objetos usando o Console do Cloud. Use a gsutil.

gsutil

1. Use gsutil defacl para recuperar a ACL padrão de objetos:

   gsutil defacl get gs://BUCKET_NAME

2. Use gsutil defacl ch ou gsutil defacl set para modificar a ACL padrão de objetos.

   Por exemplo, o comando a seguir adiciona [e-mail] à ACL padrão de objetos do bucket example-travel-maps:

   gsutil defacl ch -u [e-mail]:READER gs://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.

Amostras de código

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage para C++.

Na amostra a seguir, uma ACL padrão do objeto é adicionada a um bucket:

Ver no GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& entity, std::string const& role) {
  StatusOr<gcs::ObjectAccessControl> default_object_acl =
      client.CreateDefaultObjectAcl(bucket_name, entity, role);

  if (!default_object_acl) {
    throw std::runtime_error(default_object_acl.status().message());
  }

  std::cout << "Role " << default_object_acl->role()
            << " will be granted default to " << default_object_acl->entity()
            << " on any new object created on bucket "
            << default_object_acl->bucket() << "\n"
            << "Full attributes: " << *default_object_acl << "\n";
}

Na amostra a seguir, uma ACL padrão de objetos é excluída de um bucket:

Ver no GitHub Feedback

namespace gcs = google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& entity) {
  google::cloud::Status status =
      client.DeleteDefaultObjectAcl(bucket_name, entity);

  if (!status.ok()) throw std::runtime_error(status.message());
  std::cout << "Deleted ACL entry for " << entity << " in bucket "
            << bucket_name << "\n";
}

C#

Para mais informações, consulte a documentação de referência da API Cloud Storage para C#.

Na amostra a seguir, a ACL padrão do objeto é impressa em um bucket:

Ver no GitHub Feedback

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;
using System.Collections.Generic;

public class PrintBucketDefaultAclSample
{
    public IEnumerable<ObjectAccessControl> PrintBucketDefaultAcl(string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName, new GetBucketOptions { Projection = Projection.Full });

        foreach (var acl in bucket.DefaultObjectAcl)
        {
            Console.WriteLine($"{acl.Role}:{acl.Entity}");
        }

        return bucket.DefaultObjectAcl;
    }
}

Na amostra a seguir, uma ACL padrão do objeto é adicionada a um bucket:

Ver no GitHub Feedback

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class AddBucketDefaultOwnerSample
{
    public Bucket AddBucketDefaultOwner(
        string bucketName = "your-unique-bucket-name",
        string userEmail = "[e-mail]")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName, new GetBucketOptions { Projection = Projection.Full });

        bucket.DefaultObjectAcl.Add(new ObjectAccessControl
        {
            Bucket = bucketName,
            Entity = $"user-{userEmail}",
            Role = "OWNER",
        });
        var updatedBucket = storage.UpdateBucket(bucket);
        Console.WriteLine($"Added user { userEmail} as a default owner on bucket { bucketName}.");
        return updatedBucket;
    }
}

Na amostra a seguir, uma ACL padrão de objetos é excluída de um bucket:

Ver no GitHub Feedback

using Google.Cloud.Storage.V1;
using System;
using System.Linq;

public class RemoveBucketDefaultOwnerSample
{
    public void RemoveBucketDefaultOwner(
        string bucketName = "your-unique-bucket-name",
        string userEmail = "[e-mail]")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName, new GetBucketOptions { Projection = Projection.Full });
        if (bucket.DefaultObjectAcl == null)
        {
            Console.WriteLine("No default owner to remove");
        }
        else
        {
            bucket.DefaultObjectAcl = bucket.DefaultObjectAcl.Where(acl => !(acl.Entity == $"user-{userEmail}" && acl.Role == "OWNER")).ToList();
            var updatedBucket = storage.UpdateBucket(bucket);
            Console.WriteLine($"Removed user {userEmail} from bucket {bucketName}.");
        }
    }
}

Go

Para mais informações, consulte a documentação de referência da API Cloud Storage para Go.

Na amostra a seguir, uma ACL padrão do objeto é adicionada a um bucket:

Ver no GitHub Feedback

import (
	"context"
	"fmt"

	"cloud.google.com/go/storage"
)

// addBucketDefaultOwner adds default ACL to the specified bucket.
func addBucketDefaultOwner(bucket string, entity storage.ACLEntity) error {
	// bucket := "bucket-name"
	// entity := storage.AllUsers
	role := storage.RoleOwner

	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	acl := client.Bucket(bucket).DefaultObjectACL()
	if err := acl.Set(ctx, entity, role); err != nil {
		return fmt.Errorf("ACLHandle.Set: %v", err)
	}
	return nil
}

Na amostra a seguir, uma ACL padrão de objetos é excluída de um bucket:

Ver no GitHub Feedback

import (
	"context"
	"fmt"

	"cloud.google.com/go/storage"
)

// deleteDefaultBucketACL removes default ACL from a bucket.
func removeBucketDefaultOwner(bucket string, entity storage.ACLEntity) error {
	// bucket := "bucket-name"
	// entity := storage.AllUsers
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	acl := client.Bucket(bucket).DefaultObjectACL()
	if err := acl.Delete(ctx, entity); err != nil {
		return fmt.Errorf("ACLHandle.Delete: %v", err)
	}
	return nil
}

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage para Java.

Na amostra a seguir, uma ACL padrão do objeto é adicionada a um bucket:

Ver no GitHub Feedback

Acl acl =
    storage.createDefaultAcl(bucketName, Acl.of(User.ofAllAuthenticatedUsers(), Role.READER));

Na amostra a seguir, uma ACL padrão de objetos é excluída de um bucket:

Ver no GitHub Feedback

boolean deleted = storage.deleteDefaultAcl(bucketName, User.ofAllAuthenticatedUsers());
if (deleted) {
  // the acl entry was deleted
} else {
  // the acl entry was not found
}

Node.js

Para mais informações, consulte a documentação de referência da API Cloud Storage para Node.js.

Na amostra a seguir, uma ACL padrão do objeto é adicionada a um bucket:

Ver no GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The email address of the user to add
// const userEmail = 'user-email-to-add';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function addBucketDefaultOwner() {
  // Makes the user an owner in the default ACL of the bucket. You can use
  // addAllUsers(), addDomain(), addProject(), addGroup(), and
  // addAllAuthenticatedUsers() to grant access to different types of entities.
  // You can also use "readers" and "writers" to grant different roles.
  await storage.bucket(bucketName).acl.default.owners.addUser(userEmail);

  console.log(`Added user ${userEmail} as an owner on bucket ${bucketName}.`);
}

addBucketDefaultOwner().catch(console.error);

Na amostra a seguir, uma ACL padrão de objetos é excluída de um bucket:

Ver no GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The email address of the user to remove
// const userEmail = 'user-email-to-remove';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function removeBucketDefaultOwner() {
  // Removes the user from the access control list of the bucket. You can use
  // deleteAllUsers(), deleteDomain(), deleteProject(), deleteGroup(), and
  // deleteAllAuthenticatedUsers() to remove access for different types of entities.
  await storage.bucket(bucketName).acl.default.owners.deleteUser(userEmail);

  console.log(`Removed user ${userEmail} from bucket ${bucketName}.`);
}

removeBucketDefaultOwner().catch(console.error);

PHP

Para mais informações, consulte a documentação de referência da API Cloud Storage para PHP.

Na amostra a seguir, uma ACL padrão do objeto é adicionada a um bucket:

Ver no GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * Add an entity and role to a bucket's default ACL.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 * @param string $entity The entity to update access controls for.
 * @param string $role The permissions to add for the specified entity. May
 *        be one of 'OWNER', 'READER', or 'WRITER'.
 * @param array $options
 *
 * @return void
 */
function add_bucket_default_acl($bucketName, $entity, $role, $options = [])
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $acl = $bucket->defaultAcl();
    $acl->add($entity, $role, $options);
    printf('Added %s (%s) to gs://%s default ACL' . PHP_EOL, $entity, $role, $bucketName);
}

Na amostra a seguir, uma ACL padrão de objetos é excluída de um bucket:

Ver no GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * Delete an entity from a bucket's default ACL.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 * @param string $entity the name of the entity to remove from the ACL.
 * @param array $options
 *
 * @return void
 */
function delete_bucket_default_acl($bucketName, $entity, $options = [])
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $acl = $bucket->defaultAcl();
    $acl->delete($entity, $options);
    printf('Deleted %s from gs://%s default ACL' . PHP_EOL, $entity, $bucketName);
}

Python

Para mais informações, consulte a documentação de referência da API Cloud Storage para Python.

Na amostra a seguir, uma ACL padrão do objeto é adicionada a um bucket:

Ver no GitHub Feedback

from google.cloud import storage

def add_bucket_default_owner(bucket_name, user_email):
    """Adds a user as an owner in the given bucket's default object access
    control list."""
    # bucket_name = "your-bucket-name"
    # user_email = "[e-mail]"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)

    # Reload fetches the current ACL from Cloud Storage.
    bucket.acl.reload()

    # You can also use `group`, `domain`, `all_authenticated` and `all` to
    # grant access to different types of entities. You can also use
    # `grant_read` or `grant_write` to grant different roles.
    bucket.default_object_acl.user(user_email).grant_owner()
    bucket.default_object_acl.save()

    print(
        "Added user {} as an owner in the default acl on bucket {}.".format(
            user_email, bucket_name
        )
    )

Na amostra a seguir, uma ACL padrão de objetos é excluída de um bucket:

Ver no GitHub Feedback

from google.cloud import storage

def remove_bucket_default_owner(bucket_name, user_email):
    """Removes a user from the access control list of the given bucket's
    default object access control list."""
    # bucket_name = "your-bucket-name"
    # user_email = "[e-mail]"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)

    # Reload fetches the current ACL from Cloud Storage.
    bucket.acl.reload()

    # You can also use `group`, `domain`, `all_authenticated` and `all` to
    # remove access for different types of entities.
    bucket.default_object_acl.user(user_email).revoke_read()
    bucket.default_object_acl.user(user_email).revoke_write()
    bucket.default_object_acl.user(user_email).revoke_owner()
    bucket.default_object_acl.save()

    print(
        "Removed user {} from the default acl of bucket {}.".format(
            user_email, bucket_name
        )
    )

Ruby

Para mais informações, consulte a documentação de referência da API Cloud Storage para Ruby.

Na amostra a seguir, uma ACL padrão do objeto é adicionada a um bucket:

Ver no GitHub Feedback

# The ID of your GCS bucket
# bucket_name = "your-unique-bucket-name"
# email       = "Google Cloud Storage ACL Entity email"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name

bucket.default_acl.add_owner email

puts "Added default OWNER permission for #{email} to #{bucket_name}"

Na amostra a seguir, uma ACL padrão de objetos é excluída de um bucket:

Ver no GitHub Feedback

# The ID of your GCS bucket
# bucket_name = "your-unique-bucket-name"
# email       = "Google Cloud Storage ACL Entity email"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name

bucket.default_acl.delete email

puts "Removed default ACL permissions for #{email} from #{bucket_name}"

API JSON

1. Recupere a ACL padrão de objetos com uma solicitação GET. Exemplo:

   curl -X GET -H "Authorization: Bearer OAUTH2_TOKEN" 
   
   https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?projection=full

2. 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:

   curl -X PATCH --data @defacls.json -H "Content-Type: application/json" -H "Authorization: Bearer OAUTH2_TOKEN" 
   
   https://storage.googleapis.com/storage/v1/b/example-travel-maps

   Um exemplo de defacls.json:

   {
   "defaultObjectAcl": [
   {
   "email": "[e-mail]",
   "entity": "[e-mail]",
   "role": "READER"
   }
   ]
   }
   

API XML

1. Recupere a ACL padrão de objetos com uma solicitação GET no escopo do bucket e do parâmetro ?defaultObjectAcl. Exemplo:

   curl -X GET -H "Authorization: Bearer OAUTH2_TOKEN" 
   
   https://storage.googleapis.com/BUCKET_NAME?defaultObjectAcl

2. 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:

   curl -X PUT --data-binary @acls.xml -H "Authorization: Bearer OAUTH2_TOKEN" 
   
   http://storage.googleapis.com/BUCKET_NAME?defaultObjectAcl

   Um exemplo de acls.xml:

   <AccessControlList>
   <Entries>
   <Entry>
   <Permission>FULL_CONTROL</Permission>
   <Scope type="GroupByEmail">
   <EmailAddress>[e-mail]</EmailAddress>
   </Scope>
   </Entry>
   </Entries>
   </AccessControlList>

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:

Console

Não é possível definir ACLs padrão de objetos usando o Console do Cloud. Use a gsutil.

gsutil

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:

gsutil defacl set project-private gs://example-travel-maps

API JSON

Use uma solicitação PUT e o parâmetro predefinedAcl.

Por exemplo:

curl -X PUT -H "Content-Length: 0" -H "Authorization: Bearer OAUTH2_TOKEN" 

https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?predefinedAcl=private

API XML

Use uma solicitação PUT no escopo do bucket com o parâmetro ?defaultObjectAcl e o cabeçalho x-goog-acl.

Por exemplo:

curl -X PUT -H "x-goog-acl: project-private" -H "Content-Length: 0" -H "Authorization: Bearer OAUTH2_TOKEN" 

http://storage.googleapis.com/BUCKET_NAME?defaultObjectAcl

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.

Console

Não é possível trabalhar com ACLs padrão de objetos usando o Console do Cloud. Use a gsutil.

gsutil

No exemplo abaixo, o código do projeto é "123412341234". O código do seu projeto será diferente.

[
{
"entity": "project-owners-123412341234",
"projectTeam": {
  "projectNumber": "123412341234",
  "team": "owners"
},
"role": "OWNER"
},
{
"entity": "project-editors-123412341234",
"projectTeam": {
  "projectNumber": "123412341234",
  "team": "editors"
},
"role": "OWNER"
},
{
"entity": "project-viewers-123412341234",
"projectTeam": {
  "projectNumber": "123412341234",
  "team": "viewers"
},
"role": "READER"
}
]

API JSON

No exemplo abaixo, o código do projeto é "123412341234". O código do seu projeto será diferente.

defaultObjectAcl": [
{
"kind": "storage#objectAccessControl",
"entity": "project-owners-123412341234",
"role": "OWNER",
"projectTeam": {
"projectNumber": "123412341234",
"team": "owners"
}
},
{
"kind": "storage#objectAccessControl",
"entity": "project-editors-123412341234",
"role": "OWNER",
"projectTeam": {
"projectNumber": "123412341234",
"team": "editors"
}
},
{
"kind": "storage#objectAccessControl",
"entity": "project-viewers-123412341234",
"role": "READER",
"projectTeam": {
"projectNumber": "123412341234",
"team": "viewers"
}
}
]

API XML

No exemplo abaixo, os IDs de papel do projeto começam com "00b4903a97...". Os IDs do seu projeto serão diferentes.

<?xml version='1.0' encoding='UTF-8'?>
<AccessControlList>
<Entries>
<Entry>
  <Scope type='GroupById'>
    <ID>00b4903a9721...</ID>
  </Scope>
  <Permission>FULL_CONTROL</Permission>
</Entry>
<Entry>
  <Scope type='GroupById'>
    <ID>00b4903a9722...</ID>
  </Scope>
  <Permission>FULL_CONTROL</Permission>
</Entry>
<Entry>
  <Scope type='GroupById'>
    <ID>00b4903a9723...</ID>
  </Scope>
  <Permission>READ</Permission>
</Entry>
</Entries>
</AccessControlList>

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:

Console

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.

1. Acesse o navegador do Cloud Storage no Console do Cloud.
   Acessar o navegador do Cloud Storage

2. Navegue até o objeto com a ACL que você quer visualizar.

3. Selecione Editar permissões no menu suspenso do objeto.

   Será exibida uma caixa de diálogo com as permissões do objeto.

Para informações detalhadas sobre erros de operações com falha no navegador do Cloud Storage, consulte Solução de problemas.

gsutil

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:

gsutil acl get gs://example-travel-maps/paris.jpg

Exemplo de resposta:

[
{
    "entity": "project-owners-123412341234",
    "projectTeam": {
      "projectNumber": "123412341234",
      "team": "owners"
    },
    "role": "OWNER"
},
{
    "entity": "project-editors-123412341234",
    "projectTeam": {
      "projectNumber": "123412341234",
      "team": "editors"
    },
    "role": "OWNER"
},
{
    "entity": "project-viewers-123412341234",
    "projectTeam": {
      "projectNumber": "123412341234",
      "team": "viewers"
    },
    "role": "READER"
},
{
    "email": "[e-mail]",
    "entity": "[e-mail]",
    "role": "READER"
},
{
    "email": "[e-mail]",
    "entity": "[e-mail]",
    "role": "READER"
},
{
    "entity": "allUsers",
    "role": "READER"
},
{
    "entity": "allAuthenticatedUsers",
    "role": "READER"
}
]

Para retornar a ACL de um intervalo:

gsutil acl get gs://BUCKET_NAME

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.

Amostras de código

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage para C++.

Na amostra a seguir, uma ACL de bucket é recebida:

Ver no GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  StatusOr<std::vector<gcs::BucketAccessControl>> items =
      client.ListBucketAcl(bucket_name);

  if (!items) throw std::runtime_error(items.status().message());
  std::cout << "ACLs for bucket=" << bucket_name << "\n";
  for (gcs::BucketAccessControl const& acl : *items) {
    std::cout << acl.role() << ":" << acl.entity() << "\n";
  }
}

Na amostra a seguir, uma ACL de objeto é recebida:

Ver no GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name) {
  StatusOr<std::vector<gcs::ObjectAccessControl>> items =
      client.ListObjectAcl(bucket_name, object_name);

  if (!items) throw std::runtime_error(items.status().message());
  std::cout << "ACLs for object=" << object_name << " in bucket "
            << bucket_name << "\n";
  for (gcs::ObjectAccessControl const& acl : *items) {
    std::cout << acl.role() << ":" << acl.entity() << "\n";
  }
}

C#

Para mais informações, consulte a documentação de referência da API Cloud Storage para C#.

Na amostra a seguir, uma ACL de bucket é recebida:

Ver no GitHub Feedback

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;
using System.Collections.Generic;

public class PrintBucketAclSample
{
    public IEnumerable<BucketAccessControl> PrintBucketAcl(string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName, new GetBucketOptions { Projection = Projection.Full });

        foreach (var acl in bucket.Acl)
        {
            Console.WriteLine($"{acl.Role}:{acl.Entity}");
        }

        return bucket.Acl;
    }
}

Na amostra a seguir, uma ACL de objeto é recebida:

Ver no GitHub Feedback

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;
using System.Collections.Generic;

public class PrintFileAclSample
{
    public IEnumerable<ObjectAccessControl> PrintObjectAcl(
        string bucketName = "your-unique-bucket-name",
        string objectName = "your-object-name")
    {
        var storage = StorageClient.Create();
        var storageObject = storage.GetObject(bucketName, objectName, new GetObjectOptions
        {
            Projection = Projection.Full
        });

        foreach (var acl in storageObject.Acl)
        {
            Console.WriteLine($"{acl.Role}:{acl.Entity}");
        }

        return storageObject.Acl;
    }
}

Go

Para mais informações, consulte a documentação de referência da API Cloud Storage para Go.

Na amostra a seguir, uma ACL de bucket é recebida:

Ver no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/storage"
)

// printBucketACL lists bucket ACL.
func printBucketACL(w io.Writer, bucket string) error {
	// bucket := "bucket-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	rules, err := client.Bucket(bucket).ACL().List(ctx)
	if err != nil {
		return fmt.Errorf("ACLHandle.List: %v", err)
	}
	for _, rule := range rules {
		fmt.Fprintf(w, "ACL rule: %v\n", rule)
	}
	return nil
}

Na amostra a seguir, uma ACL de objeto é recebida:

Ver no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/storage"
)

// printFileACL lists ACL of the specified object.
func printFileACL(w io.Writer, bucket, object string) error {
	// bucket := "bucket-name"
	// object := "object-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	rules, err := client.Bucket(bucket).Object(object).ACL().List(ctx)
	if err != nil {
		return fmt.Errorf("ACLHandle.List: %v", err)
	}
	for _, rule := range rules {
		fmt.Fprintf(w, "ACL rule: %v\n", rule)
	}
	return nil
}

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage para Java.

Na amostra a seguir, uma ACL de bucket é recebida:

Ver no GitHub Feedback

Acl acl = storage.getAcl(bucketName, User.ofAllAuthenticatedUsers());

Na amostra a seguir, uma ACL de objeto é recebida:

Ver no GitHub Feedback

BlobId blobId = BlobId.of(bucketName, blobName, blobGeneration);
Acl acl = storage.getAcl(blobId, User.ofAllAuthenticatedUsers());

Node.js

Para mais informações, consulte a documentação de referência da API Cloud Storage para Node.js.

Na amostra a seguir, uma ACL de bucket é recebida:

Ver no GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function printBucketAcl() {
  // Gets the ACL for the bucket
  const [acls] = await storage.bucket(bucketName).acl.get();

  acls.forEach(acl => {
    console.log(`${acl.role}: ${acl.entity}`);
  });
}
printBucketAcl().catch(console.error);

Na amostra a seguir, uma ACL de objeto é recebida:

Ver no GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The ID of your GCS file
// const fileName = 'your-file-name';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function printFileAcl() {
  // Gets the ACL for the file
  const [acls] = await storage.bucket(bucketName).file(fileName).acl.get();

  acls.forEach(acl => {
    console.log(`${acl.role}: ${acl.entity}`);
  });
}

printFileAcl().catch(console.error);

PHP

Para mais informações, consulte a documentação de referência da API Cloud Storage para PHP.

Na amostra a seguir, uma ACL de bucket é recebida:

Ver no GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * Print all entities and roles for a bucket's ACL.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 *
 * @return Google\Cloud\Storage\Acl the ACL for the Cloud Storage bucket.
 */
function get_bucket_acl($bucketName)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $acl = $bucket->acl();
    foreach ($acl->get() as $item) {
        printf('%s: %s' . PHP_EOL, $item['entity'], $item['role']);
    }
}

Na amostra a seguir, uma ACL de objeto é recebida:

Ver no GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * Print all entities and roles for an object's ACL.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 * @param string $objectName the name of your Cloud Storage object.
 *
 * @return void
 */
function get_object_acl($bucketName, $objectName)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $acl = $object->acl();
    foreach ($acl->get() as $item) {
        printf('%s: %s' . PHP_EOL, $item['entity'], $item['role']);
    }
}

Python

Para mais informações, consulte a documentação de referência da API Cloud Storage para Python.

Na amostra a seguir, uma ACL de bucket é recebida:

Ver no GitHub Feedback

from google.cloud import storage

def print_bucket_acl(bucket_name):
    """Prints out a bucket's access control list."""

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)

    for entry in bucket.acl:
        print("{}: {}".format(entry["role"], entry["entity"]))

Na amostra a seguir, uma ACL de objeto é recebida:

Ver no GitHub Feedback

from google.cloud import storage

def print_blob_acl(bucket_name, blob_name):
    """Prints out a blob's access control list."""

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)

    for entry in blob.acl:
        print("{}: {}".format(entry["role"], entry["entity"]))

Ruby

Para mais informações, consulte a documentação de referência da API Cloud Storage para Ruby.

Na amostra a seguir, uma ACL de bucket é recebida:

Ver no GitHub Feedback

# The ID of your GCS bucket
# bucket_name = "your-unique-bucket-name"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name

puts "ACL for #{bucket_name}:"

bucket.acl.owners.each do |owner|
  puts "OWNER #{owner}"
end

bucket.acl.writers.each do |writer|
  puts "WRITER #{writer}"
end

bucket.acl.readers.each do |reader|
  puts "READER #{reader}"
end

Na amostra a seguir, uma ACL de objeto é recebida:

Ver no GitHub Feedback

# The ID of your GCS bucket
# bucket_name = "your-unique-bucket-name"
# file_name   = "Name of a file in the Storage bucket"
# email       = "Google Cloud Storage ACL Entity email"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name
file    = bucket.file file_name

puts "ACL for #{file_name} in #{bucket_name}:"

file.acl.owners.each do |owner|
  puts "OWNER #{owner}"
end

file.acl.readers.each do |reader|
  puts "READER #{reader}"
end

API JSON

1. Verifique se você tem a permissão OWNER no bucket ou objeto.

2. 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.

Por exemplo, para retornar a ACL do objeto paris.jpg no bucket example-travel-maps:

curl -X GET -H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg" 

 https://storage.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg?projection=full

Você verá uma resposta semelhante a esta:

{
"kind": "storage#object",
"id": "example-travel-maps/paris.jpg/1412805837131000",
"selfLink": "https://www.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg",
"name": "paris.jpg",
"bucket": "example-travel-maps",
...
"acl": [
{
...
"entity": "project-owners-867489160491",
"role": "OWNER",
"projectTeam": {
    "projectNumber": "867489160491",
    "team": "owners"
},
...
},
{
...
"entity": "[e-mail]",
"role": "OWNER",
"email": "[e-mail]",
...
},
{
...
"entity": "[e-mail]",
"role": "READER",
"email": "[e-mail]",
...
}
],
"owner": {
"entity": "[e-mail]"
},
...
}

Você também pode usar o método GET do recurso objectAccessControls para retornar entradas individuais na ACL de um objeto.

API XML

1. Verifique se você tem a permissão FULL_CONTROL no bucket ou objeto.

2. 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.

Por exemplo, para retornar a ACL do objeto paris.jpg no bucket example-travel-maps:

curl -X GET -H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg" 

 https://storage.googleapis.com/example-travel-maps/paris.jpg?acl

Você verá uma resposta semelhante a esta:

<?xml version="1.0" encoding="UTF-8"?>
<AccessControlList>
<Owner>
<ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
<Name>Owner Name</Name>
</Owner>
<Entries>
<Entry>
  <Scope type="UserById">
    <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
    <Name>Name</Name>
  </Scope>
  <Permission>FULL_CONTROL</Permission>
</Entry>
<Entry>
  <Scope type="UserByEmail">
    <EmailAddress>[e-mail]</EmailAddress>
    <Name>Jane</Name>
  </Scope>
  <Permission>FULL_CONTROL</Permission>
</Entry>
<Entry>
  <Scope type="GroupByEmail">
    <EmailAddress>[e-mail]</EmailAddress>
  </Scope>
  <Permission>READ</Permission>
</Entry>
</Entries>
</AccessControlList>

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:

Console

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.

1. Acesse o navegador do Cloud Storage no Console do Cloud.
   Acessar o navegador do Cloud Storage

2. Navegue até o objeto com a ACL que você quer alterar.

3. Selecione Editar permissões no menu suspenso do objeto.

   Será exibida uma caixa de diálogo com as permissões do objeto.

Veja no exemplo a seguir mostra como conceder a permissão OWNER à usuária [e-mail] e a permissão READER aos membros do grupo gs-announce no objeto paris.jpg:

Para informações detalhadas sobre erros de operações com falha no navegador do Cloud Storage, consulte Solução de problemas.

gsutil

1. Defina as ACLs em um arquivo.

2. 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:

gsutil acl set acl.txt gs://example-travel-maps/paris.jpg

O conteúdo de acl.txt é mostrado abaixo. Essas ACLs concedem aos proprietários do projeto 867489160491 e à usuária [e-mail] a permissão OWNER no objeto paris.jpg. Elas também concedem aos membros do grupo gs-announce a permissão READER nesse objeto:

[
{
"entity": "project-owners-867489160491",
"role": "OWNER",
"projectTeam": {
    "projectNumber": "867489160491",
    "team": "owners"
},
},
{
"entity": "[e-mail]",
"email": "[e-mail]",
"role": "OWNER"
},
{
"entity": "[e-mail]",
"email": "[e-mail]",
"role": "READER"
}
]

Além disso, é possível definir a mesma ACL desse objeto para conceder permissões individuais. Por exemplo, para conceder à usuária [e-mail] o acesso READER, use:

gsutil acl ch -u [e-mail]:READ gs://example-travel-maps/paris.jpg

.

Amostras de código

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage para C++.

Na amostra a seguir, uma ACL é removida de um bucket:

Ver no GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& entity) {
  StatusOr<gcs::BucketMetadata> original_metadata =
      client.GetBucketMetadata(bucket_name, gcs::Projection::Full());

  if (!original_metadata) {
    throw std::runtime_error(original_metadata.status().message());
  }

  std::vector<gcs::BucketAccessControl> original_acl =
      original_metadata->acl();
  auto it = std::find_if(original_acl.begin(), original_acl.end(),
                         [entity](const gcs::BucketAccessControl& entry) {
                           return entry.entity() == entity &&
                                  entry.role() ==
                                      gcs::BucketAccessControl::ROLE_OWNER();
                         });

  if (it == original_acl.end()) {
    std::cout << "Could not find entity " << entity
              << " with role OWNER in bucket " << bucket_name << "\n";
    return;
  }

  gcs::BucketAccessControl owner = *it;
  google::cloud::Status status =
      client.DeleteBucketAcl(bucket_name, owner.entity());

  if (!status.ok()) throw std::runtime_error(status.message());
  std::cout << "Deleted ACL entry for " << owner.entity() << " in bucket "
            << bucket_name << "\n";
}

Na amostra a seguir, uma ACL é removida de um objeto:

Ver no GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name, std::string const& entity) {
  StatusOr<gcs::ObjectMetadata> original_metadata = client.GetObjectMetadata(
      bucket_name, object_name, gcs::Projection::Full());

  if (!original_metadata) {
    throw std::runtime_error(original_metadata.status().message());
  }

  std::vector<gcs::ObjectAccessControl> original_acl =
      original_metadata->acl();
  auto it = std::find_if(original_acl.begin(), original_acl.end(),
                         [entity](const gcs::ObjectAccessControl& entry) {
                           return entry.entity() == entity &&
                                  entry.role() ==
                                      gcs::ObjectAccessControl::ROLE_OWNER();
                         });

  if (it == original_acl.end()) {
    std::cout << "Could not find entity " << entity << " for file "
              << object_name << " with role OWNER in bucket " << bucket_name
              << "\n";
    return;
  }

  gcs::ObjectAccessControl owner = *it;
  google::cloud::Status status =
      client.DeleteObjectAcl(bucket_name, object_name, owner.entity());

  if (!status.ok()) throw std::runtime_error(status.message());
  std::cout << "Deleted ACL entry for " << owner.entity() << " for file "
            << object_name << " in bucket " << bucket_name << "\n";
}

C#

Para mais informações, consulte a documentação de referência da API Cloud Storage para C#.

Na amostra a seguir, uma ACL é removida de um bucket:

Ver no GitHub Feedback

using Google.Cloud.Storage.V1;
using System;
using System.Linq;

public class RemoveBucketOwnerSample
{
    public void RemoveBucketOwner(
        string bucketName = "your-unique-bucket-name",
        string userEmail = "[e-mail]")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName, new GetBucketOptions { Projection = Projection.Full });
        if (bucket.Acl == null)
        {
            Console.WriteLine("No owner to remove");
        }
        else
        {
            bucket.Acl = bucket.Acl.Where(acl => !(acl.Entity == $"user-{userEmail}" && acl.Role == "OWNER")).ToList();
            var updatedBucket = storage.UpdateBucket(bucket);
            Console.WriteLine($"Removed user {userEmail} from bucket {bucketName}.");
        }
    }
}

Na amostra a seguir, uma ACL é removida de um objeto:

Ver no GitHub Feedback

using Google.Cloud.Storage.V1;
using System;
using System.Linq;

public class RemoveFileOwnerSample
{
    public void RemoveFileOwner(
        string bucketName = "your-unique-bucket-name",
        string objectName = "your-object-name",
        string userEmail = "[e-mail]")
    {
        var storage = StorageClient.Create();
        var storageObject = storage.GetObject(bucketName, objectName, new GetObjectOptions { Projection = Projection.Full });
        if (storageObject.Acl == null)
        {
            Console.WriteLine("No owner to remove");
        }
        else
        {
            storageObject.Acl = storageObject.Acl.Where((acl) => !(acl.Entity == $"user-{userEmail}" && acl.Role == "OWNER")).ToList();
            var updatedObject = storage.UpdateObject(storageObject);
            Console.WriteLine($"Removed user {userEmail} from file {objectName}.");
        }
    }
}

Go

Para mais informações, consulte a documentação de referência da API Cloud Storage para Go.

Na amostra a seguir, uma ACL é removida de um bucket:

Ver no GitHub Feedback

import (
	"context"
	"fmt"

	"cloud.google.com/go/storage"
)

// removeBucketOwner removes ACL from a bucket.
func removeBucketOwner(bucket string, entity storage.ACLEntity) error {
	// bucket := "bucket-name"
	// entity := storage.AllUsers
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	acl := client.Bucket(bucket).ACL()
	if err := acl.Delete(ctx, entity); err != nil {
		return fmt.Errorf("ACLHandle.Delete: %v", err)
	}
	return nil
}

Na amostra a seguir, uma ACL é removida de um objeto:

Ver no GitHub Feedback

import (
	"context"
	"fmt"

	"cloud.google.com/go/storage"
)

// removeFileOwner removes default ACL from the given object.
func removeFileOwner(bucket, object string, entity storage.ACLEntity) error {
	// bucket := "bucket-name"
	// object := "object-name"
	// entity := storage.AllUsers
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	acl := client.Bucket(bucket).Object(object).ACL()
	if err := acl.Delete(ctx, entity); err != nil {
		return fmt.Errorf("ACLHandle.Delete: %v", err)
	}
	return nil
}

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage para Java.

Na amostra a seguir, uma ACL é removida de um bucket:

Ver no GitHub Feedback

boolean deleted = storage.deleteAcl(bucketName, User.ofAllAuthenticatedUsers());
if (deleted) {
  // the acl entry was deleted
} else {
  // the acl entry was not found
}

Na amostra a seguir, uma ACL é removida de um objeto:

Ver no GitHub Feedback

BlobId blobId = BlobId.of(bucketName, blobName, blobGeneration);
boolean deleted = storage.deleteAcl(blobId, User.ofAllAuthenticatedUsers());
if (deleted) {
  // the acl entry was deleted
} else {
  // the acl entry was not found
}

Node.js

Para mais informações, consulte a documentação de referência da API Cloud Storage para Node.js.

Na amostra a seguir, uma ACL é removida de um bucket:

Ver no GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The email address of the user to remove
// const userEmail = 'user-email-to-remove';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function removeBucketOwner() {
  // Removes the user from the access control list of the bucket. You can use
  // deleteAllUsers(), deleteDomain(), deleteProject(), deleteGroup(), and
  // deleteAllAuthenticatedUsers() to remove access for different types of entities.
  await storage.bucket(bucketName).acl.owners.deleteUser(userEmail);

  console.log(`Removed user ${userEmail} from bucket ${bucketName}.`);
}

removeBucketOwner().catch(console.error);

Na amostra a seguir, uma ACL é removida de um objeto:

Ver no GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The ID of your GCS file
// const fileName = 'your-file-name';

// The email address of the user to remove
// const userEmail = 'user-email-to-remove';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function removeFileOwner() {
  // Removes the user from the access control list of the file. You can use
  // deleteAllUsers(), deleteDomain(), deleteProject(), deleteGroup(), and
  // deleteAllAuthenticatedUsers() to remove access for different types of entities.
  await storage
    .bucket(bucketName)
    .file(fileName)
    .acl.owners.deleteUser(userEmail);

  console.log(`Removed user ${userEmail} from file ${fileName}.`);
}

removeFileOwner().catch(console.error);

PHP

Para mais informações, consulte a documentação de referência da API Cloud Storage para PHP.

Na amostra a seguir, uma ACL é removida de um bucket:

Ver no GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * Delete an entity from a bucket's default ACL.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 * @param string $entity the name of the entity to remove from the ACL.
 * @param array $options
 *
 * @return void
 */
function delete_bucket_acl($bucketName, $entity, $options = [])
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $acl = $bucket->acl();
    $acl->delete($entity, $options);
    printf('Deleted %s from gs://%s ACL' . PHP_EOL, $entity, $bucketName);
}

Na amostra a seguir, uma ACL é removida de um objeto:

Ver no GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * Delete an entity from an object's ACL.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 * @param string $objectName the name of your Cloud Storage object.
 * @param string $entity The entity to update access controls for.
 * @param array $options
 *
 * @return void
 */
function delete_object_acl($bucketName, $objectName, $entity, $options = [])
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $acl = $object->acl();
    $acl->delete($entity, $options);
    printf('Deleted %s from gs://%s/%s ACL' . PHP_EOL, $entity, $bucketName, $objectName);
}

Python

Para mais informações, consulte a documentação de referência da API Cloud Storage para Python.

Na amostra a seguir, uma ACL é removida de um bucket:

Ver no GitHub Feedback

from google.cloud import storage

def remove_bucket_owner(bucket_name, user_email):
    """Removes a user from the access control list of the given bucket."""
    # bucket_name = "your-bucket-name"
    # user_email = "[e-mail]"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)

    # Reload fetches the current ACL from Cloud Storage.
    bucket.acl.reload()

    # You can also use `group`, `domain`, `all_authenticated` and `all` to
    # remove access for different types of entities.
    bucket.acl.user(user_email).revoke_read()
    bucket.acl.user(user_email).revoke_write()
    bucket.acl.user(user_email).revoke_owner()
    bucket.acl.save()

    print("Removed user {} from bucket {}.".format(user_email, bucket_name))

Na amostra a seguir, uma ACL é removida de um objeto:

Ver no GitHub Feedback

from google.cloud import storage

def remove_blob_owner(bucket_name, blob_name, user_email):
    """Removes a user from the access control list of the given blob in the
    given bucket."""
    # bucket_name = "your-bucket-name"
    # blob_name = "your-object-name"
    # user_email = "[e-mail]"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)

    # You can also use `group`, `domain`, `all_authenticated` and `all` to
    # remove access for different types of entities.
    blob.acl.user(user_email).revoke_read()
    blob.acl.user(user_email).revoke_write()
    blob.acl.user(user_email).revoke_owner()
    blob.acl.save()

    print(
        "Removed user {} from blob {} in bucket {}.".format(
            user_email, blob_name, bucket_name
        )
    )

Ruby

Para mais informações, consulte a documentação de referência da API Cloud Storage para Ruby.

Na amostra a seguir, uma ACL é removida de um bucket:

Ver no GitHub Feedback

# project_id  = "Your Google Cloud project ID"
# The ID of your GCS bucket
# bucket_name = "your-unique-bucket-name"
# email       = "Google Cloud Storage ACL Entity email"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name

bucket.acl.delete email

puts "Removed ACL permissions for #{email} from #{bucket_name}"

Na amostra a seguir, uma ACL é removida de um objeto:

Ver no GitHub Feedback

# The ID of your GCS bucket
# bucket_name = "your-unique-bucket-name"
# file_name   = "Name of a file in the Storage bucket"
# email       = "Google Cloud Storage ACL Entity email"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name
file    = bucket.file file_name

file.acl.delete email

puts "Removed ACL permissions for #{email} from #{file_name}"

API JSON

1. Defina as ACLs de um arquivo JSON.

2. 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:

curl -X PATCH --data @acls.json -H "Content-Type: application/json" 

 -H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg" 

 https://storage.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg

Se a ACL conceder aos proprietários do projeto 867489160491 e à usuária [e-mail] 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:

PATCH /storage/v1/b/example-travel-maps/o/paris.jpg HTTP/1.1
Host: www.googleapis.com
Content-Type: application/json
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
Content-Length: 597
Date: Wed, 08 Oct 2014 22:37:58 GMT
{
"acl": [
{
"entity": "project-owners-867489160491",
"role": "OWNER",
"projectTeam": {
    "projectNumber": "867489160491",
    "team": "owners"
},
{
"entity": "[e-mail]",
"role": "OWNER",
"email": "[e-mail]"
},
{
"entity": "[e-mail]",
"role": "READER",
"email": "[e-mail]"
}
]
}

API XML

1. Defina as ACLs em um documento XML.

2. 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:

curl -X PUT --data-binary @acls.xml 

 -H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg" 

 https://storage.googleapis.com/example-travel-maps/paris.jpg?acl

Se a ACL conceder ao usuário [e-mail] 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:

PUT /paris.jpg?acl HTTP/1.1
Host: example-travel-maps.storage.googleapis.com
Date: Sat, 20 Feb 2010 08:31:08 GMT
Content-Length: 589
Content-Type=application/xml
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
 
<?xml version='1.0' encoding='utf-8'?>
<AccessControlList>
<Owner>
<ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
</Owner>
<Entries>
<Entry>
<Permission>FULL_CONTROL</Permission>
<Scope type="UserById">
  <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
</Scope>
</Entry>
<Entry>
<Scope type="UserByEmail">
  <EmailAddress>[e-mail]</EmailAddress>
  <Name>Jane</Name>
</Scope>
<Permission>FULL_CONTROL</Permission>
</Entry>
<Entry>
<Scope type="GroupByEmail">
  <EmailAddress>[e-mail]</EmailAddress>
</Scope>
<Permission>READ</Permission>
</Entry>
</Entries>
</AccessControlList>

A seguir

• Saiba mais sobre as listas de controle de acesso (ACLs).
• Veja como simplificar seu controle de acesso com o acesso uniforme no nível do bucket.