Key Terms

To use Cloud Storage effectively, you should understand some of the concepts on which it is built. This page provides an overview of key terms and concepts that apply to Cloud Storage.

For an introduction to using Cloud Storage, see the Quickstart Using the Console.

Projects

All data in Cloud Storage belongs inside a project. A project consists of a set of users, a set of APIs, and billing, authentication, and monitoring settings for those APIs. You can have one project or multiple projects.

Buckets

Buckets are the basic containers that hold your data. Everything that you store in Cloud Storage must be contained in a bucket. You can use buckets to organize your data and control access to your data, but unlike directories and folders, you cannot nest buckets. Because there are limits to bucket creation and deletion, you should design your storage applications to favor intensive object operations and relatively few buckets operations.

When you create a bucket, you specify a globally-unique name, a geographic location where the bucket and its contents are stored, and a default storage class. The default storage class you choose applies to objects added to the bucket that don't have a storage class specified explicitly.

After you create a bucket, you can still change its default storage class, to any class supported in the bucket's location; however, you can only change the bucket name and location by deleting and re-creating the bucket.

Bucket names

Bucket names have more restrictions than object names and must be globally unique, because every bucket resides in a single Cloud Storage namespace. Also, bucket names can be used with a CNAME redirect, which means they need to conform to DNS naming conventions. For more information, see the bucket naming guidelines.

Bucket labels

Bucket labels are key:value metadata pairs that allow you to group your buckets along with other Google Cloud Platform resources such as virtual machine instances and persistent disks. For example, you can use labels to create a team key that has values alpha, beta, and delta, and apply the team:alpha, team:beta, and team:delta labels to different buckets in order to indicate which team is associated with those buckets.

You can apply multiple labels to each bucket, with a maximum of 64 labels per bucket.

  • Keys and values cannot be longer than 63 characters each.
  • Keys and values can only contain lowercase letters, numeric characters, underscores, and dashes. International characters are allowed.
  • Label keys must start with a lowercase letter and international characters are allowed.
  • Label keys cannot be empty.

For a general example of using labels to organize your resources in billing, see Billing Export to BigQuery Query Examples.

Objects

Objects are the individual pieces of data that you store in Cloud Storage. There is no limit on the number of objects that you can create in a bucket.

Objects have two components: object data and object metadata. Object data is typically a file that you want to store in Cloud Storage. Object metadata is a collection of name-value pairs that describe various object qualities.

Object names

An object's name is treated as a piece of object metadata in Cloud Storage. Object names can contain any combination of Unicode characters (UTF-8 encoded) and must be less than 1024 bytes in length.

A common character to include in object names is a slash (/). By using slashes, you can make objects appear as though they're stored in a hierarchical structure. For example, you could name one object /europe/france/paris.jpg and another object /europe/france/cannes.jpg. When you list these objects, they appear to be in a hierarchical directory structure based on location; however, Cloud Storage sees the objects as independent with no hierarchical relationship whatsoever.

For more information, including how to rename an object, see the object naming guidelines.

Generation numbers

A generation number is a number associated with each object. Each time the object is overwritten, the generation number for the object changes. When your bucket contains multiple versions of the same object, such as when Object Versioning is enabled, you can use the generation number to refer to specific versions.

Resources

A resource is an entity within Google Cloud Platform. Each project, bucket, and object in Google Cloud Platform is a resource, as are things such as Compute Engine instances.

Resource names

Each resource has a unique name that identifies it, much like a filename. Buckets have a resource name in the form of projects/_/buckets/[BUCKET_NAME], where [BUCKET_NAME] is the ID of the bucket. Objects have a resource name in the form of projects/_/buckets/[BUCKET_NAME]/objects/[OBJECT_NAME], where [OBJECT_NAME] is the ID of the object.

A #[NUMBER] appended to the end of the resource name indicates a specific generation of the object. #0 is a special identifier for the most recent version of an object. #0 is useful to add when the name of the object ends in a string that would otherwise be interpreted as a generation number.

Data opacity

An object's data component is completely opaque to Cloud Storage. It is just a chunk of data to Cloud Storage.

Object immutability

Objects are immutable, which means that an uploaded object cannot change throughout its storage lifetime. An object's storage lifetime is the time between successful object creation (upload) and successful object deletion. In practice, this means that you cannot make incremental changes to objects, such as append operations or truncate operations. However, it is possible to overwrite objects that are stored in Cloud Storage, and doing so happens atomically — until the new upload completes the old version of the object will be served to readers, and after the upload completes the new version of the object will be served to readers. So a single overwrite operation simply marks the end of one immutable object's lifetime and the beginning of a new immutable object's lifetime.

There is no limit to how quickly you can create or update different objects in a bucket. However, a single particular object can only be updated or overwritten up to once per second. For example, if you have an object bar in bucket foo, then you should only upload a new copy of foo/bar about once per second. Updating the same object faster than once per second may result in 503 Service Unavailable errors.

You should retry failed requests using truncated exponential backoff.

Hierarchy

Cloud Storage uses a flat namespace to store objects. However, some tools (for example, Google Cloud Platform Console and gsutil) can work with objects as if they are stored in a virtual hierarchy, as a convenience.

Namespace

There is only one Cloud Storage namespace, which means every bucket must have a unique name across the entire Cloud Storage namespace. Object names must be unique only within a given bucket.

¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

¿Necesitas ayuda? Visita nuestra página de asistencia.