Se usó la API de Cloud Translation para traducir esta página.

Crear y administrar Listas de control de acceso (LCA)

En esta página, se describe cómo controlar el acceso a depósitos y objetos con Listas de control de acceso (LCA). Las LCA son un mecanismo que puedes usar para determinar quién tiene acceso a tus depósitos y objetos y qué nivel de acceso tienen.

Consulta la descripción general de LCA para obtener más información sobre si debes usar las LCA para controlar el acceso a tus recursos.

Roles obligatorios

Para obtener los permisos que te permitan crear y administrar las LCA, pídele a tu administrador que te otorgue el rol de IAM de administrador de almacenamiento (roles/storage.admin) en el bucket que contiene los objetos para los que quieres crear y administrar las LCA.

Este rol predefinido contiene los permisos necesarios para crear y administrar las LCA. Para ver los permisos exactos que son necesarios, expande la sección Permisos necesarios:

Permisos necesarios

storage.buckets.get
storage.buckets.list

Este permiso solo es necesario para usar la consola de Google Cloud para hacer la tarea en esta página.

storage.buckets.setIamPolicy
storage.buckets.update
storage.objects.get
storage.objects.getIamPolicy
storage.objects.setIamPolicy
storage.objects.update

También puedes obtener estos permisos con roles personalizados.

Para obtener más información sobre cómo otorgar roles en los buckets, consulta Usa IAM con buckets.

Establece o modifica las LCA

Console

Ve al navegador de Cloud Storage en la consola de Google Cloud.
Ir al navegador de Cloud Storage
En la lista de buckets, haz clic en el nombre del bucket que contiene el objeto cuya LCA deseas modificar.
Haz clic en el nombre del objeto para el que deseas establecer o modificar las LCA.
Haz clic en acceso de edición.

Se abre un cuadro de diálogo de permisos con la LCA actual del objeto.
Haz clic en + Agregar entrada.
Elige el tipo de Entity (Entidad) a la que quieres darle permiso.

Entidad especifica el tipo de entidad que obtiene el permiso (por ejemplo, un usuario o un grupo). Consulta los Alcances de control de acceso a fin de obtener una lista de los valores admitidos para Entidad.
Ingresa un valor en Name (Nombre).

Nombre identifica a un usuario, grupo o algún otro tipo de entidad específica. Consulta los Alcances de control de acceso a fin de obtener una lista de los valores admitidos para Nombre.

Juntos, Entidad y Nombre definen a quién se le aplica el permiso.
Elige un valor en Access (Acceso).

Acceso define el permiso que quieres establecer en el objeto. Consulta los Permisos de control de acceso a fin de obtener una lista de los valores admitidos para Acceso.
Haz clic en Guardar.

Para obtener información sobre cómo ver detalles de errores acerca de operaciones fallidas de Cloud Storage en la consola de Google Cloud, consulta Solución de problemas.

Línea de comandos

Para agregar, modificar o quitar una concesión individual en un objeto, usa el comando objects update con la marca correspondiente:

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

Donde:

BUCKET_NAME es el nombre del bucket que contiene el objeto al que se aplica la modificación. Por ejemplo, example-travel-maps
OBJECT_NAME es el nombre del objeto al que se aplica la modificación. Por ejemplo, paris.jpg
FLAG es una de las siguientes opciones:
- --add-acl-grant, junto con la concesión que deseas agregar o modificar. Por ejemplo, --add-acl-grant=entity=user-jane@gmail.com,role=READER.
- --remove-acl-grant, junto con la entidad cuyo acceso deseas quitar. Por ejemplo, --remove-acl-grant=user-jane@gmail.com.

Para reemplazar todas las LCA de un objeto, haz lo siguiente:

Define las LCA en un archivo de formato JSON o YAML.
Usa el comando objects update con la marca --acl-file:
```
gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --acl-file=FILE_LOCATION
```
Donde:
- BUCKET_NAME es el nombre del bucket que contiene el objeto al que se aplican las LCA. Por ejemplo, example-travel-maps
- OBJECT_NAME es el nombre del objeto al que se aplican las LCA. Por ejemplo, paris.jpg
- FILE_LOCATION es la ruta de acceso local al archivo que contiene las LCA que definiste. Por ejemplo, Desktop/acls.json

El contenido de un archivo de LCA de ejemplo se muestra a continuación. Estas LCA otorgan a los propietarios del proyecto 867489160491 y al usuario jane@gmail.com el permiso OWNER para el objeto paris.jpg, y otorgan a los miembros del grupo gs-announce el permiso READER:

[
  {
    "entity": "project-owners-867489160491",
    "role": "OWNER",
    "projectTeam": {
      "projectNumber": "867489160491",
      "team": "owners"
    },
  },
  {
    "entity": "user-jane@gmail.com",
    "email": "jane@gmail.com",
    "role": "OWNER"
  },
  {
    "entity": "group-gs-announce@googlegroups.com",
    "email": "gs-announce@googlegroups.com",
    "role": "READER"
  }
]

Bibliotecas cliente

C++

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C++.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se agrega una LCA a un 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";
}

En el siguiente ejemplo, se quita la LCA de un 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#

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C#.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se agrega una LCA a un 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 = "dev@iam.gserviceaccount.com")
    {
        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;
    }
}

En el siguiente ejemplo, se quita la LCA de un 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 = "dev@iam.gserviceaccount.com")
    {
        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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Go.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se agrega una LCA a un 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
}

En el siguiente ejemplo, se quita la LCA de un 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Java.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se agrega una LCA a un 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 = "someuser@domain.com"

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

En el siguiente ejemplo, se quita la LCA de un 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 = "someuser@domain.com"

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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Node.js.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se agrega una LCA a un 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);

En el siguiente ejemplo, se quita la LCA de un 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage PHP.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se agrega una LCA a un 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. 'user-example@domain.com')
 * @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);
}

En el siguiente ejemplo, se quita la LCA de un 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. 'user-example@domain.com')
 */
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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Python.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se agrega una LCA a un 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 = "name@example.com"

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

En el siguiente ejemplo, se quita la LCA de un 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 = "name@example.com"

    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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Ruby.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se agrega una LCA a un 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}"

En el siguiente ejemplo, se quita la LCA de un 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}"

API de REST

API de JSON

Cuando creas un objeto, puedes especificar la propiedad acl[] en el cuerpo de la solicitud o el parámetro de consulta predefinedAcl en una solicitud de inserción. Para un objeto existente, especifica la propiedad acl[] o el parámetro de consulta predefinedAcl en una solicitud de parche o de actualización.

Para ver la definición de la propiedad de la LCA del objeto, consulta el recurso ObjectAccessControls.

Define las LCA en un archivo de JSON.

Por ejemplo, si con la LCA se otorga a los propietarios del proyecto 867489160491 y al usuario jane@gmail.com el permiso OWNER, además de otorgar a los miembros del grupo gs-announce el permiso READER, podrías tener un archivo llamado acls.json con el siguiente contenido:

{
"acl": [
  {
    "entity": "project-owners-867489160491",
    "role": "OWNER",
    "projectTeam": {
      "projectNumber": "867489160491",
      "team": "owners"
    }
  },
  {
    "entity": "user-jane@gmail.com",
    "role": "OWNER",
    "email": "jane@gmail.com"
  },
  {
    "entity": "group-gs-announce@googlegroups.com",
    "role": "READER",
    "email": "gs-announce@googlegroups.com"
  }
]
}

Envía una solicitud de parche con el archivo JSON y especifica el objeto en el que establecerás las LCA.

Por ejemplo, con el siguiente comando cURL, se aplica una carga útil de JSON del documento acls.json a un objeto llamado paris.jpg en el 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 de XML

En la API de XML, trabajas con LCA en formato XML. Debes adjuntar un documento XML al cuerpo de las solicitudes para cambiar las LCA del bucket y del objeto. Se muestra un documento XML cuando obtienes las LCA del bucket y del objeto. El documento XML contiene entradas de LCA del objeto o bucket individual.

Después de crear un bucket con una solicitud de bucket PUT, usa una segunda solicitud de bucket PUT con el parámetro ?acl para cambiar la LCA.
Después de subir un objeto con una solicitud de objeto PUT, cambia la LCA con otra solicitud PUT con el parámetro ?acl o el encabezado de solicitud x-googl-acl.

Con el siguiente comando cURL, se aplica una carga útil de XML desde el documento acls.xml hasta un objeto llamado paris.jpg en el 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

Usa la siguiente sintaxis de LCA para el documento API de XML.

Elemento	Descripción
`AccessControlList`	Contenedor para elementos `Entries` y `Owner`
`Owner`	Contenedor para elementos `DisplayName` y `ID` Este elemento no es necesario para los objetos, ya que un objeto siempre es propiedad el usuario que lo subió. Este elemento se usa cuando empleas la sintaxis de la LCA de Amazon S3 en una situación de migración. Amazon Simple Storage Service y Amazon S3 son marcas registradas de Amazon.com, Inc. o sus afiliados en Estados Unidos y otros países.
`ID`	ID de Cloud Storage del propietario del bucket.
`DisplayName`	No se implementó. El valor es siempre una string vacía.
`Entries`	Contenedor para cero o más elementos `Entry`
`Entry`	Contenedor para elementos `Scope` y `Permission`. Una `Entry` debe contener solo un elemento `Scope` y un elemento `Permission`.
`Scope`	Contenedor para un elemento `ID`, `EmailAddress` o `Domain` con el que se define el alcance de la LCA. Este elemento debe tener un atributo `type` que contenga uno de los siguientes valores: `UserByID`, `UserByEmail`, `GroupByID`, `GroupByEmail`, `GroupByDomain`, `AllUsers` o `AllAuthenticatedUsers`.
`ID`	Un identificador para el beneficiario cuando con el ID se especifica la entrada de permiso.
`EmailAddress`	El identificador de correo electrónico para el beneficiario cuando la entrada de permiso la especifica el correo electrónico.
`Domain`	El identificador de dominio para el beneficiario cuando la entrada de permiso se especifica por dominio.
`Name`	Elemento opcional que se puede especificar o que se puede agregar de forma automática si el alcance es `UserByEmail` o `GroupByEmail`.
`Permission`	El permiso otorgado `READ`, `WRITE` o `FULL_CONTROL`.

Cuando trabajas con LCA, usa la API de XML de la siguiente manera:

Solo puedes usar el formato XML que se describió antes.
No puedes establecer alcances duplicados.

Puedes tener muchas entradas en tu XML de la LCA, pero no puedes tener entradas con alcances duplicados. Por ejemplo, no puedes tener dos entradas con el mismo elemento de alcance de jane@example.com.

En el ejemplo siguiente, se muestran diferentes entradas de LCA 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="GroupByDomain">
        <Domain>example.com</Domain>
      </Scope>
      <Permission>READ</Permission>
    </Entry>
    <Entry>
      <Scope type="GroupByEmail">
        <EmailAddress>gs-announce@googlegroups.com</EmailAddress>
      </Scope>
      <Permission>READ</Permission>
    </Entry>
    <Entry>
      <Scope type="UserByEmail">
        <EmailAddress>jane@gmail.com</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>

Establece el elemento Nombre en el XML de la LCA

Cuando recuperas una LCA de un objeto o bucket, podrías observar un elemento <Name> adicional adjunto a algunas de tus entradas. Por ejemplo, quizás veas una entrada con el siguiente aspecto:

<Entry>
  <Scope type="UserByEmail">
    <EmailAddress>jane@gmail.com</EmailAddress>
    <Name>Jane</Name>
  </Scope>
  <Permission>FULL_CONTROL</Permission>
</Entry>

Estos elementos opcionales <Name> se propagan en las siguientes dos circunstancias:

Cuando las LCA de objeto o bucket incluyen <Name> como elemento

Cuando estableces las LCA, puedes elegir incluir el elemento <Name> con tus entradas de LCA. Puedes proporcionar cualquier valor en el elemento <Name>; Cloud Storage recuerda estos valores hasta que se quita o reemplaza la LCA. Este enfoque puede ser útil si usas identificadores que no son fáciles de identificar.
Cuando un alcance UserByEmail o GroupByEmail contiene un perfil público de Google.

Si usas uno de estos alcances, pero no proporcionas un elemento <Name>, Cloud Storage verifica si el usuario o Grupo de Google asociado con la dirección de correo electrónico tiene un perfil público de Google con un nombre público. Si es así, Cloud Storage propaga de forma automática el elemento <Name> con el nombre público.

Aplica una LCA predefinida

En vez de especificar la LCA en su totalidad de a una entrada a la vez como se muestra arriba, puedes usar una LCA predefinida. Esta se aplicará de forma automática a un número de entradas personalizadas en una situación específica. Puedes aplicar una LCA predefinida a un bucket o un objeto con Google Cloud CLI, la API de JSON o la API de XML.

En objetos nuevos

Para aplicar una LCA predefinida a un objeto mientras se sube, haz lo siguiente:

Console

No puedes aplicar una LCA predefinida con la consola de Google Cloud. Utiliza gcloud storage en su lugar.

Línea de comandos

Usa el comando gcloud storage cp con la marca --predefined-acl:

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

Por ejemplo, para aplicar la LCA predefinida bucketOwnerRead cuando se sube un objeto paris.jpg a un bucket example-travel-maps, haz lo siguiente:

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

API de REST

API de JSON

Usa el parámetro predefinedAcl de string de consulta en una solicitud de inserción para aplicar la LCA predefinida.

Por ejemplo, para aplicar la LCA predefinida bucketOwnerRead cuando se sube un objeto paris.jpg a un bucket example-travel-maps, haz lo siguiente:

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 de XML

Usa el encabezado x-goog-acl en una solicitud Put de objeto para aplicar la LCA predefinida.

Por ejemplo, para aplicar la LCA predefinida bucket-owner-read cuando se sube un objeto paris.jpg a un bucket example-travel-maps, haz lo siguiente:

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

En objetos o depósitos existentes

También puedes aplicar una LCA predefinida en un objeto o bucket existente, que es útil si deseas cambiar de una LCA predefinida a otra, o si deseas actualizar una LCA personalizada a una predefinida.

Console

No puedes aplicar una LCA predefinida con la consola de Google Cloud. Utiliza gcloud storage en su lugar.

Línea de comandos

Usa el comando objects update con la marca --predefined-acl:

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

Por ejemplo, para aplicar la LCA predefinida private al objeto paris.jpg en el bucket example-travel-maps, haz lo siguiente:

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

API de REST

API de JSON

Usa el parámetro de string de consulta predefinedAcl y especifica una propiedad vacía acl en una solicitud de parche para aplicar la LCA predefinida.

Por ejemplo, para aplicar la LCA predefinida private al objeto paris.jpg en el bucket example-travel-maps, haz lo siguiente:

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 de XML

Usa el encabezado x-goog-acl con el parámetro de string de consulta acl en una solicitud Put Object, pero no incluyas un documento XML en ella.

Por ejemplo, para aplicar la LCA predefinida private al objeto paris.jpg en el bucket example-travel-maps, haz lo siguiente:

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

Establece LCA de objeto predeterminadas

Para evitar establecer LCA cada vez que creas un objeto nuevo, puedes determinar una LCA de objeto predeterminada en un bucket. Una vez que haces esto, se le aplicará la LCA predeterminada a cada objeto nuevo agregado a ese bucket que no tenga una aplicada de forma explícita. Por ejemplo, quizás desees especificar que solo un determinado grupo de usuarios tenga acceso a la mayoría de los objetos en un bucket determinado. Puedes cambiar la LCA de objeto predeterminada y, luego, agregar objetos al bucket. A estos objetos agregados se les aplica de forma automática la LCA de objeto predeterminada que especificaste; sin embargo, puedes proporcionar diferentes LCA a objetos específicos, en cuyo caso no se les aplicará la LCA predeterminada.

Para ver y cambiar la LCA de objeto predeterminada de un bucket, haz lo siguiente:

Console

No puedes establecer LCA de objeto predeterminadas con la consola de Google Cloud. Utiliza gcloud storage en su lugar.

Línea de comandos

Usa el comando buckets describe con la marca --format a fin de recuperar la LCA de objetos predeterminada para el bucket:
```
gcloud storage buckets describe gs://BUCKET_NAME --format="default(default_acl)"
```
En el ejemplo anterior, BUCKET_NAME es el nombre del bucket con la LCA de objetos predeterminada que deseas ver. Por ejemplo, my-bucket
Usa el comando buckets update con la marca deseada para modificar la LCA de objetos predeterminada del bucket:
```
gcloud storage buckets update gs://BUCKET_NAME FLAG
```
Donde:
- BUCKET_NAME es el nombre del bucket con la LCA de objetos predeterminada que deseas modificar. Por ejemplo, my-bucket
- FLAG es una de las siguientes opciones:
  - --add-default-object-acl-grant y una concesión que desees agregar a la LCA de objetos predeterminada general del bucket.
  - --default-object-acl-file y la ruta a un archivo local que define una LCA de objetos predeterminada nueva para el bucket.
  - --predefined-default-object-acl y el nombre de una LCA de objetos predefinida con la que quieras reemplazar la LCA de objetos predeterminada existente para el bucket.
  - --remove-default-object-acl-grant y una entidad que desees quitar de la LCA de objetos predeterminada general del bucket.

Bibliotecas cliente

C++

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C++.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se agrega una LCA de objeto predeterminada a un 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";
}

En la siguiente tabla, se borra una LCA de objeto predeterminada de un 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#

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C#.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se imprime la LCA del objeto predeterminado de un 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;
    }
}

En el siguiente ejemplo, se agrega una LCA de objeto predeterminada a un 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 = "dev@iam.gserviceaccount.com")
    {
        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;
    }
}

En la siguiente tabla, se borra una LCA de objeto predeterminada de un 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 = "user@iam.gserviceaccount.com")
    {
        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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Go.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se agrega una LCA de objeto predeterminada a un 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
}

En la siguiente tabla, se borra una LCA de objeto predeterminada de un 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Java.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se agrega una LCA de objeto predeterminada a un 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 = "someuser@domain.com"

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

En la siguiente tabla, se borra una LCA de objeto predeterminada de un 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 = "someuser@domain.com"

    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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Node.js.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se agrega una LCA de objeto predeterminada a un 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);

En la siguiente tabla, se borra una LCA de objeto predeterminada de un 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage PHP.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se agrega una LCA de objeto predeterminada a un 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. 'user-example@domain.com')
 * @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);
}

En la siguiente tabla, se borra una LCA de objeto predeterminada de un 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. 'user-example@domain.com')
 */
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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Python.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se agrega una LCA de objeto predeterminada a un 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 = "name@example.com"

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

En la siguiente tabla, se borra una LCA de objeto predeterminada de un 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 = "name@example.com"

    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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Ruby.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se agrega una LCA de objeto predeterminada a un 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}"

En la siguiente tabla, se borra una LCA de objeto predeterminada de un 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}"

API de REST

API de JSON

Recupera la LCA de objeto predeterminada con una solicitud GET. Por ejemplo:

curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?projection=full

Usa una solicitud de parche para reemplazar la LCA de objeto predeterminada. Por ejemplo, con la siguiente solicitud, se reemplaza la LCA de objeto predeterminada por la LCA especificada en defacls.json para un 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

Un ejemplo de defacls.json:

{
"defaultObjectAcl": [
  {
    "email": "jane@gmail.com",
    "entity": "user-jane@gmail.com",
    "role": "READER"
  }
]
}

API de XML

Recupera la LCA de objeto predeterminada con una solicitud GET con el alcance acotado a tu bucket y el parámetro ?defaultObjectAcl. Por ejemplo:
```
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://storage.googleapis.com/BUCKET_NAME?defaultObjectAcl
```

Usa una solicitud PUT con el alcance acotado a tu bucket y el parámetro ?defaultObjectAcl para reemplazar la LCA de objeto predeterminada por la LCA especificada en acls.xml. Por ejemplo:

curl -X PUT --data-binary @acls.xml -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    http://storage.googleapis.com/BUCKET_NAME?defaultObjectAcl

Un ejemplo de acls.xml:

<AccessControlList>
  <Entries>
    <Entry>
      <Permission>FULL_CONTROL</Permission>
      <Scope type="UserByEmail">
        <EmailAddress>jane@gmail.com</EmailAddress>
      </Scope>
    </Entry>
  </Entries>
</AccessControlList>

La sintaxis de las LCA se describen en Establece LCA. También puedes especificar una LCA predefinida como la LCA de objeto predeterminada.

Para establecer la LCA de objeto predeterminada de un bucket como una LCA predefinida, haz lo siguiente:

Console

No puedes establecer LCA de objeto predeterminadas con la consola de Google Cloud. Utiliza gcloud storage en su lugar.

Línea de comandos

Usa el comando buckets update con la marca --predefined-default-object-acl:

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

Donde:

BUCKET_NAME es el nombre del bucket con la LCA de objetos predeterminada que deseas modificar. Por ejemplo, my-bucket
PREDEFINED_ACL es el nombre de una LCA predefinida válida. Por ejemplo, projectPrivate

APIs de REST

API de JSON

Usa una solicitud PUT y el parámetro predefinedAcl.

Por ejemplo:

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 de XML

Usa una solicitud PUT con el alcance acotado a tu bucket, el parámetro ?defaultObjectAcl y el encabezado x-goog-acl.

Por ejemplo:

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

LCA de objetos predeterminadas para los depósitos recién creados:

En los siguientes ejemplos, se muestran las LCA de objeto predeterminadas que se aplican de forma automática a los depósitos recién creados cuando no especificas tus propias LCA de objeto predeterminadas como parte de la solicitud. Para ver si se cambiaron las LCA de objeto predeterminadas de tu bucket, compara las LCA de objeto predeterminadas actuales de tu bucket con los ejemplos a continuación.

Console

No puedes trabajar con LCA de objeto predeterminadas en la consola de Google Cloud. Utiliza gcloud storage en lugar de esta función.

Línea de comandos

En el ejemplo siguiente, el ID del proyecto es “123412341234”; el tuyo 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

API de REST

API de JSON

En el ejemplo siguiente, el ID del proyecto es “123412341234”; el tuyo 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 de XML

En el ejemplo siguiente, los ID de función del proyecto comienzan con “00b4903a97…”; tus ID de proyecto serán 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>

Ten en cuenta que la LCA de objeto predeterminada para un bucket recién creado es equivalente a la LCA projectPrivate predefinida.

Recupera las LCA

Para obtener la LCA de un recurso existente, sigue estos pasos:

Console

Ve al navegador de Cloud Storage en la consola de Google Cloud.
Ir al navegador de Cloud Storage
Navega al objeto cuya LCA deseas ver.
Elige Editar acceso en el menú desplegable del objeto.

Deberías ver un diálogo con los permisos del objeto.

Para obtener información sobre cómo ver detalles de errores acerca de operaciones fallidas de Cloud Storage en la consola de Google Cloud, consulta Solución de problemas.

Línea de comandos

Usa el comando objects describe con la marca --format para recuperar la LCA de un objeto:
```
gcloud storage objects describe gs://BUCKET_NAME/OBJECT_NAME --format="default(acl)"
```
Donde:
- BUCKET_NAME es el nombre del bucket que contiene el objeto cuya LCA deseas ver. Por ejemplo, my-bucket
- OBJECT_NAME es el nombre del objeto cuya LCA deseas ver. Por ejemplo, paris.jpg

Bibliotecas cliente

C++

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C++.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se obtiene una LCA de objeto:

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#

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C#.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se obtiene una LCA de objeto:


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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Go.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se obtiene una LCA de objeto:

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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Java.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se obtiene una LCA de objeto:


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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Node.js.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se obtiene una LCA de 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';

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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage PHP.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se obtiene una LCA de objeto:

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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Python.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se obtiene una LCA de objeto:

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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Ruby.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se obtiene una LCA de 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

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 de REST

API de JSON

Asegúrate de tener permiso OWNER en el objeto.
Recupera la LCA de un objeto con una solicitud GET.

La LCA de objeto se muestra en el formato JSON adjunta al cuerpo de la respuesta.

Por ejemplo, para mostrar la LCA del objeto paris.jpg en el bucket example-travel-maps, haz lo siguiente:

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

Deberías ver una respuesta similar a la siguiente:

{
  "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": "user-jane@gmail.com",
      "role": "OWNER",
      "email": "jane@gmail.com",
      ...
    },
    {
      ...
      "entity": "group-gs-announce@googlegroups.com",
      "role": "READER",
      "email": "gs-announce@googlegroups.com",
      ...
    }
    ],
  "owner": {
    "entity": "user-jane@gmail.com"
  },
  ...
}

También puedes usar el método GET de recurso objectAccessControls para mostrar entradas individuales de la LCA de un objeto.

API de XML

Asegúrate de tener permiso FULL_CONTROL en el objeto o bucket.
Recupera la LCA del objeto o bucket con el parámetro de string de consulta acl en una solicitud GET de objeto.

Las LCA se describen en XML, adjuntas al cuerpo de la respuesta.

Por ejemplo, para mostrar la LCA del objeto paris.jpg en el bucket example-travel-maps, haz lo siguiente:

curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://storage.googleapis.com/example-travel-maps/paris.jpg?acl

Deberías ver una respuesta similar a la siguiente:

<?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>jane@gmail.com</EmailAddress>
        <Name>Jane</Name>
      </Scope>
      <Permission>FULL_CONTROL</Permission>
    </Entry>
    <Entry>
      <Scope type="GroupByEmail">
        <EmailAddress>gs-announce@googlegroups.com</EmailAddress>
      </Scope>
      <Permission>READ</Permission>
    </Entry>
  </Entries>
</AccessControlList>

También puedes usar el método JSON GET del recurso ObjectAccessControls para mostrar una entrada específica de la LCA.

¿Qué sigue?

Obtén más información sobre las LCA.
Para aprender a simplificar el control de acceso, consulta Usa el acceso uniforme a nivel de bucket .
Obtén información sobre las prácticas recomendadas para usar las LCA.