Preconditions tell Cloud Storage to only perform a request if the generation <concept-generation>
or metageneration <concept-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
When you create a ~google.cloud.storage.bucket.Bucket
, its ~google.cloud.storage.bucket.Bucket.metageneration
is initialized to 1
, representing the initial version of the bucket's metadata.
When you first upload a ~google.cloud.storage.blob.Blob
("Object" in the GCS back-end docs), its ~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.
Each time you patch or update the bucket's / blob's metadata, its metageneration
is incremented.
Each time you upload a new version of a file to a ~google.cloud.storage.blob.Blob
("Object" in the GCS back-end docs), the Blob's ~google.cloud.storage.blob.generation
is changed, and its ~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.
Passing the if_generation_match
parameter to a method which retrieves a blob resource (e.g., Blob.reload <google.cloud.storage.blob.Blob.reload>
) or modifies the blob (e.g., 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 forif_generation_match
makes the operation succeed only if there are no live versions of the blob.
Passing the if_generation_not_match
parameter to a method which retrieves a blob resource (e.g., Blob.reload <google.cloud.storage.blob.Blob.reload>
) or modifies the blob (e.g., 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.
Passing the if_metageneration_match
parameter to a method which retrieves a blob or bucket resource (e.g., Blob.reload <google.cloud.storage.blob.Blob.reload>
, Bucket.reload <google.cloud.storage.bucket.Bucket.reload>
) or modifies the blob or bucket (e.g., Blob.update <google.cloud.storage.blob.Blob.update>
Bucket.patch <google.cloud.storage.bucket.Bucket.patch>
) makes the operation conditional on whether the resource's current metageneration
matches the given value.
Passing the if_metageneration_not_match
parameter to a method which retrieves a blob or bucket resource (e.g., Blob.reload <google.cloud.storage.blob.Blob.reload>
, Bucket.reload <google.cloud.storage.bucket.Bucket.reload>
) or modifies the blob or bucket (e.g., Blob.update <google.cloud.storage.blob.Blob.update>
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.