Class Blob (2.6.0)
- 3.5.0 (latest)
- 3.4.1
- 3.3.1
- 3.2.0
- 3.1.1
- 3.0.0
- 2.19.0
- 2.17.0
- 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
Blob(name,bucket,chunk_size=None,encryption_key=None,kms_key_name=None,generation=None,)A wrapper around Cloud Storage's concept of anObject.
Parameters | |
|---|---|
| Name | Description |
name | strThe name of the blob. This corresponds to the unique path of the object in the bucket. If bytes, will be converted to a unicode object. Blob / object names can contain any sequence of valid unicode characters, of length 1-1024 bytes when UTF-8 encoded. |
bucket | BucketThe bucket to which this blob belongs. |
chunk_size | int(Optional) The size of a chunk of data whenever iterating (in bytes). This must be a multiple of 256 KB per the API specification. If not specified, the chunk_size of the blob itself is used. If that is not specified, a default value of 40 MB is used. |
encryption_key | bytes(Optional) 32 byte encryption key for customer-supplied encryption. Seehttps://cloud.google.com/storage/docs/encryption#customer-supplied. |
kms_key_name | str(Optional) Resource name of Cloud KMS key used to encrypt the blob's contents. |
generation | long(Optional) If present, selects a specific revision of this object. |
Properties
acl
Create our ACL on demand.
bucket
Bucket which contains the object.
| Returns | |
|---|---|
| Type | Description |
Bucket | The object's bucket. |
cache_control
Scalar property getter.
chunk_size
Get the blob's default chunk size.
| Returns | |
|---|---|
| Type | Description |
int or | The current blob's chunk size, if it is set. |
client
The client bound to this blob.
component_count
Number of underlying components that make up this object.
Seehttps://cloud.google.com/storage/docs/json_api/v1/objects
| Returns | |
|---|---|
| Type | Description |
int or | The component count (in case of a composed object) orNone if the blob's resource has not been loaded from the server. This property will not be set on objects not created viacompose. |
content_disposition
Scalar property getter.
content_encoding
Scalar property getter.
content_language
Scalar property getter.
content_type
Scalar property getter.
crc32c
Scalar property getter.
custom_time
Retrieve the custom time for the object.
Seehttps://cloud.google.com/storage/docs/json_api/v1/objects
| Returns | |
|---|---|
| Type | Description |
| Datetime object parsed from RFC3339 valid timestamp, orNone if the blob's resource has not been loaded from the server (seereload). |
encryption_key
Retrieve the customer-supplied encryption key for the object.
| Returns | |
|---|---|
| Type | Description |
bytes or | The encryption key orNone if no customer-supplied encryption key was used, or the blob's resource has not been loaded from the server. |
etag
Retrieve the ETag for the object.
| Returns | |
|---|---|
| Type | Description |
str or | The blob etag orNone if the blob's resource has not been loaded from the server. |
event_based_hold
Scalar property getter.
generation
Retrieve the generation for the object.
Seehttps://cloud.google.com/storage/docs/json_api/v1/objects
| Returns | |
|---|---|
| Type | Description |
int or | The generation of the blob orNone if the blob's resource has not been loaded from the server. |
id
Retrieve the ID for the object.
Seehttps://cloud.google.com/storage/docs/json_api/v1/objects
The ID consists of the bucket name, object name, and generation number.
| Returns | |
|---|---|
| Type | Description |
str or | The ID of the blob orNone if the blob's resource has not been loaded from the server. |
kms_key_name
Resource name of Cloud KMS key used to encrypt the blob's contents.
| Returns | |
|---|---|
| Type | Description |
str or | The resource name orNone if no Cloud KMS key was used, or the blob's resource has not been loaded from the server. |
md5_hash
Scalar property getter.
media_link
Retrieve the media download URI for the object.
Seehttps://cloud.google.com/storage/docs/json_api/v1/objects
| Returns | |
|---|---|
| Type | Description |
str or | The media link for the blob orNone if the blob's resource has not been loaded from the server. |
metadata
Retrieve arbitrary/application specific metadata for the object.
Seehttps://cloud.google.com/storage/docs/json_api/v1/objects
:setter: Update arbitrary/application specific metadata for the object.:getter: Retrieve arbitrary/application specific metadata for the object.
| Returns | |
|---|---|
| Type | Description |
dict or | The metadata associated with the blob orNone if the property is not set. |
metageneration
Retrieve the metageneration for the object.
Seehttps://cloud.google.com/storage/docs/json_api/v1/objects
| Returns | |
|---|---|
| Type | Description |
int or | The metageneration of the blob orNone if the blob's resource has not been loaded from the server. |
owner
Retrieve info about the owner of the object.
Seehttps://cloud.google.com/storage/docs/json_api/v1/objects
| Returns | |
|---|---|
| Type | Description |
dict or | Mapping of owner's role/ID, orNone if the blob's resource has not been loaded from the server. |
path
Getter property for the URL path to this Blob.
| Returns | |
|---|---|
| Type | Description |
str | The URL path to this Blob. |
public_url
The public URL for this blob.
Usemake_public to enable anonymous access via the returnedURL.
| Returns | |
|---|---|
| Type | Description |
| The public URL for this blob. |
retention_expiration_time
Retrieve timestamp at which the object's retention period expires.
Seehttps://cloud.google.com/storage/docs/json_api/v1/objects
| Returns | |
|---|---|
| Type | Description |
| Datetime object parsed from RFC3339 valid timestamp, orNone if the property is not set locally. |
self_link
Retrieve the URI for the object.
Seehttps://cloud.google.com/storage/docs/json_api/v1/objects
| Returns | |
|---|---|
| Type | Description |
str or | The self link for the blob orNone if the blob's resource has not been loaded from the server. |
size
Size of the object, in bytes.
Seehttps://cloud.google.com/storage/docs/json_api/v1/objects
| Returns | |
|---|---|
| Type | Description |
int or | The size of the blob orNone if the blob's resource has not been loaded from the server. |
storage_class
Scalar property getter.
temporary_hold
Scalar property getter.
time_created
Retrieve the timestamp at which the object was created.
Seehttps://cloud.google.com/storage/docs/json_api/v1/objects
| Returns | |
|---|---|
| Type | Description |
| Datetime object parsed from RFC3339 valid timestamp, orNone if the blob's resource has not been loaded from the server (seereload). |
time_deleted
Retrieve the timestamp at which the object was deleted.
Seehttps://cloud.google.com/storage/docs/json_api/v1/objects
| Returns | |
|---|---|
| Type | Description |
| Datetime object parsed from RFC3339 valid timestamp, orNone if the blob's resource has not been loaded from the server (seereload). If the blob has not been deleted, this will never be set. |
updated
Retrieve the timestamp at which the object was updated.
Seehttps://cloud.google.com/storage/docs/json_api/v1/objects
| Returns | |
|---|---|
| Type | Description |
| Datetime object parsed from RFC3339 valid timestamp, orNone if the blob's resource has not been loaded from the server (seereload). |
user_project
Project ID billed for API requests made via this blob.
Derived from bucket's value.
Methods
Blob
Blob(name,bucket,chunk_size=None,encryption_key=None,kms_key_name=None,generation=None,)propertyname Get the blob's name.
compose
compose(sources,client=None,timeout=60,if_generation_match=None,if_metageneration_match=None,if_source_generation_match=None,retry=<google.cloud.storage.retry.ConditionalRetryPolicyobject>)Concatenate source blobs into this one.
Ifuser_project is set on the bucket, bills the API requestto that project.
SeeAPI reference docsand acode sample.
| Parameters | |
|---|---|
| Name | Description |
sources | list ofBlobs whose contents will be composed into this blob. |
client | Client(Optional) The client to use. If not passed, falls back to the |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
if_generation_match | long(Optional) Makes the operation conditional on whether the destination object's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the object. Note: In a previous version, this argument worked identically to the |
if_metageneration_match | long(Optional) Makes the operation conditional on whether the destination object's current metageneration matches the given value. If a list of long is passed in, no match operation will be performed. (Deprecated: type(list of long) is supported for backwards-compatability reasons only.) |
if_source_generation_match | list of long(Optional) Makes the operation conditional on whether the current generation of each source blob matches the corresponding generation. The list must match |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. See: |
create_resumable_upload_session
create_resumable_upload_session(content_type=None,size=None,origin=None,client=None,timeout=60,checksum=None,predefined_acl=None,if_generation_match=None,if_generation_not_match=None,if_metageneration_match=None,if_metageneration_not_match=None,retry=<google.cloud.storage.retry.ConditionalRetryPolicyobject>)Create a resumable upload session.
Resumable upload sessions allow you to start an upload session fromone client and complete the session in another. This method is calledby the initiator to set the metadata and limits. The initiator thenpasses the session URL to the client that will upload the binary data.The client performs a PUT request on the session URL to complete theupload. This process allows untrusted clients to upload to anaccess-controlled bucket.
For more details, see thedocumentation onsigned URLs.
The content type of the upload will be determined in orderof precedence:
- The value passed in to this method (if not :data:
None) - The value stored on the current blob
- The default value ('application/octet-stream')
object versioning andlifecycle API documents for details.Ifencryption_key is set, the blob will be encrypted withacustomer-suppliedencryption key.
Ifuser_project is set on the bucket, bills the API requestto that project.
| Parameters | |
|---|---|
| Name | Description |
size | int(Optional) The maximum number of bytes that can be uploaded using this session. If the size is not known when creating the session, this should be left blank. |
content_type | str(Optional) Type of content being uploaded. |
origin | str(Optional) If set, the upload can only be completed by a user-agent that uploads from the given origin. This can be useful when passing the session to a web client. |
client | Client(Optional) The client to use. If not passed, falls back to the |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
checksum | str(Optional) The type of checksum to compute to verify the integrity of the object. After the upload is complete, the server-computed checksum of the resulting object will be checked and google.resumable_media.common.DataCorruption will be raised on a mismatch. On a validation failure, the client will attempt to delete the uploaded object automatically. Supported values are "md5", "crc32c" and None. The default is None. |
predefined_acl | str(Optional) Predefined access control list |
if_generation_match | long(Optional) See :ref: |
if_generation_not_match | long(Optional) See :ref: |
if_metageneration_match | long(Optional) See :ref: |
if_metageneration_not_match | long(Optional) See :ref: |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. A None value will disable retries. A google.api_core.retry.Retry value will enable retries, and the object will define retriable response codes and errors and configure backoff and timeout options. Agoogle.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and activates it only if certain conditions are met. This class exists to provide safe defaults for RPC calls that are not technically safe to retry normally (due to potential data duplication or other side-effects) but become safe to retry if a condition such as if_generation_match is set. See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for information on retry types and how to configure them. Media operations (downloads and uploads) do not support non-default predicates in a Retry object. The default will always be used. Other configuration changes for Retry objects such as delays and deadlines are respected. |
| Exceptions | |
|---|---|
| Type | Description |
GoogleCloudError | if the session creation response returns an error status. |
| Returns | |
|---|---|
| Type | Description |
str | The resumable upload session URL. The upload can be completed by making an HTTP PUT request with the file's contents. |
delete
delete(client=None,if_generation_match=None,if_generation_not_match=None,if_metageneration_match=None,if_metageneration_not_match=None,timeout=60,retry=<google.cloud.storage.retry.ConditionalRetryPolicyobject>)Deletes a blob from Cloud Storage.
Ifuser_project is set on the bucket, bills the API requestto that project.
| Parameters | |
|---|---|
| Name | Description |
client | Client(Optional) The client to use. If not passed, falls back to the |
if_generation_match | long(Optional) See :ref: |
if_generation_not_match | long(Optional) See :ref: |
if_metageneration_match | long(Optional) See :ref: |
if_metageneration_not_match | long(Optional) See :ref: |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. See: |
| Exceptions | |
|---|---|
| Type | Description |
NotFound | (propagated fromdelete_blob). |
download_as_bytes
download_as_bytes(client=None,start=None,end=None,raw_download=False,if_etag_match=None,if_etag_not_match=None,if_generation_match=None,if_generation_not_match=None,if_metageneration_match=None,if_metageneration_not_match=None,timeout=60,checksum='md5',retry=<google.api_core.retry.Retryobject>)Download the contents of this blob as a bytes object.
Ifuser_project is set on the bucket, bills the API requestto that project.
| Parameters | |
|---|---|
| Name | Description |
client | Client(Optional) The client to use. If not passed, falls back to the |
start | int(Optional) The first byte in a range to be downloaded. |
end | int(Optional) The last byte in a range to be downloaded. |
raw_download | bool(Optional) If true, download the object without any expansion. |
if_etag_match | Union[str, Set[str]](Optional) See :ref: |
if_etag_not_match | Union[str, Set[str]](Optional) See :ref: |
if_generation_match | long(Optional) See :ref: |
if_generation_not_match | long(Optional) See :ref: |
if_metageneration_match | long(Optional) See :ref: |
if_metageneration_not_match | long(Optional) See :ref: |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
checksum | str(Optional) The type of checksum to compute to verify the integrity of the object. The response headers must contain a checksum of the requested type. If the headers lack an appropriate checksum (for instance in the case of transcoded or ranged downloads where the remote service does not know the correct checksum, including downloads where chunk_size is set) an INFO-level log will be emitted. Supported values are "md5", "crc32c" and None. The default is "md5". |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. A None value will disable retries. A google.api_core.retry.Retry value will enable retries, and the object will define retriable response codes and errors and configure backoff and timeout options. Agoogle.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and activates it only if certain conditions are met. This class exists to provide safe defaults for RPC calls that are not technically safe to retry normally (due to potential data duplication or other side-effects) but become safe to retry if a condition such as if_metageneration_match is set. See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for information on retry types and how to configure them. Media operations (downloads and uploads) do not support non-default predicates in a Retry object. The default will always be used. Other configuration changes for Retry objects such as delays and deadlines are respected. |
| Exceptions | |
|---|---|
| Type | Description |
NotFound | |
| Returns | |
|---|---|
| Type | Description |
bytes | The data stored in this blob. |
download_as_string
download_as_string(client=None,start=None,end=None,raw_download=False,if_etag_match=None,if_etag_not_match=None,if_generation_match=None,if_generation_not_match=None,if_metageneration_match=None,if_metageneration_not_match=None,timeout=60,retry=<google.api_core.retry.Retryobject>)(Deprecated) Download the contents of this blob as a bytes object.
Ifuser_project is set on the bucket, bills the API requestto that project.
download_as_bytes.| Parameters | |
|---|---|
| Name | Description |
client | Client(Optional) The client to use. If not passed, falls back to the |
start | int(Optional) The first byte in a range to be downloaded. |
end | int(Optional) The last byte in a range to be downloaded. |
raw_download | bool(Optional) If true, download the object without any expansion. |
if_etag_match | Union[str, Set[str]](Optional) See :ref: |
if_etag_not_match | Union[str, Set[str]](Optional) See :ref: |
if_generation_match | long(Optional) See :ref: |
if_generation_not_match | long(Optional) See :ref: |
if_metageneration_match | long(Optional) See :ref: |
if_metageneration_not_match | long(Optional) See :ref: |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. A None value will disable retries. A google.api_core.retry.Retry value will enable retries, and the object will define retriable response codes and errors and configure backoff and timeout options. Agoogle.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and activates it only if certain conditions are met. This class exists to provide safe defaults for RPC calls that are not technically safe to retry normally (due to potential data duplication or other side-effects) but become safe to retry if a condition such as if_metageneration_match is set. See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for information on retry types and how to configure them. Media operations (downloads and uploads) do not support non-default predicates in a Retry object. The default will always be used. Other configuration changes for Retry objects such as delays and deadlines are respected. |
| Exceptions | |
|---|---|
| Type | Description |
NotFound | |
| Returns | |
|---|---|
| Type | Description |
bytes | The data stored in this blob. |
download_as_text
download_as_text(client=None,start=None,end=None,raw_download=False,encoding=None,if_etag_match=None,if_etag_not_match=None,if_generation_match=None,if_generation_not_match=None,if_metageneration_match=None,if_metageneration_not_match=None,timeout=60,retry=<google.api_core.retry.Retryobject>)Download the contents of this blob as text (not bytes).
Ifuser_project is set on the bucket, bills the API requestto that project.
| Parameters | |
|---|---|
| Name | Description |
client | Client(Optional) The client to use. If not passed, falls back to the |
start | int(Optional) The first byte in a range to be downloaded. |
end | int(Optional) The last byte in a range to be downloaded. |
raw_download | bool(Optional) If true, download the object without any expansion. |
encoding | str(Optional) encoding to be used to decode the downloaded bytes. Defaults to the |
if_etag_match | Union[str, Set[str]](Optional) See :ref: |
if_etag_not_match | Union[str, Set[str]](Optional) See :ref: |
if_generation_match | long(Optional) See :ref: |
if_generation_not_match | long(Optional) See :ref: |
if_metageneration_match | long(Optional) See :ref: |
if_metageneration_not_match | long(Optional) See :ref: |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. A None value will disable retries. A google.api_core.retry.Retry value will enable retries, and the object will define retriable response codes and errors and configure backoff and timeout options. Agoogle.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and activates it only if certain conditions are met. This class exists to provide safe defaults for RPC calls that are not technically safe to retry normally (due to potential data duplication or other side-effects) but become safe to retry if a condition such as if_metageneration_match is set. See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for information on retry types and how to configure them. Media operations (downloads and uploads) do not support non-default predicates in a Retry object. The default will always be used. Other configuration changes for Retry objects such as delays and deadlines are respected. |
| Returns | |
|---|---|
| Type | Description |
text | The data stored in this blob, decoded to text. |
download_to_file
download_to_file(file_obj,client=None,start=None,end=None,raw_download=False,if_etag_match=None,if_etag_not_match=None,if_generation_match=None,if_generation_not_match=None,if_metageneration_match=None,if_metageneration_not_match=None,timeout=60,checksum='md5',retry=<google.api_core.retry.Retryobject>)DEPRECATED. Download the contents of this blob into a file-like object.
Note:If the server-set property,media_link, is not yetinitialized, makes an additional API request to load it.For more fine-grained control over the download process, check outgoogle-resumable-media.For example, this library allows downloadingparts of a blob rather than the whole thing.Ifuser_project is set on the bucket, bills the API requestto that project.
| Parameters | |
|---|---|
| Name | Description |
file_obj | fileA file handle to which to write the blob's data. |
client | Client(Optional) The client to use. If not passed, falls back to the |
start | int(Optional) The first byte in a range to be downloaded. |
end | int(Optional) The last byte in a range to be downloaded. |
raw_download | bool(Optional) If true, download the object without any expansion. |
if_etag_match | Union[str, Set[str]](Optional) See :ref: |
if_etag_not_match | Union[str, Set[str]](Optional) See :ref: |
if_generation_match | long(Optional) See :ref: |
if_generation_not_match | long(Optional) See :ref: |
if_metageneration_match | long(Optional) See :ref: |
if_metageneration_not_match | long(Optional) See :ref: |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
checksum | str(Optional) The type of checksum to compute to verify the integrity of the object. The response headers must contain a checksum of the requested type. If the headers lack an appropriate checksum (for instance in the case of transcoded or ranged downloads where the remote service does not know the correct checksum, including downloads where chunk_size is set) an INFO-level log will be emitted. Supported values are "md5", "crc32c" and None. The default is "md5". |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. A None value will disable retries. A google.api_core.retry.Retry value will enable retries, and the object will define retriable response codes and errors and configure backoff and timeout options. Agoogle.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and activates it only if certain conditions are met. This class exists to provide safe defaults for RPC calls that are not technically safe to retry normally (due to potential data duplication or other side-effects) but become safe to retry if a condition such as if_metageneration_match is set. See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for information on retry types and how to configure them. Media operations (downloads and uploads) do not support non-default predicates in a Retry object. The default will always be used. Other configuration changes for Retry objects such as delays and deadlines are respected. |
| Exceptions | |
|---|---|
| Type | Description |
NotFound | |
download_to_filename
download_to_filename(filename,client=None,start=None,end=None,raw_download=False,if_etag_match=None,if_etag_not_match=None,if_generation_match=None,if_generation_not_match=None,if_metageneration_match=None,if_metageneration_not_match=None,timeout=60,checksum='md5',retry=<google.api_core.retry.Retryobject>)Download the contents of this blob into a named file.
Ifuser_project is set on the bucket, bills the API requestto that project.
See acode sampleto download a file with acustomer-supplied encryption key.
| Parameters | |
|---|---|
| Name | Description |
filename | strA filename to be passed to |
client | Client(Optional) The client to use. If not passed, falls back to the |
start | int(Optional) The first byte in a range to be downloaded. |
end | int(Optional) The last byte in a range to be downloaded. |
raw_download | bool(Optional) If true, download the object without any expansion. |
if_etag_match | Union[str, Set[str]](Optional) See :ref: |
if_etag_not_match | Union[str, Set[str]](Optional) See :ref: |
if_generation_match | long(Optional) See :ref: |
if_generation_not_match | long(Optional) See :ref: |
if_metageneration_match | long(Optional) See :ref: |
if_metageneration_not_match | long(Optional) See :ref: |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
checksum | str(Optional) The type of checksum to compute to verify the integrity of the object. The response headers must contain a checksum of the requested type. If the headers lack an appropriate checksum (for instance in the case of transcoded or ranged downloads where the remote service does not know the correct checksum, including downloads where chunk_size is set) an INFO-level log will be emitted. Supported values are "md5", "crc32c" and None. The default is "md5". |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. A None value will disable retries. A google.api_core.retry.Retry value will enable retries, and the object will define retriable response codes and errors and configure backoff and timeout options. Agoogle.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and activates it only if certain conditions are met. This class exists to provide safe defaults for RPC calls that are not technically safe to retry normally (due to potential data duplication or other side-effects) but become safe to retry if a condition such as if_metageneration_match is set. See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for information on retry types and how to configure them. Media operations (downloads and uploads) do not support non-default predicates in a Retry object. The default will always be used. Other configuration changes for Retry objects such as delays and deadlines are respected. |
| Exceptions | |
|---|---|
| Type | Description |
NotFound | |
exists
exists(client=None,if_etag_match=None,if_etag_not_match=None,if_generation_match=None,if_generation_not_match=None,if_metageneration_match=None,if_metageneration_not_match=None,timeout=60,retry=<google.api_core.retry.Retryobject>)Determines whether or not this blob exists.
Ifuser_project is set on the bucket, bills the API requestto that project.
| Parameters | |
|---|---|
| Name | Description |
client | Client(Optional) The client to use. If not passed, falls back to the |
if_etag_match | Union[str, Set[str]](Optional) See :ref: |
if_etag_not_match | Union[str, Set[str]](Optional) See :ref: |
if_generation_match | long(Optional) See :ref: |
if_generation_not_match | long(Optional) See :ref: |
if_metageneration_match | long(Optional) See :ref: |
if_metageneration_not_match | long(Optional) See :ref: |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. See: |
| Returns | |
|---|---|
| Type | Description |
bool | True if the blob exists in Cloud Storage. |
from_string
from_string(uri,client=None)Get a constructor for blob object by URI.
from google.cloud importstoragefrom google.cloud.storage.blob importBlobclient =storage.Client()blob =Blob.from_string("gs://bucket/object", client=client)| Parameters | |
|---|---|
| Name | Description |
uri | strThe blob uri pass to get blob object. |
client | Client(Optional) The client to use. Application code shouldalways pass |
| Returns | |
|---|---|
| Type | Description |
Blob | The blob object created. |
generate_signed_url
generate_signed_url(expiration=None,api_access_endpoint="https://storage.googleapis.com",method="GET",content_md5=None,content_type=None,response_disposition=None,response_type=None,generation=None,headers=None,query_parameters=None,client=None,credentials=None,version=None,service_account_email=None,access_token=None,virtual_hosted_style=False,bucket_bound_hostname=None,scheme="http",)Generates a signed URL for this blob.
Note:If you are on Google Compute Engine, you can't generate a signedURL using GCE service account.If you'd like to be able to generate a signed URL from GCE,you can use a standard service account from a JSON file ratherthan a GCE service account.See acode sample.This is particularly useful if you don't want publiclyaccessible blobs, but don't want to require users to explicitlylog in.
Ifbucket_bound_hostname is set as an argument ofapi_access_endpoint,https works only if using aCDN.
| Parameters | |
|---|---|
| Name | Description |
expiration | Union[Integer, datetime.datetime, datetime.timedelta]Point in time when the signed URL should expire. If a |
api_access_endpoint | str(Optional) URI base. |
method | strThe HTTP verb that will be used when requesting the URL. |
content_md5 | str(Optional) The MD5 hash of the object referenced by |
content_type | str(Optional) The content type of the object referenced by |
response_disposition | str(Optional) Content disposition of responses to requests for the signed URL. For example, to enable the signed URL to initiate a file of |
response_type | str(Optional) Content type of responses to requests for the signed URL. Ignored if content_type is set on object/blob metadata. |
generation | str(Optional) A value that indicates which generation of the resource to fetch. |
headers | dict(Optional) Additional HTTP headers to be included as part of the signed URLs. See:https://cloud.google.com/storage/docs/xml-api/reference-headers Requests using the signed URLmust pass the specified header (name and value) with each request for the URL. |
query_parameters | dict(Optional) Additional query parameters to be included as part of the signed URLs. See:https://cloud.google.com/storage/docs/xml-api/reference-headers#query |
client | Client(Optional) The client to use. If not passed, falls back to the |
credentials | (Optional) The authorization credentials to attach to requests. These credentials identify this application to the service. If none are specified, the client will attempt to ascertain the credentials from the environment. |
version | str(Optional) The version of signed credential to create. Must be one of 'v2' 'v4'. |
service_account_email | str(Optional) E-mail address of the service account. |
access_token | str(Optional) Access token for a service account. |
virtual_hosted_style | bool(Optional) If true, then construct the URL relative the bucket's virtual hostname, e.g., ' |
bucket_bound_hostname | str(Optional) If passed, then construct the URL relative to the bucket-bound hostname. Value can be a bare or with scheme, e.g., 'example.com' or 'http://example.com'. See:https://cloud.google.com/storage/docs/request-endpoints#cname |
scheme | str(Optional) If |
| Exceptions | |
|---|---|
| Type | Description |
`ValueError | when version is invalid. |
`TypeError | when expiration is not a valid type. |
`AttributeError | if credentials is not an instance ofgoogle.auth.credentials.Signing. |
| Returns | |
|---|---|
| Type | Description |
str | A signed URL you can use to access the resource until expiration. |
get_iam_policy
get_iam_policy(client=None,requested_policy_version=None,timeout=60,retry=<google.api_core.retry.Retryobject>)Retrieve the IAM policy for the object.
Note:Blob- / object-level IAM support does not yet exist and methodscurrently call an internal ACL backend not providing any utilitybeyond the blob'sacl at this time. The API may be enhancedin the future and is currently undocumented. Useacl formanaging object access control.| Parameters | |
|---|---|
| Name | Description |
client | Client(Optional) The client to use. If not passed, falls back to the |
requested_policy_version | int or(Optional) The version of IAM policies to request. If a policy with a condition is requested without setting this, the server will return an error. This must be set to a value of 3 to retrieve IAM policies containing conditions. This is to prevent client code that isn't aware of IAM conditions from interpreting and modifying policies incorrectly. The service might return a policy with version lower than the one that was requested, based on the feature syntax in the policy fetched. |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. See: |
| Returns | |
|---|---|
| Type | Description |
| the policy instance, based on the resource returned from thegetIamPolicy API request. |
make_private
make_private(client=None,timeout=60,if_generation_match=None,if_generation_not_match=None,if_metageneration_match=None,if_metageneration_not_match=None,retry=<google.cloud.storage.retry.ConditionalRetryPolicyobject>)Update blob's ACL, revoking read access for anonymous users.
| Parameters | |
|---|---|
| Name | Description |
client | Client or(Optional) The client to use. If not passed, falls back to the |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
if_generation_match | long(Optional) See :ref: |
if_generation_not_match | long(Optional) See :ref: |
if_metageneration_match | long(Optional) See :ref: |
if_metageneration_not_match | long(Optional) See :ref: |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. See: |
make_public
make_public(client=None,timeout=60,if_generation_match=None,if_generation_not_match=None,if_metageneration_match=None,if_metageneration_not_match=None,retry=<google.cloud.storage.retry.ConditionalRetryPolicyobject>)Update blob's ACL, granting read access to anonymous users.
| Parameters | |
|---|---|
| Name | Description |
client | Client or(Optional) The client to use. If not passed, falls back to the |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
if_generation_match | long(Optional) See :ref: |
if_generation_not_match | long(Optional) See :ref: |
if_metageneration_match | long(Optional) See :ref: |
if_metageneration_not_match | long(Optional) See :ref: |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. See: |
open
open(mode="r",chunk_size=None,ignore_flush=None,encoding=None,errors=None,newline=None,**kwargs)Create a file handler for file-like I/O to or from this blob.
This method can be used as a context manager, just like Python'sbuilt-in 'open()' function.
While reading, as with other read methods, if blob.generation is not setthe most recent blob generation will be used. Because the file-like IOreader downloads progressively in chunks, this could result in data frommultiple versions being mixed together. If this is a concern, useeither bucket.get_blob(), or blob.reload(), which will download thelatest generation number and set it; or, if the generation is known, setit manually, for instance with bucket.blob(generation=123456).
Checksumming (hashing) to verify data integrity is disabled for readsusing this feature because reads are implemented using request ranges,which do not provide checksums to validate. Seehttps://cloud.google.com/storage/docs/hashes-etags for details.
See acode sample.
Keyword arguments to pass to the underlying API calls.For both uploads and downloads, the following arguments aresupported:
if_generation_matchif_generation_not_matchif_metageneration_matchif_metageneration_not_matchtimeoutretry
For downloads only, the following additional arguments are supported:
raw_download
For uploads only, the following additional arguments are supported:
content_typenum_retriespredefined_aclchecksum
num_retries is supported for backwards-compatibilityreasons only; please useretry with a Retry object orConditionalRetryPolicy instead.| Parameters | |
|---|---|
| Name | Description |
mode | str(Optional) A mode string, as per standard Python |
chunk_size | long(Optional) For reads, the minimum number of bytes to read at a time. If fewer bytes than the chunk_size are requested, the remainder is buffered. For writes, the maximum number of bytes to buffer before sending data to the server, and the size of each request when data is sent. Writes are implemented as a "resumable upload", so chunk_size for writes must be exactly a multiple of 256KiB as with other resumable uploads. The default is 40 MiB. |
ignore_flush | bool(Optional) For non text-mode writes, makes flush() do nothing instead of raising an error. flush() without closing is not supported by the remote service and therefore calling it normally results in io.UnsupportedOperation. However, that behavior is incompatible with some consumers and wrappers of file objects in Python, such as zipfile.ZipFile or io.TextIOWrapper. Setting ignore_flush will cause flush() to successfully do nothing, for compatibility with those contexts. The correct way to actually flush data to the remote server is to close() (using a context manager, such as in the example, will cause this to happen automatically). |
encoding | str(Optional) For text mode only, the name of the encoding that the stream will be decoded or encoded with. If omitted, it defaults to locale.getpreferredencoding(False). |
errors | str(Optional) For text mode only, an optional string that specifies how encoding and decoding errors are to be handled. Pass 'strict' to raise a ValueError exception if there is an encoding error (the default of None has the same effect), or pass 'ignore' to ignore errors. (Note that ignoring encoding errors can lead to data loss.) Other more rarely-used options are also available; see the Python 'io' module documentation for 'io.TextIOWrapper' for a complete list. |
newline | str(Optional) For text mode only, controls how line endings are handled. It can be None, '', '\n', '\r', and '\r\n'. If None, reads use "universal newline mode" and writes use the system default. See the Python 'io' module documentation for 'io.TextIOWrapper' for details. |
patch
patch(client=None,if_generation_match=None,if_generation_not_match=None,if_metageneration_match=None,if_metageneration_not_match=None,timeout=60,retry=<google.cloud.storage.retry.ConditionalRetryPolicyobject>)Sends all changed properties in a PATCH request.
Updates the_properties with the response from the backend.
Ifuser_project is set, bills the API request to that project.
| Parameters | |
|---|---|
| Name | Description |
client | Client orthe client to use. If not passed, falls back to the |
if_generation_match | long(Optional) See :ref: |
if_generation_not_match | long(Optional) See :ref: |
if_metageneration_match | long(Optional) See :ref: |
if_metageneration_not_match | long(Optional) See :ref: |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. See: |
path_helper
path_helper(bucket_path,blob_name)Relative URL path for a blob.
| Parameters | |
|---|---|
| Name | Description |
bucket_path | strThe URL path for a bucket. |
blob_name | strThe name of the blob. |
| Returns | |
|---|---|
| Type | Description |
str | The relative URL path forblob_name. |
reload
reload(client=None,projection='noAcl',if_etag_match=None,if_etag_not_match=None,if_generation_match=None,if_generation_not_match=None,if_metageneration_match=None,if_metageneration_not_match=None,timeout=60,retry=<google.api_core.retry.Retryobject>)Reload properties from Cloud Storage.
Ifuser_project is set, bills the API request to that project.
| Parameters | |
|---|---|
| Name | Description |
client | Client orthe client to use. If not passed, falls back to the |
projection | str(Optional) If used, must be 'full' or 'noAcl'. Defaults to |
if_etag_match | Union[str, Set[str]](Optional) See :ref: |
if_etag_not_match | Union[str, Set[str]])(Optional) See :ref: |
if_generation_match | long(Optional) See :ref: |
if_generation_not_match | long(Optional) See :ref: |
if_metageneration_match | long(Optional) See :ref: |
if_metageneration_not_match | long(Optional) See :ref: |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. See: |
rewrite
rewrite(source,token=None,client=None,if_generation_match=None,if_generation_not_match=None,if_metageneration_match=None,if_metageneration_not_match=None,if_source_generation_match=None,if_source_generation_not_match=None,if_source_metageneration_match=None,if_source_metageneration_not_match=None,timeout=60,retry=<google.cloud.storage.retry.ConditionalRetryPolicyobject>)Rewrite source blob into this one.
Ifuser_project is set on the bucket, bills the API requestto that project.
| Parameters | |
|---|---|
| Name | Description |
source | blob whose contents will be rewritten into this blob. |
token | str(Optional) Token returned from an earlier, not-completed call to rewrite the same source blob. If passed, result will include updated status, total bytes written. |
client | Client(Optional) The client to use. If not passed, falls back to the |
if_generation_match | long(Optional) See :ref: |
if_generation_not_match | long(Optional) See :ref: |
if_metageneration_match | long(Optional) See :ref: |
if_metageneration_not_match | long(Optional) See :ref: |
if_source_generation_match | long(Optional) Makes the operation conditional on whether the source object's generation matches the given value. |
if_source_generation_not_match | long(Optional) Makes the operation conditional on whether the source object's generation does not match the given value. |
if_source_metageneration_match | long(Optional) Makes the operation conditional on whether the source object's current metageneration matches the given value. |
if_source_metageneration_not_match | long(Optional) Makes the operation conditional on whether the source object's current metageneration does not match the given value. |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. See: |
| Returns | |
|---|---|
| Type | Description |
tuple | (token, bytes_rewritten, total_bytes), wheretoken is a rewrite token (None if the rewrite is complete),bytes_rewritten is the number of bytes rewritten so far, andtotal_bytes is the total number of bytes to be rewritten. |
set_iam_policy
set_iam_policy(policy,client=None,timeout=60,retry=<google.cloud.storage.retry.ConditionalRetryPolicyobject>)Update the IAM policy for the bucket.
Note:Blob- / object-level IAM support does not yet exist and methodscurrently call an internal ACL backend not providing any utilitybeyond the blob'sacl at this time. The API may be enhancedin the future and is currently undocumented. Useacl formanaging object access control.| Parameters | |
|---|---|
| Name | Description |
policy | policy instance used to update bucket's IAM policy. |
client | Client(Optional) The client to use. If not passed, falls back to the |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. See: |
| Returns | |
|---|---|
| Type | Description |
| the policy instance, based on the resource returned from thesetIamPolicy API request. |
test_iam_permissions
test_iam_permissions(permissions,client=None,timeout=60,retry=<google.api_core.retry.Retryobject>)| Parameters | |
|---|---|
| Name | Description |
permissions | list of stringthe permissions to check |
client | Client(Optional) The client to use. If not passed, falls back to the |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. See: |
| Returns | |
|---|---|
| Type | Description |
list of string | the permissions returned by thetestIamPermissions API request. |
update
update(client=None,if_generation_match=None,if_generation_not_match=None,if_metageneration_match=None,if_metageneration_not_match=None,timeout=60,retry=<google.cloud.storage.retry.ConditionalRetryPolicyobject>)Sends all properties in a PUT request.
Updates the_properties with the response from the backend.
Ifuser_project is set, bills the API request to that project.
| Parameters | |
|---|---|
| Name | Description |
client | Client orthe client to use. If not passed, falls back to the |
if_generation_match | long(Optional) See :ref: |
if_generation_not_match | long(Optional) See :ref: |
if_metageneration_match | long(Optional) See :ref: |
if_metageneration_not_match | long(Optional) See :ref: |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. See: |
update_storage_class
update_storage_class(new_class,client=None,if_generation_match=None,if_generation_not_match=None,if_metageneration_match=None,if_metageneration_not_match=None,if_source_generation_match=None,if_source_generation_not_match=None,if_source_metageneration_match=None,if_source_metageneration_not_match=None,timeout=60,retry=<google.cloud.storage.retry.ConditionalRetryPolicyobject>)Update blob's storage class via a rewrite-in-place. This helper willwait for the rewrite to complete before returning, so it may take sometime for large files.
Seehttps://cloud.google.com/storage/docs/per-object-storage-class
Ifuser_project is set on the bucket, bills the API requestto that project.
| Parameters | |
|---|---|
| Name | Description |
new_class | strnew storage class for the object. One of:NEARLINE_STORAGE_CLASS,COLDLINE_STORAGE_CLASS,ARCHIVE_STORAGE_CLASS,STANDARD_STORAGE_CLASS,MULTI_REGIONAL_LEGACY_STORAGE_CLASS, orREGIONAL_LEGACY_STORAGE_CLASS. |
client | Client(Optional) The client to use. If not passed, falls back to the |
if_generation_match | long(Optional) See :ref: |
if_generation_not_match | long(Optional) See :ref: |
if_metageneration_match | long(Optional) See :ref: |
if_metageneration_not_match | long(Optional) See :ref: |
if_source_generation_match | long(Optional) Makes the operation conditional on whether the source object's generation matches the given value. |
if_source_generation_not_match | long(Optional) Makes the operation conditional on whether the source object's generation does not match the given value. |
if_source_metageneration_match | long(Optional) Makes the operation conditional on whether the source object's current metageneration matches the given value. |
if_source_metageneration_not_match | long(Optional) Makes the operation conditional on whether the source object's current metageneration does not match the given value. |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. See: |
upload_from_file
upload_from_file(file_obj,rewind=False,size=None,content_type=None,num_retries=None,client=None,predefined_acl=None,if_generation_match=None,if_generation_not_match=None,if_metageneration_match=None,if_metageneration_not_match=None,timeout=60,checksum=None,retry=<google.cloud.storage.retry.ConditionalRetryPolicyobject>)Upload the contents of this blob from a file-like object.
The content type of the upload will be determined in orderof precedence:
- The value passed in to this method (if not :data:
None) - The value stored on the current blob
- The default value ('application/octet-stream')
object versioning andlifecycle API documents for details.If the size of the data to be uploaded exceeds 8 MB a resumable mediarequest will be used, otherwise the content and the metadata will beuploaded in a single multipart upload request.
For more fine-grained over the upload process, check outgoogle-resumable-media.
Ifuser_project is set on the bucket, bills the API requestto that project.
| Parameters | |
|---|---|
| Name | Description |
file_obj | fileA file handle opened in binary mode for reading. |
rewind | boolIf True, seek to the beginning of the file handle before writing the file to Cloud Storage. |
size | intThe number of bytes to be uploaded (which will be read from |
content_type | str(Optional) Type of content being uploaded. |
num_retries | intNumber of upload retries. By default, only uploads with if_generation_match set will be retried, as uploads without the argument are not guaranteed to be idempotent. Setting num_retries will override this default behavior and guarantee retries even when if_generation_match is not set. (Deprecated: This argument will be removed in a future release.) |
client | Client(Optional) The client to use. If not passed, falls back to the |
predefined_acl | str(Optional) Predefined access control list |
if_generation_match | long(Optional) See :ref: |
if_generation_not_match | long(Optional) See :ref: |
if_metageneration_match | long(Optional) See :ref: |
if_metageneration_not_match | long(Optional) See :ref: |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
checksum | str(Optional) The type of checksum to compute to verify the integrity of the object. If the upload is completed in a single request, the checksum will be entirely precomputed and the remote server will handle verification and error handling. If the upload is too large and must be transmitted in multiple requests, the checksum will be incrementally computed and the client will handle verification and error handling, raising google.resumable_media.common.DataCorruption on a mismatch and attempting to delete the corrupted file. Supported values are "md5", "crc32c" and None. The default is None. |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. A None value will disable retries. A google.api_core.retry.Retry value will enable retries, and the object will define retriable response codes and errors and configure backoff and timeout options. Agoogle.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and activates it only if certain conditions are met. This class exists to provide safe defaults for RPC calls that are not technically safe to retry normally (due to potential data duplication or other side-effects) but become safe to retry if a condition such as if_generation_match is set. See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for information on retry types and how to configure them. Media operations (downloads and uploads) do not support non-default predicates in a Retry object. The default will always be used. Other configuration changes for Retry objects such as delays and deadlines are respected. |
| Exceptions | |
|---|---|
| Type | Description |
GoogleCloudError | if the upload response returns an error status. |
upload_from_filename
upload_from_filename(filename,content_type=None,num_retries=None,client=None,predefined_acl=None,if_generation_match=None,if_generation_not_match=None,if_metageneration_match=None,if_metageneration_not_match=None,timeout=60,checksum=None,retry=<google.cloud.storage.retry.ConditionalRetryPolicyobject>)Upload this blob's contents from the content of a named file.
The content type of the upload will be determined in orderof precedence:
- The value passed in to this method (if not :data:
None) - The value stored on the current blob
- The value given by
mimetypes.guess_type - The default value ('application/octet-stream')
object versioning andlifecycle API documents for details.Ifuser_project is set on the bucket, bills the API requestto that project.
See acode sampleto upload a file with acustomer-supplied encryption key.
| Parameters | |
|---|---|
| Name | Description |
filename | strThe path to the file. |
content_type | str(Optional) Type of content being uploaded. |
client | Client(Optional) The client to use. If not passed, falls back to the |
num_retries | intNumber of upload retries. By default, only uploads with if_generation_match set will be retried, as uploads without the argument are not guaranteed to be idempotent. Setting num_retries will override this default behavior and guarantee retries even when if_generation_match is not set. (Deprecated: This argument will be removed in a future release.) |
predefined_acl | str(Optional) Predefined access control list |
if_generation_match | long(Optional) See :ref: |
if_generation_not_match | long(Optional) See :ref: |
if_metageneration_match | long(Optional) See :ref: |
if_metageneration_not_match | long(Optional) See :ref: |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
checksum | str(Optional) The type of checksum to compute to verify the integrity of the object. If the upload is completed in a single request, the checksum will be entirely precomputed and the remote server will handle verification and error handling. If the upload is too large and must be transmitted in multiple requests, the checksum will be incrementally computed and the client will handle verification and error handling, raising google.resumable_media.common.DataCorruption on a mismatch and attempting to delete the corrupted file. Supported values are "md5", "crc32c" and None. The default is None. |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. A None value will disable retries. A google.api_core.retry.Retry value will enable retries, and the object will define retriable response codes and errors and configure backoff and timeout options. Agoogle.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and activates it only if certain conditions are met. This class exists to provide safe defaults for RPC calls that are not technically safe to retry normally (due to potential data duplication or other side-effects) but become safe to retry if a condition such as if_generation_match is set. See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for information on retry types and how to configure them. Media operations (downloads and uploads) do not support non-default predicates in a Retry object. The default will always be used. Other configuration changes for Retry objects such as delays and deadlines are respected. |
upload_from_string
upload_from_string(data,content_type='text/plain',num_retries=None,client=None,predefined_acl=None,if_generation_match=None,if_generation_not_match=None,if_metageneration_match=None,if_metageneration_not_match=None,timeout=60,checksum=None,retry=<google.cloud.storage.retry.ConditionalRetryPolicyobject>)Upload contents of this blob from the provided string.
Note:The effect of uploading to an existing blob depends on the"versioning" and "lifecycle" policies defined on the blob'sbucket. In the absence of those policies, upload willoverwrite any existing contents. See theobject versioning andlifecycle API documents for details.Ifuser_project is set on the bucket, bills the API requestto that project.
| Parameters | |
|---|---|
| Name | Description |
data | bytes or strThe data to store in this blob. If the value is text, it will be encoded as UTF-8. |
content_type | str(Optional) Type of content being uploaded. Defaults to |
num_retries | intNumber of upload retries. By default, only uploads with if_generation_match set will be retried, as uploads without the argument are not guaranteed to be idempotent. Setting num_retries will override this default behavior and guarantee retries even when if_generation_match is not set. (Deprecated: This argument will be removed in a future release.) |
client | Client(Optional) The client to use. If not passed, falls back to the |
predefined_acl | str(Optional) Predefined access control list |
if_generation_match | long(Optional) See :ref: |
if_generation_not_match | long(Optional) See :ref: |
if_metageneration_match | long(Optional) See :ref: |
if_metageneration_not_match | long(Optional) See :ref: |
timeout | float or tuple(Optional) The amount of time, in seconds, to wait for the server response. See: |
checksum | str(Optional) The type of checksum to compute to verify the integrity of the object. If the upload is completed in a single request, the checksum will be entirely precomputed and the remote server will handle verification and error handling. If the upload is too large and must be transmitted in multiple requests, the checksum will be incrementally computed and the client will handle verification and error handling, raising google.resumable_media.common.DataCorruption on a mismatch and attempting to delete the corrupted file. Supported values are "md5", "crc32c" and None. The default is None. |
retry | google.api_core.retry.Retry orgoogle.cloud.storage.retry.ConditionalRetryPolicy(Optional) How to retry the RPC. A None value will disable retries. A google.api_core.retry.Retry value will enable retries, and the object will define retriable response codes and errors and configure backoff and timeout options. Agoogle.cloud.storage.retry.ConditionalRetryPolicy value wraps a Retry object and activates it only if certain conditions are met. This class exists to provide safe defaults for RPC calls that are not technically safe to retry normally (due to potential data duplication or other side-effects) but become safe to retry if a condition such as if_generation_match is set. See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for information on retry types and how to configure them. Media operations (downloads and uploads) do not support non-default predicates in a Retry object. The default will always be used. Other configuration changes for Retry objects such as delays and deadlines are respected. |
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-11-05 UTC.