Blobs / Objects#
Create / interact with Google Cloud Storage blobs.
-
class
google.cloud.storage.blob.
Blob
(name, bucket, chunk_size=None)[source]# Bases:
google.cloud.storage._helpers._PropertyMixin
A wrapper around Cloud Storage’s concept of an
Object
.Parameters: - name (string) – The name of the blob. This corresponds to the unique path of the object in the bucket.
- bucket (
google.cloud.storage.bucket.Bucket
) – The bucket to which this blob belongs. - chunk_size (integer) – The size of a chunk of data whenever iterating (1 MB). This must be a multiple of 256 KB per the API specification.
-
acl
# Create our ACL on demand.
-
cache_control
# HTTP ‘Cache-Control’ header for this object.
- See: https://tools.ietf.org/html/rfc7234#section-5.2 and
- https://cloud.google.com/storage/docs/json_api/v1/objects
If the property is not set locally, returns
None
.Return type: string or NoneType
-
chunk_size
# Get the blob’s default chunk size.
Return type: integer or NoneType
Returns: 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.
See: https://cloud.google.com/storage/docs/json_api/v1/objects
Return type: integer or NoneType
Returns: The component count (in case of a composed object) or None
if the property is not set locally. This property will not be set on objects not created viacompose
.
-
content_disposition
# HTTP ‘Content-Disposition’ header for this object.
- See: https://tools.ietf.org/html/rfc6266 and
- https://cloud.google.com/storage/docs/json_api/v1/objects
If the property is not set locally, returns
None
.Return type: string or NoneType
-
content_encoding
# HTTP ‘Content-Encoding’ header for this object.
- See: https://tools.ietf.org/html/rfc7231#section-3.1.2.2 and
- https://cloud.google.com/storage/docs/json_api/v1/objects
If the property is not set locally, returns
None
.Return type: string or NoneType
-
content_language
# HTTP ‘Content-Language’ header for this object.
If the property is not set locally, returns
None
.Return type: string or NoneType
-
content_type
# HTTP ‘Content-Type’ header for this object.
- See: https://tools.ietf.org/html/rfc2616#section-14.17 and
- https://cloud.google.com/storage/docs/json_api/v1/objects
If the property is not set locally, returns
None
.Return type: string or NoneType
-
crc32c
# CRC32C checksum for this object.
- See: http://tools.ietf.org/html/rfc4960#appendix-B and
- https://cloud.google.com/storage/docs/json_api/v1/objects
If the property is not set locally, returns
None
.Return type: string or NoneType
-
delete
(client=None)[source]# Deletes a blob from Cloud Storage.
Parameters: client ( Client
orNoneType
) – Optional. The client to use. If not passed, falls back to theclient
stored on the blob’s bucket.Return type: Blob
Returns: The blob that was just deleted. Raises: google.cloud.exceptions.NotFound
(propagated fromgoogle.cloud.storage.bucket.Bucket.delete_blob()
).
-
download_as_string
(encryption_key=None, client=None)[source]# Download the contents of this blob as a string.
Parameters: - encryption_key (str or bytes) – Optional 32 byte encryption key for customer-supplied encryption.
- client (
Client
orNoneType
) – Optional. The client to use. If not passed, falls back to theclient
stored on the blob’s bucket.
Return type: bytes
Returns: The data stored in this blob.
Raises:
-
download_to_file
(file_obj, encryption_key=None, client=None)[source]# Download the contents of this blob into a file-like object.
Note
If the server-set property,media_link
, is not yet initialized, makes an additional API request to load it.Downloading a file that has been encrypted with a customer-supplied encryption key:
>>> from google.cloud import storage >>> from google.cloud.storage import Blob >>> client = storage.Client(project='my-project') >>> bucket = client.get_bucket('my-bucket') >>> encryption_key = 'aa426195405adee2c8081bb9e7e74b19' >>> blob = Blob('secure-data', bucket) >>> with open('/tmp/my-secure-file', 'wb') as file_obj: >>> blob.download_to_file(file_obj, ... encryption_key=encryption_key)
The
encryption_key
should be a str or bytes with a length of at least 32.Parameters: Raises:
-
download_to_filename
(filename, encryption_key=None, client=None)[source]# Download the contents of this blob into a named file.
Parameters: Raises:
-
etag
# Retrieve the ETag for the object.
- See: http://tools.ietf.org/html/rfc2616#section-3.11 and
- https://cloud.google.com/storage/docs/json_api/v1/objects
Return type: string or NoneType
Returns: The blob etag or None
if the property is not set locally.
-
exists
(client=None)[source]# Determines whether or not this blob exists.
Parameters: client ( Client
orNoneType
) – Optional. The client to use. If not passed, falls back to theclient
stored on the blob’s bucket.Return type: boolean Returns: True if the blob exists in Cloud Storage.
-
generate_signed_url
(expiration, method='GET', content_type=None, generation=None, response_disposition=None, response_type=None, client=None, credentials=None)[source]# Generates a signed URL for this blob.
Note
If you are on Google Compute Engine, you can’t generate a signed URL. Follow Issue 922 for updates on this. 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 rather than a GCE service account.
If you have a blob that you want to allow access to for a set amount of time, you can use this method to generate a URL that is only valid within a certain time period.
This is particularly useful if you don’t want publicly accessible blobs, but don’t want to require users to explicitly log in.
Parameters: - expiration (int, long, datetime.datetime, datetime.timedelta) – When the signed URL should expire.
- method (str) – The HTTP verb that will be used when requesting the URL.
- content_type (str) – (Optional) The content type of the object
referenced by
resource
. - generation (str) – (Optional) A value that indicates which generation of the resource to fetch.
- 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
blog.png
, use the value'attachment; filename=blob.png'
. - response_type (str) – (Optional) Content type of responses to requests for the signed URL. Used to over-ride the content type of the underlying blob/object.
- client (
Client
orNoneType
) – (Optional) The client to use. If not passed, falls back to theclient
stored on the blob’s bucket. - credentials (
oauth2client.client.OAuth2Credentials
orNoneType
) – (Optional) The OAuth2 credentials to use to sign the URL. Defaults to the credentials stored on the client used.
Return type: Returns: A signed URL you can use to access the resource until expiration.
-
generation
# Retrieve the generation for the object.
See: https://cloud.google.com/storage/docs/json_api/v1/objects
Return type: integer or NoneType
Returns: The generation of the blob or None
if the property is not set locally.
-
id
# Retrieve the ID for the object.
See: https://cloud.google.com/storage/docs/json_api/v1/objects
Return type: string or NoneType
Returns: The ID of the blob or None
if the property is not set locally.
-
make_public
(client=None)[source]# Make this blob public giving all users read access.
Parameters: client ( Client
orNoneType
) – Optional. The client to use. If not passed, falls back to theclient
stored on the blob’s bucket.
-
md5_hash
# MD5 hash for this object.
- See: http://tools.ietf.org/html/rfc4960#appendix-B and
- https://cloud.google.com/storage/docs/json_api/v1/objects
If the property is not set locally, returns
None
.Return type: string or NoneType
-
media_link
# Retrieve the media download URI for the object.
See: https://cloud.google.com/storage/docs/json_api/v1/objects
Return type: string or NoneType
Returns: The media link for the blob or None
if the property is not set locally.
-
metadata
# Retrieve arbitrary/application specific metadata for the object.
See: https://cloud.google.com/storage/docs/json_api/v1/objects
Return type: dict or NoneType
Returns: The metadata associated with the blob or None
if the property is not set locally.
-
metageneration
# Retrieve the metageneration for the object.
See: https://cloud.google.com/storage/docs/json_api/v1/objects
Return type: integer or NoneType
Returns: The metageneration of the blob or None
if the property is not set locally.
-
owner
# Retrieve info about the owner of the object.
See: https://cloud.google.com/storage/docs/json_api/v1/objects
Return type: dict or NoneType
Returns: Mapping of owner’s role/ID. If the property is not set locally, returns None
.
-
path
# Getter property for the URL path to this Blob.
Return type: string Returns: The URL path to this Blob.
-
static
path_helper
(bucket_path, blob_name)[source]# Relative URL path for a blob.
Parameters: Return type: Returns: The relative URL path for
blob_name
.
-
public_url
# The public URL for this blob’s object.
Return type: string Returns: The public URL for this blob.
-
self_link
# Retrieve the URI for the object.
See: https://cloud.google.com/storage/docs/json_api/v1/objects
Return type: string or NoneType
Returns: The self link for the blob or None
if the property is not set locally.
-
size
# Size of the object, in bytes.
See: https://cloud.google.com/storage/docs/json_api/v1/objects
Return type: integer or NoneType
Returns: The size of the blob or None
if the property is not set locally.
-
storage_class
# Retrieve the storage class for the object.
See: https://cloud.google.com/storage/docs/storage-classes https://cloud.google.com/storage/docs/nearline-storage https://cloud.google.com/storage/docs/durable-reduced-availability
Return type: string or NoneType
Returns: If set, one of “STANDARD”, “NEARLINE”, or “DURABLE_REDUCED_AVAILABILITY”, else None
.
-
time_deleted
# Retrieve the timestamp at which the object was deleted.
See: https://cloud.google.com/storage/docs/json_api/v1/objects
Return type: datetime.datetime
orNoneType
Returns: Datetime object parsed from RFC3339 valid timestamp, or None
if the property is not set locally. If the blob has not been deleted, this will never be set.
-
updated
# Retrieve the timestamp at which the object was updated.
See: https://cloud.google.com/storage/docs/json_api/v1/objects
Return type: datetime.datetime
orNoneType
Returns: Datetime object parsed from RFC3339 valid timestamp, or None
if the property is not set locally.
-
upload_from_file
(file_obj, rewind=False, size=None, encryption_key=None, content_type=None, num_retries=6, client=None)[source]# Upload the contents of this blob from a file-like object.
The content type of the upload will either be - The value passed in to the function (if any) - The value stored on the current blob - The default value of ‘application/octet-stream’
Note
The effect of uploading to an existing blob depends on the “versioning” and “lifecycle” policies defined on the blob’s bucket. In the absence of those policies, upload will overwrite any existing contents.
See the object versioning and lifecycle API documents for details.
Uploading a file with a customer-supplied encryption key:
>>> from google.cloud import storage >>> from google.cloud.storage import Blob >>> client = storage.Client(project='my-project') >>> bucket = client.get_bucket('my-bucket') >>> encryption_key = 'aa426195405adee2c8081bb9e7e74b19' >>> blob = Blob('secure-data', bucket) >>> with open('my-file', 'rb') as my_file: >>> blob.upload_from_file(my_file, ... encryption_key=encryption_key)
The
encryption_key
should be a str or bytes with a length of at least 32.Parameters: - file_obj (file) – A file handle open for reading.
- rewind (boolean) – If True, seek to the beginning of the file handle before writing the file to Cloud Storage.
- size (int) – The number of bytes to read from the file handle.
If not provided, we’ll try to guess the size using
os.fstat()
. (If the file handle is not from the filesystem this won’t be possible.) - encryption_key (str or bytes) – Optional 32 byte encryption key for customer-supplied encryption.
- content_type (string or
NoneType
) – Optional type of content being uploaded. - num_retries (integer) – Number of upload retries. Defaults to 6.
- client (
Client
orNoneType
) – Optional. The client to use. If not passed, falls back to theclient
stored on the blob’s bucket.
Raises: ValueError
if size is not passed in and can not be determined;google.cloud.exceptions.GoogleCloudError
if the upload response returns an error status.
-
upload_from_filename
(filename, content_type=None, encryption_key=None, client=None)[source]# Upload this blob’s contents from the content of a named file.
The content type of the upload will either be - The value passed in to the function (if any) - The value stored on the current blob - The value given by mimetypes.guess_type
Note
The effect of uploading to an existing blob depends on the “versioning” and “lifecycle” policies defined on the blob’s bucket. In the absence of those policies, upload will overwrite any existing contents.
See the object versioning and lifecycle API documents for details.
Parameters: - filename (string) – The path to the file.
- content_type (string or
NoneType
) – Optional type of content being uploaded. - encryption_key (str or bytes) – Optional 32 byte encryption key for customer-supplied encryption.
- client (
Client
orNoneType
) – Optional. The client to use. If not passed, falls back to theclient
stored on the blob’s bucket.
-
upload_from_string
(data, content_type='text/plain', encryption_key=None, client=None)[source]# 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’s bucket. In the absence of those policies, upload will overwrite any existing contents.
See the object versioning and lifecycle API documents for details.
Parameters: - data (bytes or text) – The data to store in this blob. If the value is text, it will be encoded as UTF-8.
- content_type (string) – Optional type of content being uploaded. Defaults
to
'text/plain'
. - encryption_key (str or bytes) – Optional 32 byte encryption key for customer-supplied encryption.
- client (
Client
orNoneType
) – Optional. The client to use. If not passed, falls back to theclient
stored on the blob’s bucket.