blob package
Packages
| aio |
Classes
| BlobServiceClient |
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. |
| ContainerClient |
A client to interact with a specific container, although that container may not yet exist. For operations relating to a specific blob within this container, a blob client can be retrieved using the get_blob_client(blob, snapshot=None) function. |
| BlobClient |
A client to interact with a specific blob, although that blob may not yet exist. |
| BlobType |
An enumeration. |
| BlobLeaseClient |
Creates a new BlobLeaseClient. This client provides lease operations on a BlobClient or ContainerClient. |
| StorageErrorCode |
An enumeration. |
| UserDelegationKey |
Represents a user delegation key, provided to the user by Azure Storage based on their Azure Active Directory access token. The fields are saved as simple strings since the user does not have to interact with this object; to generate an identify SAS, the user can simply pass it to the right API. |
| ExponentialRetry |
Exponential retry. |
| LinearRetry |
Linear retry. |
| LocationMode |
Specifies the location the request should be sent to. This mode only applies for RA-GRS accounts which allow secondary read access. All other account types must use PRIMARY. |
| BlockState |
Block blob block types. |
| StandardBlobTier |
Specifies the blob tier to set the blob to. This is only applicable for block blobs on standard storage accounts. |
| PremiumPageBlobTier |
Specifies the page blob tier to set the blob to. This is only applicable to page blobs on premium storage accounts. Please take a look at: https://docs.microsoft.com/en-us/azure/storage/storage-premium-storage#scalability-and-performance-targets for detailed information on the corresponding IOPS and throughput per PageBlobTier. |
| SequenceNumberAction |
Sequence number actions. |
| PublicAccess |
Specifies whether data in the container may be accessed publicly and the level of access. |
| BlobAnalyticsLogging |
Azure Analytics Logging settings. |
| Metrics |
A summary of request statistics grouped by API in hour or minute aggregates for blobs. |
| RetentionPolicy |
The retention policy which determines how long the associated data should persist. |
| StaticWebsite |
The properties that enable an account to host a static website. |
| CorsRule |
CORS is an HTTP feature that enables a web application running under one domain to access resources in another domain. Web browsers implement a security restriction known as same-origin policy that prevents a web page from calling APIs in a different domain; CORS provides a secure way to allow one domain (the origin domain) to call APIs in another domain. |
| ContainerProperties |
Blob container's properties class. Returned |
| BlobProperties |
Blob Properties. |
| LeaseProperties |
Blob Lease Properties. |
| ContentSettings |
The content settings of a blob. |
| CopyProperties |
Blob Copy Properties. These properties will be None if this blob has never been the destination in a Copy Blob operation, or if this blob has been modified after a concluded Copy Blob operation, for example, using Set Blob Properties, Upload Blob, or Commit Block List. |
| BlobBlock |
BlockBlob Block class. |
| PageRange |
Page Range for page blob. |
| AccessPolicy |
Access Policy class used by the set and get access policy methods in each service. A stored access policy can specify the start time, expiry time, and permissions for the Shared Access Signatures with which it's associated. Depending on how you want to control access to your resource, you can specify all of these parameters within the stored access policy, and omit them from the URL for the Shared Access Signature. Doing so permits you to modify the associated signature's behavior at any time, as well as to revoke it. Or you can specify one or more of the access policy parameters within the stored access policy, and the others on the URL. Finally, you can specify all of the parameters on the URL. In this case, you can use the stored access policy to revoke the signature, but not to modify its behavior. Together the Shared Access Signature and the stored access policy must include all fields required to authenticate the signature. If any required fields are missing, the request will fail. Likewise, if a field is specified both in the Shared Access Signature URL and in the stored access policy, the request will fail with status code 400 (Bad Request). |
| ContainerSasPermissions |
ContainerSasPermissions class to be used with the generate_container_sas(account_name, container_name, account_key=None, user_delegation_key=None, permission=None, expiry=None, start=None, policy_id=None, ip=None, **kwargs) function and for the AccessPolicies used with set_container_access_policy(signed_identifiers, public_access=None, **kwargs). |
| BlobSasPermissions |
BlobSasPermissions class to be used with the generate_blob_sas(account_name, container_name, blob_name, snapshot=None, account_key=None, user_delegation_key=None, permission=None, expiry=None, start=None, policy_id=None, ip=None, **kwargs) function. |
| ResourceTypes |
Specifies the resource types that are accessible with the account SAS. |
| AccountSasPermissions |
ResourceTypes class to be used with generate_account_sas function and for the AccessPolicies used with set_*_acl. There are two types of SAS which may be used to grant resource access. One is to grant access to a specific resource (resource-specific). Another is to grant access to the entire service for a specific account and allow certain operations based on perms found here. |
| StorageStreamDownloader |
A streaming object to download from Azure Storage. |
| CustomerProvidedEncryptionKey |
All data in Azure Storage is encrypted at-rest using an account-level encryption key. In versions 2018-06-17 and newer, you can manage the key used to encrypt blob contents and application metadata per-blob by providing an AES-256 encryption key in requests to the storage service. When you use a customer-provided key, Azure Storage does not manage or persist your key. When writing data to a blob, the provided key is used to encrypt your data before writing it to disk. A SHA-256 hash of the encryption key is written alongside the blob contents, and is used to verify that all subsequent operations against the blob use the same encryption key. This hash cannot be used to retrieve the encryption key or decrypt the contents of the blob. When reading a blob, the provided key is used to decrypt your data after reading it from disk. In both cases, the provided encryption key is securely discarded as soon as the encryption or decryption process completes. |
| RehydratePriority |
An enumeration. |
| PartialBatchErrorException |
There is a partial failure in batch operations. |
| ContainerEncryptionScope |
The default encryption scope configuration for a container. This scope is used implicitly for all future writes within the container, but can be overridden per blob operation. New in version 12.2.0. |
Functions
upload_blob_to_url(blob_url, data, credential=None, **kwargs)
Upload data to a given URL
The data will be uploaded as a block blob.
upload_blob_to_url(blob_url, data, credential=None, **kwargs)
Parameters
- blob_url
- str
The full URI to the blob. This can also include a SAS token.
- data
- bytes or str or Iterable
The data to upload. This can be bytes, text, an iterable or a file-like object.
- credential
The credentials with which to authenticate. This is optional if the blob URL already has a SAS token. The value can be a SAS token string, an 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.
Returns
Blob-updated property dict (Etag and last modified)
Return type
download_blob_from_url(blob_url, output, credential=None, **kwargs)
Download the contents of a blob to a local file or stream.
download_blob_from_url(blob_url, output, credential=None, **kwargs)
Parameters
- blob_url
- str
The full URI to the blob. This can also include a SAS token.
- output
- str or writable stream.
Where the data should be downloaded to. This could be either a file path to write to, or an open IO handle to write to.
- credential
The credentials with which to authenticate. This is optional if the blob URL already has a SAS token or the blob is public. The value can be a SAS token string, an 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.
Return type
generate_account_sas(account_name, account_key, resource_types, permission, expiry, start=None, ip=None, **kwargs)
Generates a shared access signature for the blob service.
Use the returned signature with the credential parameter of any BlobServiceClient, ContainerClient or BlobClient.
generate_account_sas(account_name, account_key, resource_types, permission, expiry, start=None, ip=None, **kwargs)
Parameters
- account_name
- str
The storage account name used to generate the shared access signature.
- account_key
- str
The account key, also called shared key or access key, to generate the shared access signature.
- resource_types
- str or ResourceTypes
Specifies the resource types that are accessible with the account SAS.
- permission
- str or AccountSasPermissions
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.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.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.
- 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.
Returns
A Shared Access Signature (sas) token.
Return type
Examples
Generating a shared access signature.
# Create a SAS token to use to authenticate a new client
from datetime import datetime, timedelta
from azure.storage.blob import ResourceTypes, AccountSasPermissions, generate_account_sas
sas_token = generate_account_sas(
blob_service_client.account_name,
account_key=blob_service_client.credential.account_key,
resource_types=ResourceTypes(object=True),
permission=AccountSasPermissions(read=True),
expiry=datetime.utcnow() + timedelta(hours=1)
)
generate_container_sas(account_name, container_name, account_key=None, user_delegation_key=None, permission=None, expiry=None, start=None, policy_id=None, ip=None, **kwargs)
Generates a shared access signature for a container.
Use the returned signature with the credential parameter of any BlobServiceClient, ContainerClient or BlobClient.
generate_container_sas(account_name, container_name, account_key=None, user_delegation_key=None, permission=None, expiry=None, start=None, policy_id=None, ip=None, **kwargs)
Parameters
- account_name
- str
The storage account name used to generate the shared access signature.
- container_name
- str
The name of the container.
- account_key
- str
The account key, also called shared key or access key, to generate the shared access signature. Either account_key or user_delegation_key must be specified.
- user_delegation_key
- UserDelegationKey
Instead of an account shared key, the user could pass in a user delegation key. A user delegation key can be obtained from the service by authenticating with an AAD identity; this can be accomplished by calling get_user_delegation_key(key_start_time, key_expiry_time, **kwargs). When present, the SAS is signed with the user delegation key instead.
- permission
- str or ContainerSasPermissions
The permissions associated with the shared access signature. The user is restricted to operations allowed by the permissions. Permissions must be ordered read, write, delete, list. 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.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.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.
- policy_id
- str
A unique value up to 64 characters in length that correlates to a stored access policy. To create a stored access policy, use set_container_access_policy(signed_identifiers, public_access=None, **kwargs).
- 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.
Returns
A Shared Access Signature (sas) token.
Return type
Examples
Generating a sas token.
# Use access policy to generate a sas token
from azure.storage.blob import generate_container_sas
sas_token = generate_container_sas(
container_client.account_name,
container_client.container_name,
account_key=container_client.credential.account_key,
policy_id='my-access-policy-id'
)
generate_blob_sas(account_name, container_name, blob_name, snapshot=None, account_key=None, user_delegation_key=None, permission=None, expiry=None, start=None, policy_id=None, ip=None, **kwargs)
Generates a shared access signature for a blob.
Use the returned signature with the credential parameter of any BlobServiceClient, ContainerClient or BlobClient.
generate_blob_sas(account_name, container_name, blob_name, snapshot=None, account_key=None, user_delegation_key=None, permission=None, expiry=None, start=None, policy_id=None, ip=None, **kwargs)
Parameters
- account_name
- str
The storage account name used to generate the shared access signature.
- container_name
- str
The name of the container.
- blob_name
- str
The name of the blob.
- snapshot
- str
An optional blob snapshot ID.
- account_key
- str
The account key, also called shared key or access key, to generate the shared access signature. Either account_key or user_delegation_key must be specified.
- user_delegation_key
- UserDelegationKey
Instead of an account shared key, the user could pass in a user delegation key. A user delegation key can be obtained from the service by authenticating with an AAD identity; this can be accomplished by calling get_user_delegation_key(key_start_time, key_expiry_time, **kwargs). When present, the SAS is signed with the user delegation key instead.
- permission
- str or BlobSasPermissions
The permissions associated with the shared access signature. The user is restricted to operations allowed by the permissions. Permissions must be ordered read, write, delete, list. 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.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.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.
- policy_id
- str
A unique value up to 64 characters in length that correlates to a stored access policy. To create a stored access policy, use set_container_access_policy(signed_identifiers, public_access=None, **kwargs).
- 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.
Returns
A Shared Access Signature (sas) token.