Criar e gerenciar listas de controle de acesso (ACLs)

Visão geral

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.

Consulte Visão geral da ACL para saber se é necessário usar ACLs para controlar o acesso aos recursos.

Funções exigidas

Para receber as permissões necessárias para criar e gerenciar ACLs, solicite ao administrador o papel do IAM de Administrador do Storage (roles/storage.admin) no bucket que contém os objetos desejados. para criar e gerenciar ACLs.

Esse papel predefinido contém as permissões necessárias para criar e gerenciar ACLs. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

• storage.buckets.get
• storage.buckets.list
• Essa permissão é necessária apenas para usar o console do Google Cloud para realizar as tarefas nesta página.
• storage.buckets.setIamPolicy
• storage.buckets.update
• storage.objects.get
• storage.objects.getIamPolicy
• storage.objects.setIamPolicy
• storage.objects.update

Também é possível receber essas permissões com funções personalizadas.

Para informações sobre como conceder papéis nos buckets, consulte Usar o IAM com buckets.

Definir ou modificar ACLs

Console

Observação: não é possível usar o console do Google Cloud para definir ou modificar ACLs em buckets. O console do Google Cloud só pode ser usado para definir ou modificar ACLs em objetos individuais.

1. Acesse o navegador do Cloud Storage no console do Google Cloud.
   Acessar o navegador do Cloud Storage

2. Na lista de buckets, clique no nome do bucket que contém o objeto com a ACL que você quer modificar.

3. Clique no nome do objeto para que você quer definir ou modificar ACLs.

4. Clique em Editar acesso.

   Uma caixa de diálogo de permissão com a ACL atual do objeto é aberta.

5. Clique em + Adicionar entrada.

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

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

8. Selecione um valor para Acesso.

   O Acesso especifica a permissão que será definida para o objeto. Consulte Permissões de controle de acessopara ver a lista de valores aceitos em Acesso.

9. Clique em Salvar.

Para saber como acessar informações detalhadas de erro sobre operações do Cloud Storage com falha no console do Google Cloud, consulte Solução de problemas.

Linha de comando

Para adicionar, modificar ou remover uma concessão individual em um objeto, use o comando objects update com a flag relevante:

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME FLAG

Em que:

• BUCKET_NAME é o nome do bucket que contém o objeto a que a modificação se aplica. Por exemplo, example-travel-maps.

• OBJECT_NAME é o nome do objeto ao qual a modificação se aplica. Por exemplo, paris.jpg.

• FLAG é um destes:

  • --add-acl-grant, com a concessão que você quer adicionar ou modificar. Por exemplo, --add-acl-grant=entity=[e-mail],role=READER.

  • --remove-acl-grant, com a entidade cujo acesso você quer remover. Por exemplo, --remove-acl-grant=[e-mail].

Para substituir todas as ACLs de um objeto:

1. Defina as ACLs em um arquivo no formato JSON ou YAML.

2. Use o comando objects update com a flag --acl-file:

   gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --acl-file=FILE_LOCATION

   Em que:

   • BUCKET_NAME é o nome do bucket que contém o objeto a que as ACLs se aplicam. Por exemplo, example-travel-maps.

   • OBJECT_NAME é o nome do objeto ao qual as ACLs se aplicam. Por exemplo, paris.jpg.

   • FILE_LOCATION é o caminho local para o arquivo que contém as ACLs definidas. Por exemplo, Desktop/acls.json.

O conteúdo de um exemplo de arquivo ACLs é 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"
  }
]

Bibliotecas de cliente

C++

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

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::move(patched_acl).status();
  std::cout << "ACL entry for " << patched_acl->entity() << " in object "
            << patched_acl->object() << " in bucket " << patched_acl->bucket()
            << " is now " << *patched_acl << "\n";
}

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

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::move(original_metadata).status();

  std::vector<gcs::ObjectAccessControl> original_acl =
      original_metadata->acl();
  auto it = std::find_if(original_acl.begin(), original_acl.end(),
                         [entity](gcs::ObjectAccessControl const& 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 C#.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

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;
    }
}

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

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

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: %w", 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: %w", err)
	}
	return nil
}

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

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: %w", err)
	}
	defer client.Close()

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

Java

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

import com.google.cloud.storage.Acl;
import com.google.cloud.storage.Acl.Role;
import com.google.cloud.storage.Acl.User;
import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class AddFileOwner {

  public static void addFileOwner(
      String projectId, String bucketName, String userEmail, String blobName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // Email of the user you wish to add as a file owner
    // String userEmail = "[e-mail]"

    // The name of the blob/file that you wish to modify permissions on
    // String blobName = "your-blob-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Blob blob = storage.get(BlobId.of(bucketName, blobName));
    Acl newOwner = Acl.of(new User(userEmail), Role.OWNER);

    blob.createAcl(newOwner);
    System.out.println(
        "Added user "
            + userEmail
            + " as an owner on file "
            + blobName
            + " in bucket "
            + bucketName);
  }
}

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

import com.google.cloud.storage.Acl.User;
import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class RemoveFileOwner {

  public static void removeFileOwner(
      String projectId, String bucketName, String userEmail, String blobName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // Email of the user you wish to remove as a file owner
    // String userEmail = "[e-mail]"

    // The name of the blob/file that you wish to modify permissions on
    // String blobName = "your-blob-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Blob blob = storage.get(BlobId.of(bucketName, blobName));
    User ownerToRemove = new User(userEmail);

    boolean success = blob.deleteAcl(ownerToRemove);
    if (success) {
      System.out.println(
          "Removed user "
              + userEmail
              + " as an owner on file "
              + blobName
              + " in bucket "
              + bucketName);
    } else {
      System.out.println("User " + userEmail + " was not found");
    }
  }
}

Node.js

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

/**
 * 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);

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

/**
 * 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 PHP.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

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.
 *        (e.g. 'my-bucket')
 * @param string $objectName The name of your Cloud Storage object.
 *        (e.g. 'my-object')
 * @param string $entity The entity for which to update access controls.
 *        (e.g. '[e-mail]')
 * @param string $role The permissions to add for the specified entity.
 *        (e.g. 'OWNER')
 */
function add_object_acl(string $bucketName, string $objectName, string $entity, string $role): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $acl = $object->acl();
    $acl->add($entity, $role);
    printf('Added %s (%s) to gs://%s/%s ACL' . PHP_EOL, $entity, $role, $bucketName, $objectName);
}

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

use Google\Cloud\Storage\StorageClient;

/**
 * Delete an entity from an object's ACL.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $objectName The name of your Cloud Storage object.
 *        (e.g. 'my-object')
 * @param string $entity The entity for which to update access controls.
 *        (e.g. '[e-mail]')
 */
function delete_object_acl(string $bucketName, string $objectName, string $entity): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $acl = $object->acl();
    $acl->delete($entity);
    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 Python.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

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

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

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(
        f"Removed user {user_email} from blob {blob_name} in bucket {bucket_name}."
    )

Ruby

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

# 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}"

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

# 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}"

APIs REST

API JSON

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 a definição da propriedade da ACL de objeto, consulte o recurso ObjectAccessControls.

1. Defina as ACLs de um arquivo JSON.

   Por exemplo, se a Access Control List conceder aos proprietários do projeto 867489160491 e ao usuário [e-mail] a permissão OWNER, bem como conceder aos membros do grupo gs-announce a permissão READER, você terá um arquivo chamado acls.json com o seguinte conteúdo:

   {
   "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]"
     }
   ]
   }
   

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 $(gcloud auth print-access-token)" \
    https://storage.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg

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.

Por exemplo, 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 $(gcloud auth print-access-token)" \
    https://storage.googleapis.com/example-travel-maps/paris.jpg?acl

Use a sintaxe de ACL a seguir com o documento 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 Cloud Storage do proprietário do bucket.
DisplayName	Não implementado. O valor é sempre uma string vazia.
Entries	Contêiner para nenhum ou mais elementos Entry.
Entry	Contêiner para elementos Scope e Permission. Um Entry precisa conter apenas um elemento Scope e um Permission.
Scope	Contêiner para um elemento ID, EmailAddress ou Domain que define o escopo da ACL. Esse elemento precisa ter um atributo type que contenha 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 do 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="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>FULL_CONTROL</Permission>
    </Entry>
    <Entry>
      <Scope type="AllUsers"/>
      <Permission>READ</Permission>
    </Entry>
    <Entry>
      <Scope type="AllAuthenticatedUsers"/>
      <Permission>READ</Permission>
    </Entry>
  </Entries>
</AccessControlList>

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.

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.

Aplicar uma ACL predefinida

Em vez de especificar uma entrada de cada vez em toda a ACL como 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 Google Cloud CLI, a API JSON ou a API XML.

Em objetos novos

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 Google Cloud. Use gcloud storage, em vez disso.

Linha de comando

Use o comando gcloud storage cp com a flag --predefined-acl:

gcloud storage cp OBJECT gs://BUCKET_NAME --predefined-acl=PREDEFINED_ACL

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

gcloud storage cp paris.jpg gs://example-travel-maps --predefined-acl=bucketOwnerRead

APIs REST

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 $(gcloud auth print-access-token)"  \
    "https://storage.googleapis.com/upload/storage/v1/b/example-travel-maps/o?name=paris.jpg&predefinedAcl=bucketOwnerRead"

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 $(gcloud auth print-access-token)"  \
    https://storage.googleapis.com/example-travel-maps/paris.jpg

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 Google Cloud. Use gcloud storage, em vez disso.

Linha de comando

Use o comando objects update com a flag --predefined-acl:

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --predefined-acl=PREDEFINED_ACL_NAME

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

gcloud storage objects update gs://example-travel-maps/paris.jpg --predefined-acl=private

APIs REST

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 $(gcloud auth print-access-token)"  \
    https://storage.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg?predefinedAcl=private

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 $(gcloud auth print-access-token)" \
    -H "x-goog-acl: private" \
    https://storage.googleapis.com/example-travel-maps/paris.jpg?acl

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 Google Cloud. Use gcloud storage, em vez disso.

Linha de comando

1. Use o comando buckets describe com a flag --format para recuperar a ACL padrão de objetos do bucket:

   gcloud storage buckets describe gs://BUCKET_NAME --format="default(default_acl)"

   Em que BUCKET_NAME é o nome do bucket com a ACL de objeto padrão que você quer visualizar. Por exemplo, my-bucket.

2. Use o comando buckets update com a flag desejada para modificar a ACL padrão de objetos do bucket:

   gcloud storage buckets update gs://BUCKET_NAME FLAG

   Em que:

   • BUCKET_NAME é o nome do bucket com a ACL de objeto padrão que você quer modificar. Por exemplo, my-bucket.

   • FLAG é um destes:

     • --add-default-object-acl-grant e uma concessão que você quer adicionar à ACL padrão de objetos do bucket.

     • --default-object-acl-file e o caminho para um arquivo local que define uma nova ACL de objeto padrão para o bucket.

     • --predefined-default-object-acl e o nome de uma ACL de objeto predefinida pela qual você quer substituir a ACL atual padrão de objetos do bucket.

     • --remove-default-object-acl-grant e uma entidade que você quer remover da ACL padrão de objetos do bucket.

Bibliotecas de cliente

C++

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

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::move(default_object_acl).status();

  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:

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

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:

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:

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

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: %w", err)
	}
	defer client.Close()

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

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

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: %w", err)
	}
	defer client.Close()

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

Java

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

import com.google.cloud.storage.Acl;
import com.google.cloud.storage.Acl.Role;
import com.google.cloud.storage.Acl.User;
import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class AddBucketDefaultOwner {

  public static void addBucketDefaultOwner(String bucketName, String userEmail) {

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The email of the user you wish to add as a default owner
    // String userEmail = "[e-mail]"

    Storage storage = StorageOptions.newBuilder().build().getService();
    Bucket bucket = storage.get(bucketName);
    Acl newDefaultOwner = Acl.of(new User(userEmail), Role.OWNER);

    bucket.createDefaultAcl(newDefaultOwner);
    System.out.println("Added user " + userEmail + " as an owner on " + bucketName);
  }
}

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

import com.google.cloud.storage.Acl.User;
import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class RemoveBucketDefaultOwner {

  public static void removeBucketDefaultOwner(String bucketName, String userEmail) {

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The email of the user you wish to remove as a default owner
    // String userEmail = "[e-mail]"

    Storage storage = StorageOptions.newBuilder().build().getService();
    Bucket bucket = storage.get(bucketName);
    User userToRemove = new User(userEmail);

    boolean success = bucket.deleteDefaultAcl(userToRemove);
    if (success) {
      System.out.println("Removed user " + userEmail + " as an owner on " + bucketName);
    } else {
      System.out.println("User " + userEmail + " was not found");
    }
  }
}

Node.js

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

/**
 * 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:

/**
 * 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 PHP.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

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.
 *        (e.g. 'my-bucket')
 * @param string $entity The entity for which to update access controls.
 *        (e.g. '[e-mail]')
 * @param string $role The permissions to add for the specified entity.
 *        (e.g. 'OWNER')
 */
function add_bucket_default_acl(string $bucketName, string $entity, string $role): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $acl = $bucket->defaultAcl();
    $acl->add($entity, $role);
    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:

use Google\Cloud\Storage\StorageClient;

/**
 * Delete an entity from a bucket's default ACL.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $entity The entity for which to update access controls.
 *        (e.g. '[e-mail]')
 */
function delete_bucket_default_acl(string $bucketName, string $entity): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $acl = $bucket->defaultAcl();
    $acl->delete($entity);
    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 Python.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

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:

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(
        f"Removed user {user_email} from the default acl of bucket {bucket_name}."
    )

Ruby

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

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

# 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}"

APIs REST

API JSON

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

   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-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 $(gcloud auth print-access-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. Por exemplo:

   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-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 $(gcloud auth print-access-token)" \
       http://storage.googleapis.com/BUCKET_NAME?defaultObjectAcl
   

   Um exemplo de acls.xml:

   <AccessControlList>
     <Entries>
       <Entry>
         <Permission>FULL_CONTROL</Permission>
         <Scope type="UserByEmail">
           <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 Google Cloud. Use gcloud storage, em vez disso.

Linha de comando

Use o comando buckets update com a flag --predefined-default-object-acl:

gcloud storage buckets update gs://BUCKET_NAME --predefined-default-object-acl=PREDEFINED_ACL

Em que:

• BUCKET_NAME é o nome do bucket com a ACL de objeto padrão que você quer modificar. Por exemplo, my-bucket.

• PREDEFINED_ACL é o nome de uma ACL predefinida válida. Por exemplo, projectPrivate.

APIs REST

API JSON

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

Por exemplo:

curl -X PUT -H "Content-Length: 0" -H "Authorization: Bearer $(gcloud auth print-access-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 $(gcloud auth print-access-token)" \
    http://storage.googleapis.com/BUCKET_NAME?defaultObjectAcl

Access Control Lists de objetos padrão para buckets recém-criados:

Os exemplos a seguir mostram as Access Control Lists de objetos padrão que se aplicam automaticamente aos buckets recém-criados ao especificar as próprias Access Control Lists de objetos padrão como parte da solicitação. Para ver se as Access Control Lists de objetos padrão do bucket foram alteradas, compare as Access Control Lists de objetos padrão atuais do bucket com os exemplos abaixo.

Console

Não é possível trabalhar com ACLs padrão de objetos usando o console do Google Cloud. Use gcloud storage.

Linha de comando

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

defaultObjectAcl:
– entity: project-owners-123412341234
  etag: CAE=
  kind: storage#objectAccessControl
  projectTeam:
    projectNumber: '123412341234'
    team: owners
  role: OWNER
– entity: project-editors-123412341234
  etag: CAE=
  kind: storage#objectAccessControl
  projectTeam:
    projectNumber: '123412341234'
    team: editors
  role: OWNER
– entity: project-viewers-123412341234
  etag: CAE=
  kind: storage#objectAccessControl
  projectTeam:
    projectNumber: '123412341234'
    team: viewers
  role: READER

APIs REST

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 códigos de papel do projeto começam com "00b4903a97...". Os códigos 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 acessar a ACL de um recurso existente:

Console

Observação: não é possível usar o console do Google 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 Google Cloud.
   Acessar o navegador do Cloud Storage

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

3. Selecione Editar acesso no menu suspenso do objeto.

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

Para saber como acessar informações detalhadas de erro sobre operações do Cloud Storage com falha no console do Google Cloud, consulte Solução de problemas.

Linha de comando

1. Use o comando objects describe com a flag --format para recuperar a ACL de um objeto:

   gcloud storage objects describe gs://BUCKET_NAME/OBJECT_NAME --format="default(acl)"

   Em que:

   • BUCKET_NAME é o nome do bucket que contém o objeto com a ACL que você quer visualizar. Por exemplo, my-bucket.

   • OBJECT_NAME é o nome do objeto com a ACL que você quer visualizar. Por exemplo, paris.jpg.

Bibliotecas de cliente

C++

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

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::move(items).status();
  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 C#.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

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: %w", err)
	}
	defer client.Close()

	rules, err := client.Bucket(bucket).Object(object).ACL().List(ctx)
	if err != nil {
		return fmt.Errorf("ACLHandle.List: %w", 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 Java.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

import com.google.cloud.storage.Acl;
import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.List;

public class PrintFileAcl {

  public static void printFileAcl(String bucketName, String blobName) {

    // The ID to give your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The name of the blob/file that you wish to view Acls of
    // String blobName = "your-blob-name";

    Storage storage = StorageOptions.newBuilder().build().getService();
    Blob blob = storage.get(BlobId.of(bucketName, blobName));
    List<Acl> blobAcls = blob.getAcl();

    for (Acl acl : blobAcls) {

      // This will give you the role.
      // See https://cloud.google.com/storage/docs/access-control/lists#permissions
      String role = acl.getRole().name();

      // This will give you the Entity type (i.e. User, Group, Project etc.)
      // See https://cloud.google.com/storage/docs/access-control/lists#scopes
      String entityType = acl.getEntity().getType().name();

      System.out.printf("%s: %s %n", role, entityType);
    }
  }
}

Node.js

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

/**
 * 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 PHP.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

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.
 *        (e.g. 'my-bucket')
 * @param string $objectName The name of your Cloud Storage object.
 *        (e.g. 'my-object')
 */
function get_object_acl(string $bucketName, string $objectName): void
{
    $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 Python.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

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(f"{entry['role']}: {entry['entity']}")

Ruby

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

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

# 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

APIs REST

API JSON

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

2. Recupere a ACL 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 $(gcloud auth print-access-token)" \
    https://storage.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg?projection=full

Será exibida uma resposta semelhante a:

{
  "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 $(gcloud auth print-access-token)" \
    https://storage.googleapis.com/example-travel-maps/paris.jpg?acl

Será exibida uma resposta semelhante a:

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

A seguir

• Saiba mais sobre as ACLs.
• Veja como simplificar o controle de acesso com o acesso uniforme no nível do bucket.
• Saiba mais sobre as práticas recomendadas para o uso de ACLs.