ACL

Manipulate access control lists that Cloud Storage provides.

google.cloud.storage.bucket.Bucket has a getting method that creates an ACL object under the hood, and you can interact with that using google.cloud.storage.bucket.Bucket.acl():

 client = storage.Client()
 bucket = client.get_bucket(bucket_name)
 acl = bucket.acl

Adding and removing permissions can be done with the following methods (in increasing order of granularity):

  • ACL.all() corresponds to access for all users.

  • ACL.all_authenticated() corresponds to access for all users that are signed into a Google account.

  • ACL.domain() corresponds to access on a per Google Apps domain (ie, example.com).

  • ACL.group() corresponds to access on a per group basis (either by ID or e-mail address).

  • ACL.user() corresponds to access on a per user basis (either by ID or e-mail address).

And you are able to grant and revoke the following roles:

  • Reading: _ACLEntity.grant_read() and _ACLEntity.revoke_read()

  • Writing: _ACLEntity.grant_write() and _ACLEntity.revoke_write()

  • Owning: _ACLEntity.grant_owner() and _ACLEntity.revoke_owner()

You can use any of these like any other factory method (these happen to be _ACLEntity factories):

 acl.user("me@example.org").grant_read()
 acl.all_authenticated().grant_write()

After that, you can save any changes you make with the google.cloud.storage.acl.ACL.save() method:

 acl.save()

You can alternatively save any existing google.cloud.storage.acl.ACL object (whether it was created by a factory method or not) from a google.cloud.storage.bucket.Bucket:

 bucket.acl.save(acl=acl)

To get the list of entity and role for each unique pair, the ACL class is iterable:

 print(list(acl))
 # [{'role': 'OWNER', 'entity': 'allUsers'}, ...]

This list of tuples can be used as the entity and role fields when sending metadata for ACLs to the API.

class google.cloud.storage.acl.ACL()

Bases: object

Container class representing a list of access controls.

PREDEFINED_JSON_ACLS( = frozenset({'authenticatedRead', 'bucketOwnerFullControl', 'bucketOwnerRead', 'private', 'projectPrivate', 'publicRead', 'publicReadWrite'} )

See https://cloud.google.com/storage/docs/access-control/lists#predefined-acl

add_entity(entity)

Add an entity to the ACL.

  • Parameters

    entity (_ACLEntity) – The entity to add to this ACL.

all()

Factory method for an Entity representing all users.

  • Return type

    _ACLEntity

  • Returns

    An entity representing all users.

all_authenticated()

Factory method for an Entity representing all authenticated users.

  • Return type

    _ACLEntity

  • Returns

    An entity representing all authenticated users.

clear(client=None, timeout=60)

Remove all ACL entries.

If user_project is set, bills the API request to that project.

Note that this won’t actually remove ALL the rules, but it will remove all the non-default rules. In short, you’ll still have access to a bucket that you created even after you clear ACL rules with this method.

  • Parameters

    • client (Client or NoneType) – (Optional) The client to use. If not passed, falls back to the client stored on the ACL’s parent.

    • timeout (float* or [tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait for the server response.

      Can also be passed as a tuple (connect_timeout, read_timeout). See requests.Session.request() documentation for details.

property client()

Abstract getter for the object client.

domain(domain)

Factory method for a domain Entity.

  • Parameters

    domain (str) – The domain for this entity.

  • Return type

    _ACLEntity

  • Returns

    An entity corresponding to this domain.

entity(entity_type, identifier=None)

Factory method for creating an Entity.

If an entity with the same type and identifier already exists, this will return a reference to that entity. If not, it will create a new one and add it to the list of known entities for this ACL.

  • Parameters

    • entity_type (str) – The type of entity to create (ie, user, group, etc)

    • identifier (str) – The ID of the entity (if applicable). This can be either an ID or an e-mail address.

  • Return type

    _ACLEntity

  • Returns

    A new Entity or a reference to an existing identical entity.

entity_from_dict(entity_dict)

Build an _ACLEntity object from a dictionary of data.

An entity is a mutable object that represents a list of roles belonging to either a user or group or the special types for all users and all authenticated users.

  • Parameters

    entity_dict (dict) – Dictionary full of data from an ACL lookup.

  • Return type

    _ACLEntity

  • Returns

    An Entity constructed from the dictionary.

get_entities()

Get a list of all Entity objects.

  • Return type

    list of _ACLEntity objects

  • Returns

    A list of all Entity objects.

get_entity(entity, default=None)

Gets an entity object from the ACL.

  • Parameters

    • entity (_ACLEntity or string) – The entity to get lookup in the ACL.

    • default (anything) – This value will be returned if the entity doesn’t exist.

  • Return type

    _ACLEntity

  • Returns

    The corresponding entity or the value provided to default.

group(identifier)

Factory method for a group Entity.

  • Parameters

    identifier (str) – An id or e-mail for this particular group.

  • Return type

    _ACLEntity

  • Returns

    An Entity corresponding to this group.

has_entity(entity)

Returns whether or not this ACL has any entries for an entity.

  • Parameters

    entity (_ACLEntity) – The entity to check for existence in this ACL.

  • Return type

    bool

  • Returns

    True of the entity exists in the ACL.

reload(client=None, timeout=60)

Reload the ACL data from Cloud Storage.

If user_project is set, bills the API request to that project.

  • Parameters

    • client (Client or NoneType) – (Optional) The client to use. If not passed, falls back to the client stored on the ACL’s parent.

    • timeout (float* or [tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait for the server response.

      Can also be passed as a tuple (connect_timeout, read_timeout). See requests.Session.request() documentation for details.

reset()

Remove all entities from the ACL, and clear the loaded flag.

save(acl=None, client=None, timeout=60)

Save this ACL for the current bucket.

If user_project is set, bills the API request to that project.

  • Parameters

    • acl (google.cloud.storage.acl.ACL, or a compatible list.) – The ACL object to save. If left blank, this will save current entries.

    • client (Client or NoneType) – (Optional) The client to use. If not passed, falls back to the client stored on the ACL’s parent.

    • timeout (float* or [tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait for the server response.

      Can also be passed as a tuple (connect_timeout, read_timeout). See requests.Session.request() documentation for details.

save_predefined(predefined, client=None, timeout=60)

Save this ACL for the current bucket using a predefined ACL.

If user_project is set, bills the API request to that project.

  • Parameters

    • predefined (str) – An identifier for a predefined ACL. Must be one of the keys in PREDEFINED_JSON_ACLS or PREDEFINED_XML_ACLS (which will be aliased to the corresponding JSON name). If passed, acl must be None.

    • client (Client or NoneType) – (Optional) The client to use. If not passed, falls back to the client stored on the ACL’s parent.

    • timeout (float* or [tuple*](https://python.readthedocs.io/en/latest/library/stdtypes.html#tuple)) – (Optional) The amount of time, in seconds, to wait for the server response.

      Can also be passed as a tuple (connect_timeout, read_timeout). See requests.Session.request() documentation for details.

user(identifier)

Factory method for a user Entity.

  • Parameters

    identifier (str) – An id or e-mail for this particular user.

  • Return type

    _ACLEntity

  • Returns

    An Entity corresponding to this user.

classmethod validate_predefined(predefined)

Ensures predefined is in list of predefined json values

  • Parameters

    • predefined (str) – name of a predefined acl

    • predefined – validated JSON name of predefined acl

  • Raises

    • exc

      ValueError: If predefined is not a valid acl

class google.cloud.storage.acl.BucketACL(bucket)

Bases: google.cloud.storage.acl.ACL

An ACL specifically for a bucket.

property client()

The client bound to this ACL’s bucket.

property reload_path()

Compute the path for GET API requests for this ACL.

property save_path()

Compute the path for PATCH API requests for this ACL.

property user_project()

Compute the user project charged for API requests for this ACL.

class google.cloud.storage.acl.DefaultObjectACL(bucket)

Bases: google.cloud.storage.acl.BucketACL

A class representing the default object ACL for a bucket.

class google.cloud.storage.acl.ObjectACL(blob)

Bases: google.cloud.storage.acl.ACL

An ACL specifically for a Cloud Storage object / blob.

property client()

The client bound to this ACL’s blob.

property reload_path()

Compute the path for GET API requests for this ACL.

property save_path()

Compute the path for PATCH API requests for this ACL.

property user_project()

Compute the user project charged for API requests for this ACL.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025年10月10日 UTC.