Google Storage Driver Documentation

Current version of the Google Storage driver in Libcloud uses S3 compatibility layer and as such, only supports XML API v1.0.

If you are a new Google Cloud Storage customers, you need to enable API v1.0 access and choose a default project in the Google Cloud Console for driver to work.

For information on how to do that, please see the official documentation.

If you don’t do that, you will get a message that the request is missing a project id header.

Known limitations

1. Meta data / tags aren’t returned when using list_container_objects method

Meta data / tags associated with an object are only returned when using libcloud.storage.base.StorageDriver.get_object() method and not when listing all the objects in a container using libcloud.storage.base.StorageDriver.list_container_objects() method.

This is a limitation of the Google Storage API v1.0.

API Docs

class libcloud.storage.drivers.google_storage.GoogleStorageDriver(key, secret=None, project=None, **kwargs)

Driver for Google Cloud Storage.

Can authenticate via standard Google Cloud methods (Service Accounts, Installed App credentials, and GCE instance service accounts)

Examples:

Service Accounts:

driver = GoogleStorageDriver(key=client_email, secret=private_key, ...)

Installed Application:

driver = GoogleStorageDriver(key=client_id, secret=client_secret, ...)

From GCE instance:

driver = GoogleStorageDriver(key=foo, secret=bar, ...)

Can also authenticate via Google Cloud Storage’s S3 HMAC interoperability API. S3 user keys are 20 alphanumeric characters, starting with GOOG.

Example:

driver = GoogleStorageDriver(key='GOOG0123456789ABCXYZ',
                             secret=key_secret)

connectionCls

alias of GoogleStorageConnection

create_container(container_name)

Create a new container.

Parameters:container_name (str) – Container name. Returns:Container instance on success. Return type:Container

delete_container(container)

Delete a container.

Parameters:container (Container) – Container instance Returns:True on success, False otherwise. Return type:bool

delete_object(obj)

Delete an object.

Parameters:obj (Object) – Object instance. Returns:bool True on success. Return type:bool

download_object(obj, destination_path, overwrite_existing=False, delete_on_failure=True)

Download an object to the specified destination path.

Parameters:

• obj (Object) – Object instance.
• destination_path (str) – Full path to a file or a directory where the incoming file will be saved.
• overwrite_existing (bool) – True to overwrite an existing file, defaults to False.
• delete_on_failure (bool) – True to delete a partially downloaded file if the download was not successful (hash mismatch / file size).

Returns:

True if an object has been successfully downloaded, False otherwise.

Return type:

bool

download_object_as_stream(obj, chunk_size=None)

Return a generator which yields object data.

Parameters:

• obj (Object) – Object instance
• chunk_size (int) – Optional chunk size (in bytes).

enable_container_cdn(container)

Enable container CDN.

Parameters:container (Container) – Container instance Return type:bool

enable_object_cdn(obj)

Enable object CDN.

Parameters:obj (Object) – Object instance Return type:bool

ex_cleanup_all_multipart_uploads(container, prefix=None)

Extension method for removing all partially completed S3 multipart uploads.

Parameters:

• container (Container) – The container holding the uploads
• prefix (str) – Delete only uploads of objects with this prefix

ex_delete_permissions(container_name, object_name=None, entity=None)

Delete permissions for an ACL entity on a container or object.

Parameters:

• container_name (str) – The container name.
• object_name (str) – The object name. Optional. Not providing an object will delete a container permission.
• entity (str or None) – The entity to whose permission will be deleted. Optional. If not provided, the role will be applied to the authenticated user, if using an OAuth2 authentication scheme.

ex_get_permissions(container_name, object_name=None)

Return the permissions for the currently authenticated user.

Parameters:

• container_name (str) – The container name.
• object_name (str or None) – The object name. Optional. Not providing an object will return only container permissions.

Returns:

A tuple of container and object permissions.

Return type:

tuple of (int, int or None) from ContainerPermissions and ObjectPermissions, respectively.

ex_iterate_multipart_uploads(container, prefix=None, delimiter=None)

Extension method for listing all in-progress S3 multipart uploads.

Each multipart upload which has not been committed or aborted is considered in-progress.

Parameters:

• container (Container) – The container holding the uploads
• prefix (str) – Print only uploads of objects with this prefix
• delimiter (str) – The object/key names are grouped based on being split by this delimiter

Returns:

A generator of S3MultipartUpload instances.

Return type:

generator of S3MultipartUpload

ex_set_permissions(container_name, object_name=None, entity=None, role=None)

Set the permissions for an ACL entity on a container or an object.

Parameters:

• container_name (str) – The container name.
• object_name (str) – The object name. Optional. Not providing an object will apply the acl to the container.
• entity (str) – The entity to which apply the role. Optional. If not provided, the role will be applied to the authenticated user, if using an OAuth2 authentication scheme.
• role (int from ContainerPermissions or ObjectPermissions or str.) – The permission/role to set on the entity.

Raises:

ValueError – If no entity was given, but was required. Or if the role isn’t valid for the bucket or object.

get_container(container_name)

Return a container instance.

Parameters:container_name (str) – Container name. Returns:Container instance. Return type:Container

get_container_cdn_url(container)

Return a container CDN URL.

Parameters:container (Container) – Container instance Returns:A CDN URL for this container. Return type:str

get_object(container_name, object_name)

Return an object instance.

Parameters:

• container_name (str) – Container name.
• object_name (str) – Object name.

Returns:

Object instance.

Return type:

Object

get_object_cdn_url(obj)

Return an object CDN URL.

Parameters:obj (Object) – Object instance Returns:A CDN URL for this object. Return type:str

iterate_container_objects(container, ex_prefix=None)

Return a generator of objects for the given container.

Parameters:

• container (Container) – Container instance
• ex_prefix (str) – Only return objects starting with ex_prefix

Returns:

A generator of Object instances.

Return type:

generator of Object

iterate_containers()

Return a generator of containers for the given account

Returns:A generator of Container instances. Return type:generator of Container

jsonConnectionCls

alias of GoogleStorageJSONConnection

list_container_objects(container, ex_prefix=None)

Return a list of objects for the given container.

Parameters:

• container (Container) – Container instance.
• ex_prefix (str) – Only return objects starting with ex_prefix

Returns:

A list of Object instances.

Return type:

list of Object

list_containers()

Return a list of containers.

Returns:A list of Container instances. Return type:list of Container

upload_object(file_path, container, object_name, extra=None, verify_hash=True, ex_storage_class=None)

@inherits: StorageDriver.upload_object

Parameters:ex_storage_class (str) – Storage class

upload_object_via_stream(iterator, container, object_name, extra=None, ex_storage_class=None)

@inherits: StorageDriver.upload_object_via_stream

Parameters:ex_storage_class (str) – Storage class