Créer et gérer des listes de contrôle d'accès (LCA)

Présentation

Cette page explique comment contrôler l'accès aux buckets et aux objets à l'aide de listes de contrôle d'accès (LCA). Une liste de contrôle d'accès, ou LCA, est un mécanisme permettant de déterminer qui a accès à vos buckets et objets, et de définir le niveau d'accès accordé.

Consultez la présentation des LCA pour savoir si vous devez utiliser des LCA pour contrôler l'accès à vos ressources.

Rôles requis

Pour obtenir les autorisations nécessaires pour créer et gérer des LCA, demandez à votre administrateur de vous accorder le rôle IAM d'administrateur de l'espace de stockage (roles/storage.admin) sur le bucket contenant les objets pour lesquels vous souhaitez créer et gérer des LCA.

Ce rôle prédéfini contient les autorisations requises pour créer et gérer des ACL. Pour afficher les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

  • storage.buckets.get
  • storage.buckets.list
    • Cette autorisation n'est nécessaire que pour effectuer les tâches décrites sur cette page à l'aide de la console Google Cloud.
  • storage.buckets.setIamPolicy
  • storage.buckets.update
  • storage.objects.get
  • storage.objects.getIamPolicy
  • storage.objects.setIamPolicy
  • storage.objects.update

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés.

Pour en savoir plus sur l'attribution de rôles dans des buckets, consultez la page Utiliser IAM avec des buckets.

Définir ou modifier des listes de contrôle d'accès

Console

  1. Accédez au navigateur Cloud Storage dans la console Google Cloud.
    Accéder au navigateur Cloud Storage

  2. Dans la liste des buckets, cliquez sur le nom du bucket contenant l'objet dont vous souhaitez modifier la liste de contrôle d'accès.

  3. Cliquez sur le nom de l'objet pour lequel vous souhaitez définir ou modifier des LCA.

  4. Cliquez sur Modifier l'accès.

    Une boîte de dialogue d'autorisation affichant la LCA actuelle de l'objet s'affiche.

  5. Cliquez sur + Ajouter une entrée.

  6. Choisissez le type d'entité auquel une autorisation doit être accordée.

    Le champ Entité spécifie le type d'objet qui obtient l'autorisation (par exemple, un utilisateur ou un groupe). Consultez la section Champs d'application liés au contrôle des accès pour connaître la liste des valeurs acceptées pour Entité.

  7. Saisissez une valeur dans le champ Nom.

    Le champ Nom identifie un utilisateur, un groupe ou un autre type d'entité spécifique. Consultez la section Champs d'application liés au contrôle des accès pour connaître la liste des valeurs acceptées pour Nom.

    Les champs Entité et Nom définissent à qui s'applique l'autorisation.

  8. Choisissez une valeur dans le champ Accès.

    Le champ Accès définit l'autorisation que vous souhaitez configurer sur l'objet. Consultez la section Autorisations liées au contrôle des accès pour connaître la liste des valeurs acceptées pour Accès.

  9. Cliquez sur Enregistrer.

Pour savoir comment obtenir des informations détaillées sur les erreurs liées aux opérations Cloud Storage ayant échoué dans la console Google Cloud, consultez la section Dépannage.

Ligne de commande

Pour ajouter, modifier ou supprimer une autorisation individuelle sur un objet, exécutez la commande objects update avec l'option pertinente :

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

Où :

  • BUCKET_NAME correspond au nom du bucket contenant l'objet auquel la modification s'applique. Exemple : example-travel-maps.

  • OBJECT_NAME correspond au nom de l'objet auquel la modification s'applique. Par exemple, paris.jpg.

  • FLAG est l'un des éléments suivants :

    • --add-acl-grant, ainsi que l'autorisation que vous souhaitez ajouter ou modifier. Exemple : --add-acl-grant=entity=user-jane@gmail.com,role=READER.

    • --remove-acl-grant, ainsi que l'entité dont vous souhaitez supprimer l'accès. Exemple : --remove-acl-grant=user-jane@gmail.com.

Pour remplacer toutes les LCA associées à un objet, procédez comme suit :

  1. Définissez les LCA dans un fichier au format JSON ou YAML.

  2. Exécutez la commande objects update avec l'option --acl-file :

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

    Où :

    • BUCKET_NAME correspond au nom du bucket contenant l'objet auquel les LCA s'appliquent. Exemple : example-travel-maps.

    • OBJECT_NAME correspond au nom de l'objet auquel les LCA s'appliquent. Par exemple, paris.jpg.

    • FILE_LOCATION est le chemin d'accès local au fichier contenant les LCA que vous avez définies. Exemple : Desktop/acls.json.

Vous trouverez ci-dessous un exemple de fichier d'ACL. Ces LCA accordent aux propriétaires de projet 867489160491, ainsi qu'à l'utilisateur jane@gmail.com, l'autorisation OWNER sur l'objet paris.jpg, et accordent également aux membres du groupe gs-announce l'autorisation READER sur cet objet :

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

Bibliothèques clientes

C++

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage C++.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant ajoute une liste de contrôle d'accès à un objet :

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

L'exemple suivant permet de supprimer une LCA d'un objet :

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#

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage C#.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant ajoute une liste de contrôle d'accès à un objet :


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

L'exemple suivant permet de supprimer une LCA d'un objet :


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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Go.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant ajoute une liste de contrôle d'accès à un objet :

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
}

L'exemple suivant permet de supprimer une LCA d'un objet :

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Java.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant ajoute une liste de contrôle d'accès à un objet :


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

L'exemple suivant permet de supprimer une LCA d'un objet :


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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Node.js.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant ajoute une liste de contrôle d'accès à un objet :

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

L'exemple suivant permet de supprimer une LCA d'un objet :

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage PHP.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant ajoute une liste de contrôle d'accès à un objet :

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

L'exemple suivant permet de supprimer une LCA d'un objet :

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Python.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant ajoute une liste de contrôle d'accès à un objet :

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

L'exemple suivant permet de supprimer une LCA d'un objet :

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Ruby.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant ajoute une liste de contrôle d'accès à un objet :

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

L'exemple suivant permet de supprimer une LCA d'un objet :

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

API JSON

Lors de la création d'un objet, vous pouvez spécifier la propriété acl[] dans le corps de la requête ou le paramètre de requête predefinedAcl dans une requête insert. Pour un objet existant, spécifiez la propriété acl[] ou le paramètre de requête predefinedAcl dans une requête patch ou update.

Pour obtenir la définition de la propriété de LCA d'objet, consultez la ressource ObjectAccessControls.

  1. Définissez les LCA dans un fichier JSON.

    Par exemple, si la LCA accorde aux propriétaires du projet 867489160491 et à l'utilisateur jane@gmail.com l'autorisation OWNER, et aux membres du groupe gs-announce l'autorisation READER, vous pouvez obtenir un fichier nommé acls.json avec le contenu suivant :

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

  2. Envoyez une requête patch avec le fichier JSON et spécifiez l'objet sur lequel définir les LCA.

Par exemple, la commande cURL suivante applique une charge utile JSON du document acls.json à un objet nommé paris.jpg dans le 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

Dans l'API XML, vous utilisez des listes de contrôle d'accès au format XML. Vous devez joindre un document XML au corps des requêtes de modification des LCA associées aux objets et au bucket. Un document XML est renvoyé lorsque vous obtenez des LCA associées aux objets et au bucket. Le document XML contient les entrées individuelles de LCA associées à des objets ou au bucket.

  • Après la création d'un bucket à l'aide d'une requête de bucket PUT, exécutez une seconde requête de bucket PUT avec le paramètre ?acl pour modifier la LCA associée au bucket.

  • Après avoir importé un objet avec une requête d'objet PUT, remplacez la LCA par une autre requête PUT avec le paramètre ?acl ou l'en-tête de requête x-googl-acl.

Par exemple, la commande cURL suivante applique une charge utile XML du document acls.xml à un objet nommé paris.jpg dans le 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

Utilisez la syntaxe de LCA suivante pour le document XML.

Élément Description
AccessControlList Conteneur pour les éléments Entries et Owner.
Owner Conteneur pour les éléments DisplayName et ID. Cet élément n'est pas obligatoire pour les objets puisqu'un objet appartient toujours à l'utilisateur qui l'a importé. Cet élément est utilisé lorsque vous appliquez la syntaxe de LCA Amazon S3 dans un scénario de migration.

Amazon Simple Storage Service™ et Amazon S3™ sont des marques d'Amazon.com, Inc. ou de ses sociétés affiliées aux États-Unis et/ou dans d'autres pays.
ID ID Cloud Storage du propriétaire du bucket.
DisplayName Fonctionnalité non disponible. La valeur correspond toujours à une chaîne vide.
Entries Conteneur pour zéro ou plusieurs éléments Entry.
Entry Conteneur pour les éléments Scope et Permission. Un Entry ne doit contenir qu'un seul élément Scope et qu'un seul élément Permission.
Scope Conteneur pour un élément ID, EmailAddress ou Domain qui définit le champ d'application de la LCA. Cet élément doit avoir un attribut type contenant l'une des valeurs suivantes: UserByID, UserByEmail, GroupByID, GroupByEmail, GroupByDomain, AllUsers ou AllAuthenticatedUsers.
ID Identifiant associé au bénéficiaire lorsque l'entrée d'autorisation est spécifiée par ID.
EmailAddress Identifiant d'adresse e-mail associé au bénéficiaire lorsque l'entrée d'autorisation est spécifiée par adresse e-mail.
Domain Identifiant de domaine associé au bénéficiaire lorsque l'entrée d'autorisation est spécifiée par domaine.
Name Élément facultatif pouvant être spécifié ou pouvant être ajouté automatiquement si le champ d'application correspond à UserByEmail ou GroupByEmail.
Permission Autorisation READ, WRITE ou FULL_CONTROL accordée.

Lorsque vous utilisez des LCA à l'aide de l'API XML :

  • vous ne pouvez utiliser que le format XML décrit ci-dessus ;

  • vous ne pouvez pas définir des champs d'application en double.

    Vous pouvez disposer de plusieurs entrées dans votre LCA XML, mais vous ne pouvez pas disposer d'entrées avec des champs d'application en double. Par exemple, vous ne pouvez pas avoir deux entrées avec le même élément de champ d'application de jane@example.com.

L'exemple suivant montre différentes entrées de liste de contrôle d'accès associées à un 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>

Configurer l'élément "Name" dans une liste de contrôle d'accès XML

Lorsque vous récupérez une LCA à partir d'un bucket ou d'un objet, vous pouvez remarquer un élément <Name> supplémentaire ajouté à certaines de vos entrées. Par exemple, une entrée semblable à ce qui suit peut s'afficher :

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

Ces éléments <Name> facultatifs sont renseignés dans deux cas :

  1. Lorsque les LCA associées au bucket ou aux objets incluent <Name> en tant qu'élément.

    Lorsque vous définissez des LCA, vous pouvez choisir d'inclure l'élément <Name> avec vos entrées LCA. Vous pouvez indiquer n'importe quelle valeur dans l'élément <Name>. Cloud Storage mémorise ces valeurs jusqu'à ce que la LCA soit supprimée ou remplacée. Cette approche peut être judicieuse si vous utilisez des identifiants difficiles à identifier.

  2. Lorsqu'un champ d'application UserByEmail ou GroupByEmail contient un profil Google public.

    Si vous utilisez l'un de ces champs d'application, mais ne fournissez pas d'élément <Name>, Cloud Storage vérifie si l'utilisateur ou le groupe Google associé à l'adresse e-mail possède un profil Google public portant un nom public. Si c'est le cas, Cloud Storage renseigne automatiquement l'élément <Name> avec le nom public.

Appliquer une LCA prédéfinie

Plutôt que de spécifier l'intégralité d'une liste de contrôle d'accès une entrée à la fois comme indiqué ci-dessus, vous pouvez utiliser une liste de contrôle d'accès prédéfinie qui applique automatiquement un nombre d'entrées personnalisées à un scénario spécifique. Vous pouvez appliquer une LCA prédéfinie à un bucket ou à un objet à l'aide de Google Cloud CLI, de l'API JSON ou de l'API XML.

Sur de nouveaux objets

Pour appliquer une liste de contrôle d'accès prédéfinie à un objet lors de l'importation d'un objet, procédez comme suit :

Console

Vous ne pouvez pas appliquer une LCA prédéfinie à l'aide de la console Google Cloud. Utilisez plutôt gcloud storage.

Ligne de commande

Exécutez la commande gcloud storage cp avec l'option --predefined-acl :

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

Par exemple, pour appliquer la LCA bucketOwnerRead prédéfinie lors de l'importation d'un objet paris.jpg dans un bucket example-travel-maps, exécutez la commande suivante :

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

API REST

API JSON

Utilisez le paramètre de chaîne de requête predefinedAcl dans une requête insert pour appliquer la LCA prédéfinie.

Par exemple, pour appliquer la LCA bucketOwnerRead prédéfinie lors de l'importation d'un objet paris.jpg dans un bucket example-travel-maps, exécutez la commande suivante :

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

Utilisez l'en-tête x-goog-acl d'une requête d'objet PUT pour appliquer la LCA prédéfinie.

Par exemple, pour appliquer la LCA bucket-owner-read prédéfinie lors de l'importation d'un objet paris.jpg dans un bucket example-travel-maps, exécutez la commande suivante :

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

Sur des buckets ou des objets existants

Vous pouvez également appliquer une LCA prédéfinie à un bucket ou à un objet existant. Cette méthode est utile si vous souhaitez passer d'une LCA prédéfinie à une autre ou mettre à jour des LCA personnalisées et les configurer en tant que LCA prédéfinies.

Console

Vous ne pouvez pas appliquer une LCA prédéfinie à l'aide de la console Google Cloud. Utilisez plutôt gcloud storage.

Ligne de commande

Exécutez la commande objects update avec l'option --predefined-acl :

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

Par exemple, pour appliquer la LCA private prédéfinie à l'objet paris.jpg dans le bucket example-travel-maps, exécutez la commande suivante :

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

API REST

API JSON

Utilisez le paramètre de chaîne de requête predefinedAcl et spécifiez une propriété acl vide dans une requête patch pour appliquer la LCA prédéfinie.

Par exemple, pour appliquer la LCA private prédéfinie à l'objet paris.jpg dans le bucket example-travel-maps, exécutez la commande suivante :

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

Utilisez l'en-tête x-goog-acl avec le paramètre de chaîne de requête acl dans une requête d'objet PUT, mais n'incluez pas de document XML dans votre requête.

Par exemple, pour appliquer la LCA private prédéfinie à l'objet paris.jpg dans le bucket example-travel-maps, exécutez la commande suivante :

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

Définir les LCA des objets par défaut

Pour éviter de configurer des LCA chaque fois que vous créez un objet, vous pouvez définir une liste de contrôle d'accès aux objets par défaut sur un bucket. Une fois que vous avez effectué cette opération, la valeur par défaut est appliquée à chaque nouvel objet ajouté à ce bucket auquel aucune LCA n'a été explicitement appliquée. Par exemple, vous pouvez spécifier que seul un groupe d'utilisateurs donné a accès à la plupart des objets d'un bucket particulier. Vous pouvez modifier la liste de contrôle d'accès aux objets par défaut, puis ajouter des objets au bucket. La liste de contrôle d'accès aux objets par défaut que vous avez spécifiée est automatiquement appliquée à ces objets ajoutés. Toutefois, vous pouvez attribuer différentes LCA à des objets spécifiques. Dans ce cas, la LCA par défaut n'est pas appliquée à ces objets.

Pour afficher et modifier la LCA associée aux objets par défaut pour un bucket, exécutez la commande suivante :

Console

Vous ne pouvez pas définir des LCA associées à des objets par défaut à l'aide de la console Google Cloud. Utilisez plutôt gcloud storage.

Ligne de commande

  1. Exécutez la commande buckets describe avec l'option --format pour récupérer la LCA associée aux objets par défaut pour le bucket :

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

    Où BUCKET_NAME correspond au nom du bucket dont vous souhaitez afficher la LCA d'objets par défaut. Par exemple, my-bucket.

  2. Exécutez la commande buckets update avec l'option souhaitée pour modifier la LCA associée aux objets par défaut pour le bucket :

    gcloud storage buckets update gs://BUCKET_NAME FLAG

    Où :

    • BUCKET_NAME correspond au nom du bucket dont vous souhaitez modifier la LCA d'objets par défaut. Exemple : my-bucket.

    • FLAG est l'un des éléments suivants :

      • --add-default-object-acl-grant et une autorisation que vous souhaitez ajouter à la LCA d'objets par défaut globale pour le bucket.

      • --default-object-acl-file et le chemin d'accès à un fichier local qui définit une nouvelle LCA d'objets par défaut pour le bucket.

      • --predefined-default-object-acl et le nom d'une LCA d'objets prédéfinie que vous souhaitez utiliser pour remplacer la LCA d'objets par défaut existante pour le bucket.

      • --remove-default-object-acl-grant et une entité que vous souhaitez supprimer de la LCA d'objets par défaut globale pour le bucket.

Bibliothèques clientes

C++

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage C++.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant ajoute une liste de contrôle d'accès aux objets par défaut à 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";
}

L'exemple suivant supprime une liste de contrôle d'accès aux objets par défaut d'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#

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage C#.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant affiche la LCA associée aux objets par défaut pour 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;
    }
}

L'exemple suivant ajoute une liste de contrôle d'accès aux objets par défaut à 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;
    }
}

L'exemple suivant supprime une liste de contrôle d'accès aux objets par défaut d'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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Go.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant ajoute une liste de contrôle d'accès aux objets par défaut à 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
}

L'exemple suivant supprime une liste de contrôle d'accès aux objets par défaut d'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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Java.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant ajoute une liste de contrôle d'accès aux objets par défaut à 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);
  }
}

L'exemple suivant supprime une liste de contrôle d'accès aux objets par défaut d'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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Node.js.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant ajoute une liste de contrôle d'accès aux objets par défaut à 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);

L'exemple suivant supprime une liste de contrôle d'accès aux objets par défaut d'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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage PHP.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant ajoute une liste de contrôle d'accès aux objets par défaut à 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);
}

L'exemple suivant supprime une liste de contrôle d'accès aux objets par défaut d'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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Python.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant ajoute une liste de contrôle d'accès aux objets par défaut à 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
        )
    )

L'exemple suivant supprime une liste de contrôle d'accès aux objets par défaut d'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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Ruby.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant ajoute une liste de contrôle d'accès aux objets par défaut à 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}"

L'exemple suivant supprime une liste de contrôle d'accès aux objets par défaut d'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 REST

API JSON

  1. Utilisez une requête GET pour récupérer la LCA associée aux objets par défaut : Exemple :

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

  2. Exécutez une requête patch pour remplacer la LCA associée aux objets par défaut. Par exemple, la requête suivante remplace la LCA associée aux objets par défaut par la LCA spécifiée dans defacls.json pour 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

    Exemple de defacls.json :

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

API XML

  1. Récupérez la LCA associée aux objets par défaut avec une requête GET limitée à votre bucket et au paramètre ?defaultObjectAcl. Exemple :

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

  2. Exécutez une requête PUT limitée à votre bucket par le paramètre ?defaultObjectAcl pour remplacer la LCA associée aux objets par défaut par celle spécifiée dans acls.xml. Exemple :

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

    Exemple de acls.xml :

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

La syntaxe des LCA est décrite dans la section Configurer des listes de contrôle d'accès. Vous pouvez également spécifier une LCA prédéfinie en tant que LCA associée aux objets par défaut.

Pour configurer la liste de contrôle d'accès aux objets par défaut associée à un bucket sur une liste de contrôle d'accès prédéfinie :

Console

Vous ne pouvez pas définir des LCA associées à des objets par défaut à l'aide de la console Google Cloud. Utilisez plutôt gcloud storage.

Ligne de commande

Exécutez la commande buckets update avec l'option --predefined-default-object-acl :

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

Où :

  • BUCKET_NAME correspond au nom du bucket dont vous souhaitez modifier la LCA d'objets par défaut. Exemple : my-bucket.

  • PREDEFINED_ACL correspond au nom d'une LCA prédéfinie valide. Par exemple, projectPrivate.

API REST

API JSON

Exécutez une requête PUT avec le paramètre predefinedAcl.

Exemple :

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

Exécutez une requête PUT limitée à votre bucket avec le paramètre ?defaultObjectAcl et l'en-tête x-goog-acl.

Exemple :

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 concernant les objets par défaut associées aux buckets nouvellement créés :

Les exemples suivants montrent les LCA concernant les objets par défaut qui s'appliquent automatiquement aux buckets nouvellement créés lorsque vous ne spécifiez pas vos propres LCA d'objets par défaut dans le cadre de la requête. Pour voir si les LCA concernant les objets par défaut de votre bucket ont été modifiées, comparez les LCA d'objets par défaut actuelles de votre bucket aux exemples ci-dessous.

Console

Vous ne pouvez pas utiliser les LCA associées aux objets par défaut à l'aide de la console Google Cloud. Utilisez plutôt gcloud storage.

Ligne de commande

Dans l'exemple ci-dessous, l'ID de projet est "123412341234". Votre ID de projet sera différent.

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 REST

API JSON

Dans l'exemple ci-dessous, l'ID de projet est "123412341234". Votre ID de projet sera différent.

"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

Dans l'exemple ci-dessous, les ID de rôle de projet commencent par "00b4903a97".Vos ID de projet seront différents.

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

Notez que la LCA associée aux objets par défaut pour un bucket nouvellement créé est équivalente à la LCA prédéfinie projectPrivate.

Récupérer des listes de contrôle d'accès

Pour obtenir la liste de contrôle d'accès associée à une ressource existante, procédez comme suit :

Console

  1. Accédez au navigateur Cloud Storage dans la console Google Cloud.
    Accéder au navigateur Cloud Storage

  2. Accédez à l'objet dont vous souhaitez afficher la liste de contrôle d'accès.

  3. Choisissez Modifier les autorisations dans le menu déroulant de l'objet.

    Une boîte de dialogue d'autorisation affichant les autorisations de l'objet doit s'ouvrir.

Pour savoir comment obtenir des informations détaillées sur les erreurs liées aux opérations Cloud Storage ayant échoué dans la console Google Cloud, consultez la section Dépannage.

Ligne de commande

  1. Exécutez la commande objects describe avec l'option --format pour récupérer la LCA associée à un objet :

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

    Où :

    • BUCKET_NAME correspond au nom du bucket contenant l'objet dont vous souhaitez afficher la LCA. Exemple : my-bucket.

    • OBJECT_NAME correspond au nom de l'objet pour lequel vous souhaitez afficher la LCA. Par exemple, paris.jpg.

Bibliothèques clientes

C++

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage C++.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant permet d'obtenir une liste de contrôle d'accès associée à un objet :

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#

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage C#.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant permet d'obtenir une liste de contrôle d'accès associée à un objet :


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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Go.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant permet d'obtenir une liste de contrôle d'accès associée à un objet :

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Java.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant permet d'obtenir une liste de contrôle d'accès associée à un objet :


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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Node.js.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant permet d'obtenir une liste de contrôle d'accès associée à un objet :

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage PHP.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant permet d'obtenir une liste de contrôle d'accès associée à un objet :

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Python.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant permet d'obtenir une liste de contrôle d'accès associée à un objet :

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Ruby.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

L'exemple suivant permet d'obtenir une liste de contrôle d'accès associée à un objet :

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

API JSON

  1. Assurez-vous de disposer de l'autorisation OWNER sur l'objet.

  2. Récupérez la LCA associée à l'objet à l'aide d'une requête GET.

    La LCA associée à l'objet est renvoyée au format JSON et jointe au corps de la réponse.

Par exemple, pour renvoyer la LCA associée à l'objet paris.jpg dans le bucket example-travel-maps, utilisez la commande suivante :

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

Une réponse semblable aux lignes suivantes doit s'afficher :

{
  "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"
  },
  ...
}

Vous pouvez également utiliser la méthode objectAccessControls de la ressource GETpour afficher des entrées individuelles dans une LCA associée à un objet.

API XML

  1. Assurez-vous de disposer de l'autorisation FULL_CONTROL sur le bucket ou l'objet.

  2. Récupérez la LCA associée au bucket ou à l'objet à l'aide du paramètre de chaîne de requête acl dans une requête d'objet GET.

Les LCA sont décrites au format XML et jointes au corps de la réponse.

Par exemple, pour renvoyer la LCA associée à l'objet paris.jpg dans le bucket example-travel-maps, utilisez la commande suivante :

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

Une réponse semblable aux lignes suivantes doit s'afficher :

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

Vous pouvez également utiliser la méthode JSON GET de la ressource ObjectAccessControls pour afficher une entrée de LCA spécifique.

Étapes suivantes