ACLs (Access Control Lists) erstellen und verwalten

Overview

Auf dieser Seite wird beschrieben, wie mithilfe von Access Control Lists (ACLs) der Zugriff auf Buckets und Objekte gesteuert wird. Mit ACLs bestimmen Sie, welche Nutzer auf Buckets und Objekte zugreifen können und welche Berechtigungen sie haben.

Weitere Informationen darüber, ob Sie ACLs zum Steuern des Zugriffs auf Ihre Ressourcen verwenden sollten, finden Sie in der ACL-Übersicht.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle "Storage-Administrator" (roles/storage.admin) für den Bucket zuzuweisen, der die gewünschten Objekte enthält, um die Berechtigungen zu erhalten, die Sie benötigen, wenn Sie ACLs erstellen und verwalten möchten.

Diese vordefinierte Rolle enthält die Berechtigungen, die zum Erstellen und Verwalten von ACLs erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

  • storage.buckets.get
  • storage.buckets.list
    • Diese Berechtigung ist nur erforderlich, um die Aufgaben auf dieser Seite mit der Google Cloud Console auszuführen.
  • storage.buckets.setIamPolicy
  • storage.buckets.update
  • storage.objects.get
  • storage.objects.getIamPolicy
  • storage.objects.setIamPolicy
  • storage.objects.update

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen erhalten.

Informationen zum Zuweisen von Rollen für Buckets finden Sie unter IAM mit Buckets verwenden.

ACLs festlegen oder ändern

Console

  1. Rufen Sie den Cloud Storage-Browser in der Google Cloud Console auf.
    Zum Cloud Storage-Browser

  2. Klicken Sie in der Liste der Buckets auf den Namen des Buckets mit dem Objekt, dessen ACL Sie ändern möchten.

  3. Klicken Sie auf den Namen des Objekts, für das Sie ACLs festlegen oder ändern möchten.

  4. Klicken Sie auf Zugriff bearbeiten.

    Ein Berechtigungs-Dialogfeld mit der aktuellen ACL des Objekts wird geöffnet.

  5. Klicken Sie auf + Eintrag hinzufügen.

  6. Wählen Sie die Entität aus, der Sie eine Berechtigung erteilen möchten.

    Eine Entität ist der Nutzer, die Gruppe oder eine andere Einheit, die eine Berechtigung erhalten soll. Eine Liste der für Entität unterstützten Werte finden Sie unter Access Control Lists (ACLs) im Abschnitt „Bereiche“.

  7. Geben Sie für Name einen Wert ein.

    Der Name bezeichnet den Nutzer, die Gruppe oder eine andere Art von Entität. Eine Liste der für Name unterstützten Werte finden Sie unter Zugriffsteuerungslisten im Abschnitt „Bereiche“.

    Entität und Name zusammen definieren den Empfänger der Berechtigung.

  8. Wählen Sie einen Wert für Zugriff aus.

    Unter Zugriff legen Sie die Berechtigung fest, die für das Objekt gelten soll. Eine Liste der für Zugriff unterstützten Werte finden Sie unter Access Control Lists (ACLs) im Abschnitt „Berechtigungen“.

  9. Klicken Sie auf Speichern.

Unter Fehlerbehebung erfahren Sie, wie Sie detaillierte Fehlerinformationen zu fehlgeschlagenen Cloud Storage-Vorgängen in der Google Cloud Console abrufen.

Befehlszeile

Verwenden Sie zum Hinzufügen, Ändern oder Entfernen einer einzelnen Zuweisung für ein Objekt den Befehl objects update mit dem relevanten Flag:

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

Wobei:

  • BUCKET_NAME ist der Name des Buckets, der das Objekt enthält, für das die Änderung gilt. Beispiel: example-travel-maps

  • OBJECT_NAME ist der Name des Objekts, auf das sich die Änderung bezieht. Beispiel: paris.jpg.

  • FLAG ist einer der folgenden Werte:

    • --add-acl-grant zusammen mit der Berechtigung, die Sie hinzufügen oder ändern möchten. Beispiel: --add-acl-grant=entity=user-jane@gmail.com,role=READER

    • --remove-acl-grant, zusammen mit der Entität, deren Zugriff Sie entfernen möchten. Beispiel: --remove-acl-grant=user-jane@gmail.com

So ersetzen Sie alle ACLs für ein Objekt:

  1. Definieren Sie die ACLs in einer JSON- oder YAML-formatierten Datei.

  2. Verwenden Sie den Befehl objects update mit dem Flag --acl-file:

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

    Wobei:

    • BUCKET_NAME ist der Name des Buckets, der das Objekt enthält, für das die ACLs gelten. Beispiel: example-travel-maps

    • OBJECT_NAME ist der Name des Objekts, auf das sich die ACLs beziehen. Beispiel: paris.jpg.

    • FILE_LOCATION ist der lokale Pfad zur Datei, die die von Ihnen definierten ACLs enthält. Beispiel: Desktop/acls.json

Der Inhalt einer ACL-Beispieldatei ist unten zu sehen. Diese ACLs gewähren den Inhabern von Projekt 867489160491 und dem Nutzer jane@gmail.com die Berechtigung OWNER für das Objekt paris.jpg und den Mitgliedern der Gruppe gs-announce die Berechtigung READER für dieses Objekt:

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

Clientbibliotheken

C++

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage C++ API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine ACL einem Objekt hinzugefügt:

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

Im folgenden Beispiel wird eine ACL aus einem Objekt entfernt:

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#

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage C# API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine ACL einem Objekt hinzugefügt:


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

Im folgenden Beispiel wird eine ACL aus einem Objekt entfernt:


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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Go API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine ACL einem Objekt hinzugefügt:

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
}

Im folgenden Beispiel wird eine ACL aus einem Objekt entfernt:

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Java API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine ACL einem Objekt hinzugefügt:


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

Im folgenden Beispiel wird eine ACL aus einem Objekt entfernt:


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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Node.js API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine ACL einem Objekt hinzugefügt:

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

Im folgenden Beispiel wird eine ACL aus einem Objekt entfernt:

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage PHP API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine ACL einem Objekt hinzugefügt:

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

Im folgenden Beispiel wird eine ACL aus einem Objekt entfernt:

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Python API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine ACL einem Objekt hinzugefügt:

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

Im folgenden Beispiel wird eine ACL aus einem Objekt entfernt:

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Ruby API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine ACL einem Objekt hinzugefügt:

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

Im folgenden Beispiel wird eine ACL aus einem Objekt entfernt:

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

REST APIs

JSON API

Beim Erstellen eines Objekts geben Sie im Anfragetext das Attribut acl[] oder in einer insert-Anfrage den Abfrageparameter predefinedAcl an. Für ein bestehendes Objekt geben Sie das Attribut acl[] oder den Abfrageparameter predefinedAcl in einer patch-Anfrage oder in einer update-Anfrage an.

Die Definition des Objekt-ACL-Attributs finden Sie in der Ressource ObjectAccessControls.

  1. Definieren Sie die ACLs in einer JSON-Datei.

    Wenn die ACL beispielsweise den Inhabern des Projekts 867489160491 und den Nutzern jane@gmail.com die Berechtigung OWNER sowie den Mitgliedern der Gruppe gs-announce die Berechtigung READER gewährt, dann können Sie eine Datei namens acls.json mit folgendem Inhalt haben:

    {
    "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. Senden Sie eine patch-Anfrage mit der JSON-Datei und geben Sie das Objekt an, für das die ACLs gelten sollen.

Mit dem folgenden cURL-Befehl wird beispielsweise eine JSON-Nutzlast aus dem Dokument acls.json auf ein Objekt namens paris.jpg im Bucket example-travel-maps angewendet:

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

XML API

In der XML API werden ACLs im XML-Format definiert. Zum Ändern von Bucket- und Objekt-ACLs hängen Sie ein XML-Dokument an den Anfragetext an. Wenn Sie Bucket- und Objekt-ACLs abrufen, wird ein XML-Dokument zurückgegeben. Dieses enthält die einzelnen ACL-Einträge der Buckets oder Objekte.

  • Nachdem Sie einen Bucket mit einer PUT-Bucket-Anfrage erstellt haben, verwenden Sie eine zweite PUT-Bucket-Anfrage mit dem Parameter ?acl, um die Bucket-ACL zu ändern.

  • Nachdem Sie ein Objekt mit einer PUT-Objekt-Anfrage hochgeladen haben, ändern Sie die ACL mit einer weiteren PUT-Anfrage mithilfe des ?acl- oder x-googl-acl-Anfrage-Headers.

Mit dem folgenden cURL-Befehl wird beispielsweise eine XML-Nutzlast aus dem Dokument acls.xml auf ein Objekt namens paris.jpg im Bucket example-travel-maps angewendet:

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

Verwenden Sie die folgende ACL-Syntax für das XML-Dokument.

Element Beschreibung
AccessControlList Container für Entries- und Owner-Elemente.
Owner Container für DisplayName- und ID-Elemente. Weil ein Objekt immer dem Nutzer gehört, der es hochgeladen hat, wird dieses Element für Objekte nicht benötigt. Es wird genutzt, wenn Sie die ACL-Syntax von Amazon S3 in einem Migrationsszenario verwenden.

Amazon Simple Storage Service und Amazon S3 sind Marken von Amazon.com, Inc. oder ihren Tochtergesellschaften in den Vereinigten Staaten und/oder anderen Ländern.
ID Die Cloud Storage-ID des Bucket-Inhabers.
DisplayName Nicht implementiert. Der Wert ist immer ein leerer String.
Entries Container für null oder mehr Entry-Elemente.
Entry Container für Scope- und Permission-Elemente. Ein Entry darf nur ein Scope- und ein Permission-Element enthalten.
Scope Container für ein ID-, EmailAddress- oder Domain-Element, das den ACL-Bereich definiert. Dieses Element muss ein type-Attribut haben, das einen der folgenden Werte enthält: UserByID, UserByEmail, GroupByID, GroupByEmail, GroupByDomain, AllUsers oder AllAuthenticatedUsers.
ID Kennzeichnet den Empfänger, wenn für den Berechtigungseintrag eine ID angegeben wird.
EmailAddress Die E-Mail-Adresse des Empfängers, wenn für den Berechtigungseintrag eine E-Mail-Adresse angegeben wird.
Domain Die Domain des Empfängers, wenn für den Berechtigungseintrag eine Domain angegeben wird.
Name Optionales Element, das angegeben oder auch automatisch hinzugefügt werden kann, wenn der Geltungsbereich UserByEmail oder GroupByEmail lautet.
Permission Die erteilte Berechtigung: READ , WRITE oder FULL_CONTROL.

Beachten Sie Folgendes, wenn Sie ACLs mithilfe der XML API bearbeiten:

  • Nur das oben beschriebene XML-Format kann verwendet werden.
  • Gleiche Geltungsbereiche können nicht festgelegt werden.

    Das ACL-XML kann viele Einträge enthalten, unzulässig sind jedoch Einträge mit gleichem Geltungsbereich. Es darf zum Beispiel keine zwei Einträge geben, die beide das Bereichselement jane@example.com enthalten.

Das folgende Beispiel zeigt unterschiedliche Bucket-ACL-Einträge:

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

Das Element "Name" in ACL-XML festlegen

Achten Sie beim Betrachten der ACL eines Buckets oder Objekts darauf, dass einigen der Einträge das zusätzliche Element <Name> angefügt ist. So ein Eintrag sieht zum Beispiel so aus:

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

Diese optionalen <Name>-Elemente werden in zwei Fällen hinzugefügt:

  1. Wenn die ACLs des Buckets oder Objekts <Name> als Element enthalten.

    Wenn Sie ACLs festlegen, können Sie das Element <Name> in Ihre ACL-Einträge aufnehmen. Sie können einen beliebigen Wert im Element <Name> angeben. Cloud Storage merkt sich diese Werte dann, bis die ACL entfernt oder ersetzt wird. Diese Methode kann nützlich sein, wenn Sie komplizierte Kennzeichnungen verwenden.

  2. Wenn ein UserByEmail- oder GroupByEmail-Bereich ein öffentliches Google-Profil enthält.

    Wenn Sie einen dieser Geltungsbereiche verwenden, aber kein <Name>-Element angeben, prüft Cloud Storage, ob es für den Nutzer oder die Google Group, dem bzw. der diese E-Mail-Adresse gehört, ein öffentliches Google-Profil mit einem öffentlichen Namen gibt. Wenn ja, wird der öffentliche Name von Cloud Storage automatisch für das <Name>-Element übernommen.

Vordefinierte ACL anwenden

Anstatt wie oben gezeigt die gesamte ACL Eintrag für Eintrag zu spezifizieren, können Sie eine vordefinierte ACL verwenden, die automatisch eine Reihe von Einträgen anwendet, die für ein bestimmtes Szenario angepasst sind. Sie können eine vordefinierte ACL entweder über die Google Cloud CLI, die JSON API oder die XML API auf einen Bucket oder ein Objekt anwenden.

Für neue Objekte

So wenden Sie eine vordefinierte ACL während des Objektuploads auf ein Objekt an:

Console

Sie können eine vordefinierte ACL nicht über die Google Cloud Console anwenden. Verwenden Sie stattdessen gcloud storage.

Befehlszeile

Führen Sie den Befehl gcloud storage cp mit dem Flag --predefined-acl aus:

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

So wenden Sie beispielsweise den vordefinierten ACL-bucketOwnerRead beim Hochladen einer Objekt-paris.jpg in einen Bucket-example-travel-maps an:

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

REST APIs

JSON API

Verwenden Sie den Abfragestringparameter predefinedAcl in einer insert-Anfrage, um die vordefinierte ACL anzuwenden.

So wenden Sie beispielsweise den vordefinierten ACL-bucketOwnerRead beim Hochladen einer Objekt-paris.jpg in einen Bucket-example-travel-maps an:

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"

XML API

Verwenden Sie den Header x-goog-acl in einer PUT-Objekt-Anfrage, um die vordefinierte ACL anzuwenden.

So wenden Sie beispielsweise den vordefinierten ACL-bucket-owner-read beim Hochladen einer Objekt-paris.jpg in einen Bucket-example-travel-maps an:

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

Für vorhandene Buckets oder Objekte

Eine vordefinierte ACL kann auch auf vorhandene Buckets oder Objekte angewendet werden. Dies ist nützlich, wenn Sie eine vordefinierte ACL oder eine benutzerdefinierte ACL durch eine (andere) vordefinierte ACL ersetzen möchten.

Console

Sie können eine vordefinierte ACL nicht über die Google Cloud Console anwenden. Verwenden Sie stattdessen gcloud storage.

Befehlszeile

Verwenden Sie den Befehl objects update mit dem Flag --predefined-acl:

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

So wenden Sie beispielsweise den vordefinierten ACL-private auf das Objekt paris.jpg im Bucket example-travel-maps an:

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

REST APIs

JSON API

Verwenden Sie den Abfragestringparameter predefinedAcl und geben Sie in einer patch-Anfrage ein leeres acl-Attribut an, um die vordefinierte ACL anzuwenden.

So wenden Sie beispielsweise den vordefinierten ACL-private auf das Objekt paris.jpg im Bucket example-travel-maps an:

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

XML API

Verwenden Sie den Header x-goog-acl mit dem Abfragestringparameter acl in einer Put Object-Anfrage, aber nehmen Sie kein XML-Dokument in die Anfrage auf.

So wenden Sie beispielsweise den vordefinierten ACL-private auf das Objekt paris.jpg im Bucket example-travel-maps an:

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

Standard-Objekt-ACLs festlegen

Damit Sie nicht für jedes neu erstellte Objekt eine ACL festlegen müssen, können Sie für Buckets Standard-Objekt-ACLs definieren. Jedem neuen Objekt, das dem Bucket hinzugefügt wird und das nicht bereits über eine ACL verfügt, wird automatisch diese Standard-ACL zugewiesen. Damit könnten Sie zum Beispiel festlegen, dass auf die meisten Objekte in einem bestimmten Bucket nur eine bestimmte Nutzergruppe Zugriff haben soll. Sie können die Standard-Objekt-ACL ändern und dann Objekte zum Bucket hinzufügen. Diese erhalten automatisch die Standard-Objekt-ACL, die Sie angegeben haben. Sie können einzelnen Objekten aber auch andere ACLs zuweisen, sodass diese dann nicht die Standard-ACL erhalten.

Die Standard-Objekt-ACL für einen Bucket anzeigen und ändern:

Console

Sie können Standardobjekt-ACLs nicht über die Google Cloud Console festlegen. Verwenden Sie stattdessen gcloud storage.

Befehlszeile

  1. Verwenden Sie den Befehl buckets describe mit dem Flag --format, um die Standard-Objekt-ACL für den Bucket abzurufen:

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

    Dabei ist BUCKET_NAME der Name des Buckets, dessen Standard-Objekt-ACL Sie aufrufen möchten. Beispiel: my-bucket.

  2. Verwenden Sie den Befehl buckets update mit dem gewünschten Flag, um die Standard-Objekt-ACL für den Bucket zu ändern:

    gcloud storage buckets update gs://BUCKET_NAME FLAG

    Wobei:

    • BUCKET_NAME ist der Name des Buckets, dessen Standard-Objekt-ACL Sie ändern möchten. Beispiel: my-bucket

    • FLAG ist einer der folgenden Werte:

      • --add-default-object-acl-grant und eine Zuweisung, die Sie der allgemeinen Standard-Objekt-ACL für den Bucket hinzufügen möchten.

      • --default-object-acl-file und den Pfad zu einer lokalen Datei, die eine neue Standardobjekt-ACL für den Bucket definiert.

      • --predefined-default-object-acl und den Namen einer vordefinierten Objekt-ACL, mit der Sie die vorhandene Standardobjekt-ACL für den Bucket ersetzen möchten.

      • --remove-default-object-acl-grant und eine Entität, die Sie aus der Standard-Objekt-ACL für den Bucket entfernen möchten.

Clientbibliotheken

C++

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage C++ API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine Standardobjekt-ACL einem Bucket hinzugefügt:

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

Im folgenden Beispiel wird die Standard-Objekt-ACL eines Buckets gelöscht:

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#

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage C# API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird die Standard-Objekt-ACL für einen Bucket ausgegeben:


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

Im folgenden Beispiel wird eine Standardobjekt-ACL einem Bucket hinzugefügt:


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

Im folgenden Beispiel wird die Standard-Objekt-ACL eines Buckets gelöscht:


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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Go API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine Standardobjekt-ACL einem Bucket hinzugefügt:

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
}

Im folgenden Beispiel wird die Standard-Objekt-ACL eines Buckets gelöscht:

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Java API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine Standardobjekt-ACL einem Bucket hinzugefügt:


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

Im folgenden Beispiel wird die Standard-Objekt-ACL eines Buckets gelöscht:


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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Node.js API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine Standardobjekt-ACL einem Bucket hinzugefügt:

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

Im folgenden Beispiel wird die Standard-Objekt-ACL eines Buckets gelöscht:

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage PHP API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine Standardobjekt-ACL einem Bucket hinzugefügt:

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

Im folgenden Beispiel wird die Standard-Objekt-ACL eines Buckets gelöscht:

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Python API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine Standardobjekt-ACL einem Bucket hinzugefügt:

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

Im folgenden Beispiel wird die Standard-Objekt-ACL eines Buckets gelöscht:

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Ruby API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine Standardobjekt-ACL einem Bucket hinzugefügt:

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

Im folgenden Beispiel wird die Standard-Objekt-ACL eines Buckets gelöscht:

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

REST APIs

JSON API

  1. Die Standard-Objekt-ACL rufen Sie mit einer GET-Anfrage ab. Beispiel:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?projection=full
    
  2. Verwenden Sie eine Patch-Anfrage, um die Standard-Objekt-ACL zu ersetzen. Die folgende Anfrage ersetzt beispielsweise die Standard-Objekt-ACL durch die in defacls.json angegebene ACL für ein 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
    

    Ein Beispiel für defacls.json:

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

XML API

  1. Rufen Sie die Standard-Objekt-ACL mit einer auf Ihren Bucket beschränkten GET-Anfrage und dem Parameter ?defaultObjectAcl ab. Beispiel:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        https://storage.googleapis.com/BUCKET_NAME?defaultObjectAcl
    
  2. Verwenden Sie eine auf Ihren Bucket beschränkte PUT-Anfrage mit dem Parameter ?defaultObjectAcl, um die Standard-Objekt-ACL durch die in acls.xml angegebene ACL zu ersetzen. Beispiel:

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

    Ein Beispiel für acls.xml:

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

Die ACL-Syntax wird unter ACLs festlegen beschrieben. Es ist auch möglich, eine vordefinierte ACL als Standard-Objekt-ACL festzulegen.

So legen Sie eine vordefinierte ACL als Standard-Objekt-ACL für einen Bucket fest:

Console

Sie können Standardobjekt-ACLs nicht über die Google Cloud Console festlegen. Verwenden Sie stattdessen gcloud storage.

Befehlszeile

Führen Sie den Befehl buckets update mit dem Flag --predefined-default-object-acl aus.

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

Wobei:

  • BUCKET_NAME ist der Name des Buckets, dessen Standard-Objekt-ACL Sie ändern möchten. Beispiel: my-bucket

  • PREDEFINED_ACL ist der Name einer gültigen vordefinierten ACL. Beispiel: projectPrivate.

REST APIs

JSON API

Verwenden Sie eine PUT-Anfrage und den Parameter predefinedAcl.

Beispiel:

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

XML API

Verwenden Sie eine auf Ihren Bucket beschränkte PUT-Anfrage mit dem Parameter ?defaultObjectAcl und dem Header x-goog-acl.

Beispiel:

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

Standard-Objekt-ACLs für neu erstellte Buckets:

Die folgenden Beispiele zeigen die Standard-Objekt-ACLs, die automatisch für neu erstellte Buckets gelten, wenn Sie keine eigenen Standard-Objekt-ACLs als Teil der Anfrage angeben. Wenn Sie sehen möchten, ob die Standard-Objekt-ACLs Ihres Buckets geändert wurden, vergleichen Sie die aktuellen Standard-Objekt-ACLs Ihres Buckets mit den folgenden Beispielen.

Console

Sie können über die Google Cloud Console nicht mit Standardobjekt-ACLs arbeiten. Verwenden Sie stattdessen gcloud storage.

Befehlszeile

Im folgenden Beispiel lautet die Projekt-ID "123412341234". Ihre Projekt-ID wird anders lauten.

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

REST APIs

JSON API

Im folgenden Beispiel lautet die Projekt-ID "123412341234". Ihre Projekt-ID wird anders lauten.

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

XML API

Im folgenden Beispiel beginnen die Projektrollen-IDs mit "00b4903a97...". Ihre IDs werden anders lauten.

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

Beachten Sie, dass die Standard-Objekt-ACL für einen neu erstellten Bucket der vordefinierten projectPrivate-ACL entspricht.

ACLs abrufen

So rufen Sie die ACL einer vorhandenen Ressource ab:

Console

  1. Rufen Sie den Cloud Storage-Browser in der Google Cloud Console auf.
    Zum Cloud Storage-Browser

  2. Rufen Sie das Objekt auf, dessen ACL angezeigt werden soll.

  3. Wählen Sie im Drop-down-Menü für das Objekt Bearbeitungszugriff aus.

    Ein Dialogfeld mit den Berechtigungen des Objekts wird angezeigt.

Unter Fehlerbehebung erfahren Sie, wie Sie detaillierte Fehlerinformationen zu fehlgeschlagenen Cloud Storage-Vorgängen in der Google Cloud Console abrufen.

Befehlszeile

  1. Verwenden Sie den Befehl objects describe mit dem Flag --format, um die ACL eines Objekts abzurufen:

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

    Wobei:

    • BUCKET_NAME ist der Name des Buckets, der das Objekt enthält, dessen ACL Sie ansehen möchten. Beispiel: my-bucket

    • OBJECT_NAME ist der Name des Objekts, dessen ACL Sie aufrufen möchten. Beispiel: paris.jpg.

Clientbibliotheken

C++

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage C++ API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine Objekt-ACL abgerufen:

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#

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage C# API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine Objekt-ACL abgerufen:


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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Go API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine Objekt-ACL abgerufen:

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Java API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine Objekt-ACL abgerufen:


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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Node.js API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine Objekt-ACL abgerufen:

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage PHP API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine Objekt-ACL abgerufen:

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Python API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine Objekt-ACL abgerufen:

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Ruby API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine Objekt-ACL abgerufen:

# 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

REST APIs

JSON API

  1. Sie benötigen die Berechtigung OWNER für das Objekt.

  2. Rufen Sie die Objekt-ACL mithilfe einer GET-Anfrage ab.

    Die Objekt-ACL wird im JSON-Format als Anhang zum Antworttext geliefert.

So fügen Sie beispielsweise die ACL für das Objekt paris.jpg wieder in den Bucket example-travel-maps ein:

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

Die Antwort sollte so aussehen:

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

Sie können auch die GET-Methode der objectAccessControls-Ressource verwenden, um einzelne Einträge in der ACL eines Objekts abzurufen.

XML API

  1. Sie benötigen eine FULL_CONTROL-Berechtigung für den Bucket bzw. das Objekt.

  2. Rufen Sie die Bucket- oder Objekt-ACL mit dem acl-Abfragestringparameter in einer GET Object-Anfrage ab.

Die ACLs sind in XML definiert und an den Antworttext angefügt.

So fügen Sie beispielsweise die ACL für das Objekt paris.jpg wieder in den Bucket example-travel-maps ein:

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

Die Antwort sollte so aussehen:

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

Sie können auch die JSON-GET-Methode der ObjectAccessControls verwenden, um einen bestimmten ACL-Eintrag zurückzugeben.

Nächste Schritte