Version 1.40.0

• 2.17.0 (latest)
• 2.16.0
• 2.15.0
• 2.14.0
• 2.13.0
• 2.12.0
• 2.11.0
• 2.10.0
• 2.9.0
• 2.8.0
• 2.7.0
• 2.6.0
• 2.5.0
• 2.4.0
• 2.3.0
• 2.2.1
• 2.1.0
• 2.0.0
• 1.44.0
• 1.43.0
• 1.42.3
• 1.41.1
• 1.40.0
• 1.39.0
• 1.38.0
• 1.37.1
• 1.36.2
• 1.35.1
• 1.34.0
• 1.33.0
• 1.32.0
• 1.31.2
• 1.30.0
• 1.29.0
• 1.28.1
• 1.27.0
• 1.26.0
• 1.25.0
• 1.24.1
• 1.23.0
• 1.22.0
• 1.21.0
• 1.20.0
• 1.19.0
• 1.18.0
• 1.17.0

Conditional Requests Via Generation / Metageneration Preconditions

Preconditions tell Cloud Storage to only perform a request if the generation or metageneration number of the affected object meets your precondition criteria. These checks of the generation and metageneration numbers ensure that the object is in the expected state, allowing you to perform safe read-modify-write updates and conditional operations on objects

Concepts

Metageneration

When you create a Bucket, its metageneration is initialized to 1, representing the initial version of the bucket’s metadata.

When you first upload a Blob (“Object” in the GCS back-end docs), its 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.

Each time you patch or update the bucket’s / blob’s metadata, its metageneration is incremented.

Generation

Each time you upload a new version of a file to a Blob (“Object” in the GCS back-end docs), the Blob’s generation is changed, and its 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

• Storage API Generation Precondition docs

Conditional Parameters

Using if_generation_match

Passing the if_generation_match parameter to a method which retrieves a blob resource (e.g., Blob.reload) or modifies the blob (e.g., 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., Blob.reload) or modifies the blob (e.g., 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., Blob.reload, Bucket.reload) or modifies the blob or bucket (e.g., Blob.update 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., Blob.reload, Bucket.reload) or modifies the blob or bucket (e.g., Blob.update Bucket.patch) makes the operation conditional on whether the resource’s current metageneration does not match the given value.