- 3.0.0-rc1 (latest)
- 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
Client(project=<object object>, credentials=None, _http=None, client_info=None, client_options=None, use_auth_w_custom_endpoint=True, extra_headers={})
Client to bundle configuration needed for API requests.
Parameters |
|
---|---|
Name | Description |
project |
str or None
the project which the client acts on behalf of. Will be passed when creating a topic. If not passed, falls back to the default inferred from the environment. |
credentials |
(Optional) The OAuth2 Credentials to use for this client. If not passed (and if no |
_http |
(Optional) HTTP object to make requests. Can be any object that defines |
client_info |
The client info used to send a user-agent string along with API requests. If |
client_options |
(Optional) Client options used to set user options on the client. A non-default universe domain or api endpoint should be set through client_options. |
use_auth_w_custom_endpoint |
bool
(Optional) Whether authentication is required under custom endpoints. If false, uses AnonymousCredentials and bypasses authentication. Defaults to True. Note this is only used when a custom endpoint is set in conjunction. |
extra_headers |
dict
(Optional) Custom headers to be sent with the requests attached to the client. For example, you can add custom audit logging headers. |
Properties
current_batch
Currently-active batch.
Returns | |
---|---|
Type | Description |
Batch or |
The batch at the top of the batch stack. |
Methods
batch
batch(raise_exception=True)
Factory constructor for batch object.
Parameter | |
---|---|
Name | Description |
raise_exception |
bool
(Optional) Defaults to True. If True, instead of adding exceptions to the list of return responses, the final exception will be raised. Note that exceptions are unwrapped after all operations are complete in success or failure, and only the last exception is raised. |
Returns | |
---|---|
Type | Description |
Batch |
The batch object created. |
bucket
bucket(bucket_name, user_project=None, generation=None)
Factory constructor for bucket object.
Parameters | |
---|---|
Name | Description |
bucket_name |
str
The name of the bucket to be instantiated. |
user_project |
str
(Optional) The project ID to be billed for API requests made via the bucket. |
generation |
int
(Optional) If present, selects a specific revision of this bucket. |
Returns | |
---|---|
Type | Description |
Bucket |
The bucket object created. |
create_anonymous_client
create_anonymous_client()
Factory: return client with anonymous credentials.
Returns | |
---|---|
Type | Description |
Client |
Instance w/ anonymous credentials and no project. |
create_bucket
create_bucket(bucket_or_name, requester_pays=None, project=None, user_project=None, location=None, data_locations=None, predefined_acl=None, predefined_default_object_acl=None, enable_object_retention=False, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object>)
Create a new bucket via a POST request.
See API reference docs and a code sample.
Exceptions | |
---|---|
Type | Description |
google.cloud.exceptions.Conflict |
If the bucket already exists. |
create_hmac_key
create_hmac_key(
service_account_email, project_id=None, user_project=None, timeout=60, retry=None
)
Create an HMAC key for a service account.
Returns | |
---|---|
Type | Description |
Tuple[HMACKeyMetadata, str] |
metadata for the created key, plus the bytes of the key's secret, which is an 40-character base64-encoded string. |
download_blob_to_file
download_blob_to_file(blob_or_uri, file_obj, 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='auto', retry=<google.api_core.retry.retry_unary.Retry object>)
Download the contents of a blob object or blob URI into a file-like object.
See https://cloud.google.com/storage/docs/downloading-objects
generate_signed_post_policy_v4
generate_signed_post_policy_v4(
bucket_name,
blob_name,
expiration,
conditions=None,
fields=None,
credentials=None,
virtual_hosted_style=False,
bucket_bound_hostname=None,
scheme="http",
service_account_email=None,
access_token=None,
)
Generate a V4 signed policy object. Generated policy object allows user to upload objects with a POST request.
Parameters | |
---|---|
Name | Description |
bucket_name |
str
Bucket name. |
blob_name |
str
Object name. |
expiration |
Union[Integer, datetime.datetime, datetime.timedelta]
Policy expiration time. If a |
conditions |
list
(Optional) List of POST policy conditions, which are used to restrict what is allowed in the request. |
fields |
dict
(Optional) Additional elements to include into request. |
credentials |
(Optional) Credentials object with an associated private key to sign text. |
virtual_hosted_style |
bool
(Optional) If True, construct the URL relative to the bucket virtual hostname, e.g., '
|
bucket_bound_hostname |
str
(Optional) If passed, construct the URL relative to the bucket-bound hostname. Value can be bare or with a scheme, e.g., 'example.com' or 'http://example.com'. Incompatible with virtual_hosted_style. See: https://cloud.google.com/storage/docs/request-endpoints#cname |
scheme |
str
(Optional) If |
service_account_email |
str
(Optional) E-mail address of the service account. |
access_token |
str
(Optional) Access token for a service account. |
Exceptions | |
---|---|
Type | Description |
`ValueError |
when mutually exclusive arguments are used. |
Returns | |
---|---|
Type | Description |
dict |
Signed POST policy. |
get_bucket
get_bucket(bucket_or_name, timeout=60, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.api_core.retry.retry_unary.Retry object>, *, generation=None, soft_deleted=None)
Retrieve a bucket via a GET request.
See API reference docs and a code sample.
Exceptions | |
---|---|
Type | Description |
google.cloud.exceptions.NotFound |
If the bucket is not found. |
get_hmac_key_metadata
get_hmac_key_metadata(access_id, project_id=None, user_project=None, timeout=60)
Return a metadata instance for the given HMAC key.
get_service_account_email
get_service_account_email(project=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object>)
Get the email address of the project's GCS service account
Returns | |
---|---|
Type | Description |
str |
service account email address |
list_blobs
list_blobs(bucket_or_name, max_results=None, page_token=None, prefix=None, delimiter=None, start_offset=None, end_offset=None, include_trailing_delimiter=None, versions=None, projection='noAcl', fields=None, page_size=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object>, match_glob=None, include_folders_as_prefixes=None, soft_deleted=None)
Return an iterator used to find blobs in the bucket.
If user_project
is set, bills the API request to that project.
list_buckets
list_buckets(max_results=None, page_token=None, prefix=None, projection='noAcl', fields=None, project=None, page_size=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object>, *, soft_deleted=None)
Get all buckets in the project associated to the client.
This will not populate the list of blobs available in each bucket.
See API reference docs and a code sample.
Exceptions | |
---|---|
Type | Description |
ValueError |
if both project is None and the client's project is also None . |
Returns | |
---|---|
Type | Description |
|
Iterator of all Bucket belonging to this project. |
list_hmac_keys
list_hmac_keys(max_results=None, service_account_email=None, show_deleted_keys=None, project_id=None, user_project=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object>)
List HMAC keys for a project.
Returns | |
---|---|
Type | Description |
Tuple[HMACKeyMetadata, str] |
metadata for the created key, plus the bytes of the key's secret, which is an 40-character base64-encoded string. |
lookup_bucket
lookup_bucket(bucket_name, timeout=60, if_metageneration_match=None, if_metageneration_not_match=None, retry=<google.api_core.retry.retry_unary.Retry object>)
Get a bucket by name, returning None if not found.
You can use this if you would rather check for a None value than catching a NotFound exception.
Returns | |
---|---|
Type | Description |
Bucket or |
The bucket matching the name provided or None if not found. |
restore_bucket
restore_bucket(bucket_name, generation, projection='noAcl', if_metageneration_match=None, if_metageneration_not_match=None, timeout=60, retry=<google.api_core.retry.retry_unary.Retry object>)
Restores a soft-deleted bucket.
Parameters | |
---|---|
Name | Description |
bucket_name |
str
The name of the bucket to be restored. |
generation |
int
Selects the specific revision of the bucket. |
projection |
str
(Optional) Specifies the set of properties to return. If used, must be 'full' or 'noAcl'. Defaults to 'noAcl'. if_metageneration_match (Optional[int]): Make the operation conditional on whether the blob's current metageneration matches the given value. if_metageneration_not_match (Optional[int]): Make the operation conditional on whether the blob'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 or google.cloud.storage.retry.ConditionalRetryPolicy
(Optional) How to retry the RPC. Users can configure non-default retry behavior. A |
Returns | |
---|---|
Type | Description |
Bucket |
The restored Bucket. |