BlobServiceClient class

Definition

A client to interact with the Blob Service at the account level.

This client provides operations to retrieve and configure the account properties as well as list, create and delete containers within the account. For operations relating to a specific container or blob, clients for those entities can also be retrieved using the get_client functions.

BlobServiceClient(account_url, credential=None, **kwargs)
Inheritance
builtins.object
azure.storage.blob._shared.base_client.StorageAccountHostsMixin
BlobServiceClient

Parameters

account_url
str

The URL to the blob storage account. Any other entities included in the URL path (e.g. container or blob) will be discarded. This URL can be optionally authenticated with a SAS token.

credential

The credentials with which to authenticate. This is optional if the account URL already has a SAS token. The value can be a SAS token string, and account shared access key, or an instance of a TokenCredentials class from azure.identity. If the URL already has a SAS token, specifying an explicit credential will take priority.

Variables

url
str
The full endpoint URL to the Blob service endpoint. This could be either the primary endpoint, or the secondary endpoint depending on the current *location_mode*.
primary_endpoint
str
The full primary endpoint URL.
primary_hostname
str
The hostname of the primary endpoint.
secondary_endpoint
str
The full secondary endpoint URL if configured. If not available a ValueError will be raised. To explicitly specify a secondary hostname, use the optional *secondary_hostname* keyword argument on instantiation.
secondary_hostname
str
The hostname of the secondary endpoint. If not available this will be None. To explicitly specify a secondary hostname, use the optional *secondary_hostname* keyword argument on instantiation.
location_mode
str
The location mode that the client is currently using. By default this will be "primary". Options include "primary" and "secondary".

Methods

create_container(name, metadata=None, public_access=None, timeout=None, **kwargs)

Creates a new container under the specified account.

If the container with the same name already exists, a ResourceExistsError will be raised. This method returns a client with which to interact with the newly created container.

delete_container(container, lease=None, timeout=None, **kwargs)

Marks the specified container for deletion.

The container and any blobs contained within it are later deleted during garbage collection. If the container is not found, a ResourceNotFoundError will be raised.

from_connection_string(conn_str, credential=None, **kwargs)

Create BlobServiceClient from a Connection String.

generate_shared_access_signature(resource_types, permission, expiry, start=None, ip=None, protocol=None)

Generates a shared access signature for the blob service.

Use the returned signature with the credential parameter of any BlobServiceClient, ContainerClient or BlobClient.

get_account_information(**kwargs)

Gets information related to the storage account.

The information can also be retrieved if the user has a SAS to a container or blob. The keys in the returned dictionary include 'sku_name' and 'account_kind'.

get_blob_client(container, blob, snapshot=None)

Get a client to interact with the specified blob.

The blob need not already exist.

get_container_client(container)

Get a client to interact with the specified container.

The container need not already exist.

get_service_properties(timeout=None, **kwargs)

Gets the properties of a storage account's Blob service, including Azure Storage Analytics.

get_service_stats(timeout=None, **kwargs)

Retrieves statistics related to replication for the Blob service.

It is only available when read-access geo-redundant replication is enabled for the storage account.

With geo-redundant replication, Azure Storage maintains your data durable in two locations. In both locations, Azure Storage constantly maintains multiple healthy replicas of your data. The location where you read, create, update, or delete data is the primary storage account location. The primary location exists in the region you choose at the time you create an account via the Azure Management Azure classic portal, for example, North Central US. The location to which your data is replicated is the secondary location. The secondary location is automatically determined based on the location of the primary; it is in a second data center that resides in the same region as the primary location. Read-only access is available from the secondary location, if read-access geo-redundant replication is enabled for your storage account.

get_user_delegation_key(key_start_time, key_expiry_time, timeout=None, **kwargs)

Obtain a user delegation key for the purpose of signing SAS tokens. A token credential must be present on the service object for this request to succeed.

list_containers(name_starts_with=None, include_metadata=False, results_per_page=None, timeout=None, **kwargs)

Returns a generator to list the containers under the specified account.

The generator will lazily follow the continuation tokens returned by the service and stop when all containers have been returned.

set_service_properties(logging=None, hour_metrics=None, minute_metrics=None, cors=None, target_version=None, delete_retention_policy=None, static_website=None, timeout=None, **kwargs)

Sets the properties of a storage account's Blob service, including Azure Storage Analytics.

If an element (e.g. Logging) is left as None, the existing settings on the service for that functionality are preserved.

create_container(name, metadata=None, public_access=None, timeout=None, **kwargs)

Creates a new container under the specified account.

If the container with the same name already exists, a ResourceExistsError will be raised. This method returns a client with which to interact with the newly created container.

create_container(name, metadata=None, public_access=None, timeout=None, **kwargs)

Parameters

name
str

The name of the container to create.

metadata
dict(str or str)

A dict with name-value pairs to associate with the container as metadata. Example: {'Category':'test'}

public_access
str or PublicAccess

Possible values include: container, blob.

timeout
int

The timeout parameter is expressed in seconds.

Return type

delete_container(container, lease=None, timeout=None, **kwargs)

Marks the specified container for deletion.

The container and any blobs contained within it are later deleted during garbage collection. If the container is not found, a ResourceNotFoundError will be raised.

delete_container(container, lease=None, timeout=None, **kwargs)

Parameters

container
str or ContainerProperties

The container to delete. This can either be the name of the container, or an instance of ContainerProperties.

lease
LeaseClient

If specified, delete_container only succeeds if the container's lease is active and matches this ID. Required if the container has an active lease.

if_modified_since
datetime

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has been modified since the specified time.

if_unmodified_since
datetime

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetimes will be converted to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Specify this header to perform the operation only if the resource has not been modified since the specified date/time.

if_match
str

An ETag value, or the wildcard character (*). Specify this header to perform the operation only if the resource's ETag matches the value specified.

if_none_match
str

An ETag value, or the wildcard character (). Specify this header to perform the operation only if the resource's ETag does not match the value specified. Specify the wildcard character () to perform the operation only if the resource does not exist, and fail the operation if it does exist.

timeout
int

The timeout parameter is expressed in seconds.

Return type

from_connection_string(conn_str, credential=None, **kwargs)

Create BlobServiceClient from a Connection String.

from_connection_string(conn_str, credential=None, **kwargs)

Parameters

conn_str
str

A connection string to an Azure Storage account.

credential

The credentials with which to authenticate. This is optional if the account URL already has a SAS token, or the connection string already has shared access key values. The value can be a SAS token string, and account shared access key, or an instance of a TokenCredentials class from azure.identity. Credentials provided here will take precedence over those in the connection string.

credential
default value: None

generate_shared_access_signature(resource_types, permission, expiry, start=None, ip=None, protocol=None)

Generates a shared access signature for the blob service.

Use the returned signature with the credential parameter of any BlobServiceClient, ContainerClient or BlobClient.

generate_shared_access_signature(resource_types, permission, expiry, start=None, ip=None, protocol=None)

Parameters

resource_types
str or azure.storage.blob.models.ResourceTypes

Specifies the resource types that are accessible with the account SAS.

permission
str or azure.storage.blob.models.AccountPermissions

The permissions associated with the shared access signature. The user is restricted to operations allowed by the permissions. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy.

expiry
datetime or str

The time at which the shared access signature becomes invalid. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC.

start
datetime or str

The time at which the shared access signature becomes valid. If omitted, start time for this call is assumed to be the time when the storage service receives the request. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC.

default value: None
ip
str

Specifies an IP address or a range of IP addresses from which to accept requests. If the IP address from which the request originates does not match the IP address or address range specified on the SAS token, the request is not authenticated. For example, specifying ip=168.1.5.65 or ip=168.1.5.60-168.1.5.70 on the SAS restricts the request to those IP addresses.

default value: None
protocol
str

Specifies the protocol permitted for a request made. The default value is https.

default value: None

Returns

A Shared Access Signature (sas) token.

Return type

str

get_account_information(**kwargs)

Gets information related to the storage account.

The information can also be retrieved if the user has a SAS to a container or blob. The keys in the returned dictionary include 'sku_name' and 'account_kind'.

get_account_information(**kwargs)

Returns

A dict of account information (SKU and account type).

Return type

get_blob_client(container, blob, snapshot=None)

Get a client to interact with the specified blob.

The blob need not already exist.

get_blob_client(container, blob, snapshot=None)

Parameters

container
str or ContainerProperties

The container that the blob is in. This can either be the name of the container, or an instance of ContainerProperties.

blob
str or BlobProperties

The blob with which to interact. This can either be the name of the blob, or an instance of BlobProperties.

snapshot
str or dict(str or Any)

The optional blob snapshot on which to operate. This can either be the ID of the snapshot, or a dictionary output returned by create_snapshot(metadata=None, **kwargs).

default value: None

Returns

A BlobClient.

Return type

get_container_client(container)

Get a client to interact with the specified container.

The container need not already exist.

get_container_client(container)

Parameters

container
str or ContainerProperties

The container. This can either be the name of the container, or an instance of ContainerProperties.

Returns

A ContainerClient.

Return type

azure.core.blob.container_client.ContainerClient

get_service_properties(timeout=None, **kwargs)

Gets the properties of a storage account's Blob service, including Azure Storage Analytics.

get_service_properties(timeout=None, **kwargs)

Parameters

timeout
int

The timeout parameter is expressed in seconds.

Return type

azure.storage.blob._generated.models.StorageServiceProperties

get_service_stats(timeout=None, **kwargs)

Retrieves statistics related to replication for the Blob service.

It is only available when read-access geo-redundant replication is enabled for the storage account.

With geo-redundant replication, Azure Storage maintains your data durable in two locations. In both locations, Azure Storage constantly maintains multiple healthy replicas of your data. The location where you read, create, update, or delete data is the primary storage account location. The primary location exists in the region you choose at the time you create an account via the Azure Management Azure classic portal, for example, North Central US. The location to which your data is replicated is the secondary location. The secondary location is automatically determined based on the location of the primary; it is in a second data center that resides in the same region as the primary location. Read-only access is available from the secondary location, if read-access geo-redundant replication is enabled for your storage account.

get_service_stats(timeout=None, **kwargs)

Parameters

timeout
int

The timeout parameter is expressed in seconds.

Returns

The blob service stats.

Return type

azure.storage.blob._generated.models.StorageServiceStats

get_user_delegation_key(key_start_time, key_expiry_time, timeout=None, **kwargs)

Obtain a user delegation key for the purpose of signing SAS tokens. A token credential must be present on the service object for this request to succeed.

get_user_delegation_key(key_start_time, key_expiry_time, timeout=None, **kwargs)

Parameters

key_start_time
datetime

A DateTime value. Indicates when the key becomes valid.

key_expiry_time
datetime

A DateTime value. Indicates when the key stops being valid.

timeout
int

The timeout parameter is expressed in seconds.

Returns

The user delegation key.

Return type

azure.storage.blob._shared.models.UserDelegationKey

list_containers(name_starts_with=None, include_metadata=False, results_per_page=None, timeout=None, **kwargs)

Returns a generator to list the containers under the specified account.

The generator will lazily follow the continuation tokens returned by the service and stop when all containers have been returned.

list_containers(name_starts_with=None, include_metadata=False, results_per_page=None, timeout=None, **kwargs)

Parameters

name_starts_with
str

Filters the results to return only containers whose names begin with the specified prefix.

include_metadata
bool

Specifies that container metadata be returned in the response. The default value is False.

results_per_page
int

The maximum number of container names to retrieve per API call. If the request does not specify the server will return up to 5,000 items.

timeout
int

The timeout parameter is expressed in seconds.

Returns

An iterable (auto-paging) of ContainerProperties.

Return type

ItemPaged[azure.core.blob.models.ContainerProperties]

set_service_properties(logging=None, hour_metrics=None, minute_metrics=None, cors=None, target_version=None, delete_retention_policy=None, static_website=None, timeout=None, **kwargs)

Sets the properties of a storage account's Blob service, including Azure Storage Analytics.

If an element (e.g. Logging) is left as None, the existing settings on the service for that functionality are preserved.

set_service_properties(logging=None, hour_metrics=None, minute_metrics=None, cors=None, target_version=None, delete_retention_policy=None, static_website=None, timeout=None, **kwargs)

Parameters

logging
<xref:azure.storage.blob.models.Logging>

Groups the Azure Analytics Logging settings.

hour_metrics
<xref:azure.storage.blob.models.Metrics>

The hour metrics settings provide a summary of request statistics grouped by API in hourly aggregates for blobs.

minute_metrics
<xref:azure.storage.blob.models.Metrics>

The minute metrics settings provide request statistics for each minute for blobs.

cors
list(<xref:azure.storage.blob.models.CorsRule>)

You can include up to five CorsRule elements in the list. If an empty list is specified, all CORS rules will be deleted, and CORS will be disabled for the service.

target_version
str

Indicates the default version to use for requests if an incoming request's version is not specified.

delete_retention_policy
<xref:azure.storage.blob.models.RetentionPolicy>

The delete retention policy specifies whether to retain deleted blobs. It also specifies the number of days and versions of blob to keep.

static_website
<xref:azure.storage.blob.models.StaticWebsite>

Specifies whether the static website feature is enabled, and if yes, indicates the index document and 404 error document to use.

timeout
int

The timeout parameter is expressed in seconds.

Return type