Conditional Requests Via ETag / Generation / Metageneration Preconditions¶
Preconditions tell Cloud Storage to only perform a request if the ETag, generation, or metageneration number of the affected object meets your precondition criteria. These checks of the ETag, 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¶
ETag¶
An ETag is returned as part of the response header whenever a resource is returned, as well as included in the resource itself. Users should make no assumptions about the value used in an ETag except that it changes whenever the underlying data changes, per the specification
The ETag attribute is set by the GCS back-end, and is read-only in the
client library.
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¶
Conditional Parameters¶
Using if_etag_match¶
Passing the if_etag_match parameter to a method which retrieves a
blob resource (e.g.,
Blob.reload)
makes the operation conditional on whether the blob’s current ETag matches
the given value. This parameter is not supported for modification (e.g.,
Blob.update).
Using if_etag_not_match¶
Passing the if_etag_not_match parameter to a method which retrieves a
blob resource (e.g.,
Blob.reload)
makes the operation conditional on whether the blob’s current ETag matches
the given value. This parameter is not supported for modification (e.g.,
Blob.update).
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.
