Buckets, objects, and ACLs
A bucket is the storage location you read files from and write files to. You must always specify a bucket when using the App Engine client library for Cloud Storage. Your project can access multiple buckets. Note that the client library doesn't support bucket creation.
Access control lists (ACLs) control access to the buckets and to the objects contained in them. Your project and your App Engine app are automatically added to the ACL that permits bucket access when you create a bucket in your project.
Note that the ACL that permits bucket access is distinct from the potentially many ACLs governing the objects in that bucket. Thus, your app has read and write privileges to the bucket(s) it is activated for, but it only has full rights to the objects it creates in the bucket. Your app's access to objects created by other apps or persons is limited to the rights given to your app by the objects' creator.
If an object is created in the bucket without an ACL explicitly defined for it,
it uses the default object ACL assigned to the bucket by the bucket owner. If
the bucket owner has not specified a default object ACL, the object default is
public-read, which means that anyone allowed bucket access can read the object.
ACLs and the client library
An app using the client library cannot change the bucket ACL, but it can specify an ACL that controls access to the objects it creates. The available ACL settings are described under documentation for the open method.Modifying Cloud Storage objects
Once you create an object in a bucket, you cannot modify or append to it. Instead, you must overwrite the object with a new object of the same name that contains your desired changes.
Cloud Storage and subdirectories
The App Engine client library for Cloud Storage lets you supply subdirectory delimiters when you create an object, but there are no true subdirectories in Cloud Storage. Instead, a subdirectory in Cloud Storage is a part of the object filename.
For example, you might assume that creating an object
somewhere/over/the/rainbow.mp3 would store the file rainbow.mp3 in the
subdirectory somewhere/over/the/. Instead, the object name is set to
somewhere/over/the/rainbow.mp3.
This concept is important to understand when using listbucket filtering.
If the above listing behavior is not optimal for you, listbucket
has an optional directory emulation mode. See
listbucket
for more information.
What's next
- Visit the API Reference documentation.
- Learn how to set up Cloud Storage.