Skip to content

Latest commit

 

History

History
114 lines (82 loc) · 3.97 KB

generation_metageneration.rst

File metadata and controls

114 lines (82 loc) · 3.97 KB
Raw

Conditional Requests Via Generation / Metageneration

Concepts

Metageneration

When you create a :class:`~google.cloud.storage.bucket.Bucket`, its :attr:`~google.cloud.storage.bucket.Bucket.metageneration` is initialized to 1, representing the initial version of the bucket's metadata.

When you first upload a :class:`~google.cloud.storage.blob.Blob` ("Object" in the GCS back-end docs), its :attr:`~google.cloud.storage.blob.Blob.metageneration` is likewise initialized to 1. representing the initial version of the blob's metadata.

The metageneration attribute is set by the GCS back-end, and is read-only in the client library.

WHenever you patch or update the bucket / blob's metadata, its metageneration is incremented.

Generation

Each time you upload a new version of a file to a :class:`~google.cloud.storage.blob.Blob` ("Object" in the GCS back-end docs), the Blob's :attr:`~google.cloud.storage.blob.generation` is increased, and its :attr:`~google.cloud.storage.blob.metageneration` is reset to 1 (the first metadata version for that generation of the blob).

The generation attribute is set by the GCS back-end, and is read-only in the client library.

See also

Conditional Parameters

Using if_generation_match

Passing the if_generation_match parameter to a method which retrieves a blob resource (e.g., :meth:`Blob.reload <google.cloud.storage.blob.Blob.reload>`) or modifies the blob (e.g., :meth:`Blob.update <google.cloud.storage.blob.Blob.update>`) makes the operation conditional on whether the blob's current generation matches the given value.

As a special case, passing 0 as the value for``if_generation_match`` makes the operation succeed only if there are no live versions of the blob.

Using if_generation_not_match

Passing the if_generation_not_match parameter to a method which retrieves a blob resource (e.g., :meth:`Blob.reload <google.cloud.storage.blob.Blob.reload>`) or modifies the blob (e.g., :meth:`Blob.update <google.cloud.storage.blob.Blob.update>`) makes the operation conditional on whether the blob's current generation does not match the given value.

If no live version of the blob exists, the precondition fails.

As a special case, passing 0 as the value for if_generation_not_match makes the operation succeed only if there is a live version of the blob.

Using if_metageneration_match

Passing the if_metageneration_match parameter to a method which retrieves a blob or bucket resource (e.g., :meth:`Blob.reaload <google.cloud.storage.blob.Blob.reload>`, :meth:`Bucket.reload <google.cloud.storage.bucket.Bucket.reload>`) or modifies the blob or bucket (e.g., :meth:`Blob.update <google.cloud.storage.blob.Blob.update>` :meth:`Bucket.patch <google.cloud.storage.bucket.Bucket.patch>`) makes the operation conditional on whether the resource's current metageneration matches the given value.

Using if_metageneration_not_match

Passing the if_metageneration_not_match parameter to a method which retrieves a blob or bucket resource (e.g., :meth:`Blob.reaload <google.cloud.storage.blob.Blob.reload>`, :meth:`Bucket.reload <google.cloud.storage.bucket.Bucket.reload>`) or modifies the blob or bucket (e.g., :meth:`Blob.update <google.cloud.storage.blob.Blob.update>` :meth:`Bucket.patch <google.cloud.storage.bucket.Bucket.patch>`) makes the operation conditional on whether the resource's current metageneration does not match the given value.