AppendBlobService class

Definition

An append blob is comprised of blocks and is optimized for append operations. When you modify an append blob, blocks are added to the end of the blob only, via the append_block operation. Updating or deleting of existing blocks is not supported. Unlike a block blob, an append blob does not expose its block IDs.

Each block in an append blob can be a different size, up to a maximum of 4 MB, and an append blob can include up to 50,000 blocks. The maximum size of an append blob is therefore slightly more than 195 GB (4 MB X 50,000 blocks).

AppendBlobService(account_name=None, account_key=None, sas_token=None, is_emulated=False, protocol='https', endpoint_suffix='core.windows.net', custom_domain=None, request_session=None, connection_string=None, socket_timeout=None, token_credential=None)
Inheritance
AppendBlobService

Variables

MAX_BLOCK_SIZE
int
The size of the blocks put by append_blob_from_* methods. Smaller blocks may be put if there is less data provided. The maximum block size the service supports is 4MB.

Methods

append_blob_from_bytes

Appends to the content of an existing blob from an array of bytes, with automatic chunking and progress notifications.

append_blob_from_path

Appends to the content of an existing blob from a file path, with automatic chunking and progress notifications.

append_blob_from_stream

Appends to the content of an existing blob from a file/stream, with automatic chunking and progress notifications.

append_blob_from_text

Appends to the content of an existing blob from str/unicode, with automatic chunking and progress notifications.

append_block

Commits a new block of data to the end of an existing append blob.

append_block_from_url

Creates a new block to be committed as part of a blob, where the contents are read from a source url.

create_blob

Creates a blob or overrides an existing blob. Use if_none_match=* to prevent overriding an existing blob.

See create_blob_from_* for high level functions that handle the creation and upload of large blobs with automatic chunking and progress notifications.

append_blob_from_bytes

Appends to the content of an existing blob from an array of bytes, with automatic chunking and progress notifications.

append_blob_from_bytes(container_name, blob_name, blob, index=0, count=None, validate_content=False, maxsize_condition=None, progress_callback=None, lease_id=None, timeout=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, cpk=None)

Parameters

container_name
str
Required

Name of existing container.

blob_name
str
Required

Name of blob to create or update.

blob
bytes
Required

Content of blob as an array of bytes.

index
int
default value: 0

Start index in the array of bytes.

count
int
default value: None

Number of bytes to upload. Set to None or negative value to upload all bytes starting from index.

validate_content
bool
default value: False

If true, calculates an MD5 hash for each chunk of the blob. The storage service checks the hash of the content that has arrived with the hash that was sent. This is primarily valuable for detecting bitflips on the wire if using http instead of https as https (the default) will already validate. Note that this MD5 hash is not stored with the blob.

maxsize_condition
int
default value: None

Optional conditional header. The max length in bytes permitted for the append blob. If the Append Block operation would cause the blob to exceed that limit or if the blob size is already greater than the value specified in this header, the request will fail with MaxBlobSizeConditionNotMet error (HTTP status code 412 - Precondition Failed).

progress_callback
func(current, total)
default value: None

Callback for progress with signature function(current, total) where current is the number of bytes transfered so far, and total is the size of the blob, or None if the total size is unknown.

lease_id
str
default value: None

Required if the blob has an active lease.

timeout
int
default value: None

The timeout parameter is expressed in seconds. This method may make multiple calls to the Azure service and the timeout will apply to each call individually.

if_modified_since
datetime
default value: None

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetime 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
default value: None

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetime 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
default value: None

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
default value: None

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.

cpk
CustomerProvidedEncryptionKey
default value: None

Encrypts the data on the service-side with the given key. Use of customer-provided keys must be done over HTTPS. As the encryption key itself is provided in the request, a secure connection must be established to transfer the key.

Returns

ETag and last modified properties for the Append Blob

Return type

append_blob_from_path

Appends to the content of an existing blob from a file path, with automatic chunking and progress notifications.

append_blob_from_path(container_name, blob_name, file_path, validate_content=False, maxsize_condition=None, progress_callback=None, lease_id=None, timeout=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, cpk=None)

Parameters

container_name
str
Required

Name of existing container.

blob_name
str
Required

Name of blob to create or update.

file_path
str
Required

Path of the file to upload as the blob content.

validate_content
bool
default value: False

If true, calculates an MD5 hash for each chunk of the blob. The storage service checks the hash of the content that has arrived with the hash that was sent. This is primarily valuable for detecting bitflips on the wire if using http instead of https as https (the default) will already validate. Note that this MD5 hash is not stored with the blob.

maxsize_condition
int
default value: None

Optional conditional header. The max length in bytes permitted for the append blob. If the Append Block operation would cause the blob to exceed that limit or if the blob size is already greater than the value specified in this header, the request will fail with MaxBlobSizeConditionNotMet error (HTTP status code 412 - Precondition Failed).

progress_callback
func(current, total)
default value: None

Callback for progress with signature function(current, total) where current is the number of bytes transfered so far, and total is the size of the blob, or None if the total size is unknown.

lease_id
str
default value: None

Required if the blob has an active lease.

timeout
int
default value: None

The timeout parameter is expressed in seconds. This method may make multiple calls to the Azure service and the timeout will apply to each call individually.

if_modified_since
datetime
default value: None

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetime 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
default value: None

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetime 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
default value: None

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
default value: None

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.

cpk
CustomerProvidedEncryptionKey
default value: None

Encrypts the data on the service-side with the given key. Use of customer-provided keys must be done over HTTPS. As the encryption key itself is provided in the request, a secure connection must be established to transfer the key.

Returns

ETag and last modified properties for the Append Blob

Return type

append_blob_from_stream

Appends to the content of an existing blob from a file/stream, with automatic chunking and progress notifications.

append_blob_from_stream(container_name, blob_name, stream, count=None, validate_content=False, maxsize_condition=None, progress_callback=None, lease_id=None, timeout=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, cpk=None)

Parameters

container_name
str
Required

Name of existing container.

blob_name
str
Required

Name of blob to create or update.

stream
io.IOBase
Required

Opened stream to upload as the blob content.

count
int
default value: None

Number of bytes to read from the stream. This is optional, but should be supplied for optimal performance.

validate_content
bool
default value: False

If true, calculates an MD5 hash for each chunk of the blob. The storage service checks the hash of the content that has arrived with the hash that was sent. This is primarily valuable for detecting bitflips on the wire if using http instead of https as https (the default) will already validate. Note that this MD5 hash is not stored with the blob.

maxsize_condition
int
default value: None

Conditional header. The max length in bytes permitted for the append blob. If the Append Block operation would cause the blob to exceed that limit or if the blob size is already greater than the value specified in this header, the request will fail with MaxBlobSizeConditionNotMet error (HTTP status code 412 - Precondition Failed).

progress_callback
func(current, total)
default value: None

Callback for progress with signature function(current, total) where current is the number of bytes transfered so far, and total is the size of the blob, or None if the total size is unknown.

lease_id
str
default value: None

Required if the blob has an active lease.

timeout
int
default value: None

The timeout parameter is expressed in seconds. This method may make multiple calls to the Azure service and the timeout will apply to each call individually.

if_modified_since
datetime
default value: None

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetime 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
default value: None

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetime 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
default value: None

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
default value: None

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.

cpk
CustomerProvidedEncryptionKey
default value: None

Encrypts the data on the service-side with the given key. Use of customer-provided keys must be done over HTTPS. As the encryption key itself is provided in the request, a secure connection must be established to transfer the key.

Returns

ETag and last modified properties for the Append Blob

Return type

append_blob_from_text

Appends to the content of an existing blob from str/unicode, with automatic chunking and progress notifications.

append_blob_from_text(container_name, blob_name, text, encoding='utf-8', validate_content=False, maxsize_condition=None, progress_callback=None, lease_id=None, timeout=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, cpk=None)

Parameters

container_name
str
Required

Name of existing container.

blob_name
str
Required

Name of blob to create or update.

text
str
Required

Text to upload to the blob.

encoding
str
default value: utf-8

Python encoding to use to convert the text to bytes.

validate_content
bool
default value: False

If true, calculates an MD5 hash for each chunk of the blob. The storage service checks the hash of the content that has arrived with the hash that was sent. This is primarily valuable for detecting bitflips on the wire if using http instead of https as https (the default) will already validate. Note that this MD5 hash is not stored with the blob.

maxsize_condition
int
default value: None

Optional conditional header. The max length in bytes permitted for the append blob. If the Append Block operation would cause the blob to exceed that limit or if the blob size is already greater than the value specified in this header, the request will fail with MaxBlobSizeConditionNotMet error (HTTP status code 412 - Precondition Failed).

progress_callback
func(current, total)
default value: None

Callback for progress with signature function(current, total) where current is the number of bytes transfered so far, and total is the size of the blob, or None if the total size is unknown.

lease_id
str
default value: None

Required if the blob has an active lease.

timeout
int
default value: None

The timeout parameter is expressed in seconds. This method may make multiple calls to the Azure service and the timeout will apply to each call individually.

if_modified_since
datetime
default value: None

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetime 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
default value: None

A DateTime value. Azure expects the date value passed in to be UTC. If timezone is included, any non-UTC datetime 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
default value: None

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
default value: None

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.

cpk
CustomerProvidedEncryptionKey
default value: None

Encrypts the data on the service-side with the given key. Use of customer-provided keys must be done over HTTPS. As the encryption key itself is provided in the request, a secure connection must be established to transfer the key.

Returns

ETag and last modified properties for the Append Blob

Return type

append_block

Commits a new block of data to the end of an existing append blob.

append_block(container_name, blob_name, block, validate_content=False, maxsize_condition=None, appendpos_condition=None, lease_id=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, timeout=None, cpk=None)

Parameters

container_name
str
Required

Name of existing container.

blob_name
str
Required

Name of existing blob.

block
bytes
Required

Content of the block in bytes.

validate_content
bool
default value: False

If true, calculates an MD5 hash of the block content. The storage service checks the hash of the content that has arrived with the hash that was sent. This is primarily valuable for detecting bitflips on the wire if using http instead of https as https (the default) will already validate. Note that this MD5 hash is not stored with the blob.

maxsize_condition
int
default value: None

Optional conditional header. The max length in bytes permitted for the append blob. If the Append Block operation would cause the blob to exceed that limit or if the blob size is already greater than the value specified in this header, the request will fail with MaxBlobSizeConditionNotMet error (HTTP status code 412 - Precondition Failed).

appendpos_condition
int
default value: None

Optional conditional header, used only for the Append Block operation. A number indicating the byte offset to compare. Append Block will succeed only if the append position is equal to this number. If it is not, the request will fail with the AppendPositionConditionNotMet error (HTTP status code 412 - Precondition Failed).

lease_id
str
default value: None

Required if the blob has an active lease.

if_modified_since
datetime
default value: None

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
default value: None

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
default value: None

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
default value: None

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.

cpk
CustomerProvidedEncryptionKey
default value: None

Encrypts the data on the service-side with the given key. Use of customer-provided keys must be done over HTTPS. As the encryption key itself is provided in the request, a secure connection must be established to transfer the key.

timeout
int
default value: None

The timeout parameter is expressed in seconds.

Returns

ETag, last modified, append offset, and committed block count properties for the updated Append Blob

Return type

append_block_from_url

Creates a new block to be committed as part of a blob, where the contents are read from a source url.

append_block_from_url(container_name, blob_name, copy_source_url, source_range_start=None, source_range_end=None, source_content_md5=None, source_if_modified_since=None, source_if_unmodified_since=None, source_if_match=None, source_if_none_match=None, maxsize_condition=None, appendpos_condition=None, lease_id=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, timeout=None, cpk=None)

Parameters

container_name
str
Required

Name of existing container.

blob_name
str
Required

Name of blob.

copy_source_url
str
Required

The URL of the source data. It can point to any Azure Blob or File, that is either public or has a shared access signature attached.

source_range_start
int
default value: None

This indicates the start of the range of bytes(inclusive) that has to be taken from the copy source.

source_range_end
int
default value: None

This indicates the end of the range of bytes(inclusive) that has to be taken from the copy source.

source_content_md5
str
default value: None

If given, the service will calculate the MD5 hash of the block content and compare against this value.

source_if_modified_since
datetime
default value: None

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 source resource has been modified since the specified time.

source_if_unmodified_since
datetime
default value: None

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 source resource has not been modified since the specified date/time.

source_if_match
str
default value: None

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

source_if_none_match
str
default value: None

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

maxsize_condition
int
default value: None

Optional conditional header. The max length in bytes permitted for the append blob. If the Append Block operation would cause the blob to exceed that limit or if the blob size is already greater than the value specified in this header, the request will fail with MaxBlobSizeConditionNotMet error (HTTP status code 412 - Precondition Failed).

appendpos_condition
int
default value: None

Optional conditional header, used only for the Append Block operation. A number indicating the byte offset to compare. Append Block will succeed only if the append position is equal to this number. If it is not, the request will fail with the AppendPositionConditionNotMet error (HTTP status code 412 - Precondition Failed).

lease_id
str
default value: None

Required if the blob has an active lease.

if_modified_since
datetime
default value: None

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
default value: None

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
default value: None

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
default value: None

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.

cpk
CustomerProvidedEncryptionKey
default value: None

Encrypts the data on the service-side with the given key. Use of customer-provided keys must be done over HTTPS. As the encryption key itself is provided in the request, a secure connection must be established to transfer the key.

timeout
int
default value: None

The timeout parameter is expressed in seconds.

create_blob

Creates a blob or overrides an existing blob. Use if_none_match=* to prevent overriding an existing blob.

See create_blob_from_* for high level functions that handle the creation and upload of large blobs with automatic chunking and progress notifications.

create_blob(container_name, blob_name, content_settings=None, metadata=None, lease_id=None, if_modified_since=None, if_unmodified_since=None, if_match=None, if_none_match=None, timeout=None, cpk=None)

Parameters

container_name
str
Required

Name of existing container.

blob_name
str
Required

Name of blob to create or update.

content_settings
ContentSettings
default value: None

ContentSettings object used to set blob properties.

metadata
dict(str, str)
default value: None

Name-value pairs associated with the blob as metadata.

lease_id
str
default value: None

Required if the blob has an active lease.

if_modified_since
datetime
default value: None

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
default value: None

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
default value: None

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
default value: None

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.

cpk
CustomerProvidedEncryptionKey
default value: None

Encrypts the data on the service-side with the given key. Use of customer-provided keys must be done over HTTPS. As the encryption key itself is provided in the request, a secure connection must be established to transfer the key.

timeout
int
default value: None

The timeout parameter is expressed in seconds.

Returns

ETag and last modified properties for the updated Append Blob

Return type

Attributes

MAX_BLOCK_SIZE

MAX_BLOCK_SIZE = 4194304