migration_guide.md

Storage Blob Service SDK Migration Guide from <= 2.x to 12.x

In this section, we list the main changes you need to be aware of when converting your Storage Blob SDK library from version <= 2.X to version 12.X. In version 12 we also support asynchronous APIs.

Converting Core Classes

<= 2.X synchronous classes have been replaced. New asynchronous counterparts added.

<= 2.X Classes (Clients)	V12 Clients	NEW Asynchronous clients
BlockBlobService	BlobServiceClient	BlobServiceClient
PageBlobService	ContainerClient	ContainerClient
AppendBlobService	BlobClient	BlobClient

Version <= 2.X to Version 12 API Mapping

Version <= 2.X		Version 12.X
Note: Any class means any of BlockBlobService, AppendBlobService or PageBlobService class.
API Name	Class(es) it belongs to	API Name	Class(es) it belongs to
make_blob_url	Any class	It’s an attribute on BlobClient, you can instantiate a BlobClient and call blob_client.url to get the url.	BlobClient
make_container_url	Any class	It’s an attribute on ContainerClient, you can instantiate a ContainerClient and call container_client.url to get the url.	ContainerClient
generate_account_shared_access_signature	Any class	generate_account_sas	It’s not a class method. Just import from azure.storage.blob directly
generate_container_shared_access_signature	Any class	generate_container_sas	It’s not a class method. Just import from azure.storage.blob directly
generate_blob_shared_access_signature	Any class	generate_blob_sas	It’s not a class method. Just import from azure.storage.blob directly
get_user_delegation_key	Any class	get_user_delegation_key	BlobServiceClient
get_blob_service_stats	Any class	get_service_stats	BlobServiceClient
set_blob_service_properties	Any class	set_service_properties	BlobServiceClient
get_blob_service_properties	Any class	get_service_properties	BlobServiceClient
get_blob_account_information	Any class	get_account_information	BlobServiceClient, ContainerClient or BlobClient
list_containers	Any class	list_containers	BlobServiceClient
create_container	Any class	create_container	BlobServiceClient or ContainerClient
get_container_properties	Any class	get_container_properties	ContainerClient
get_container_metadata	Any class
set_container_metadata	Any class	set_container_metadata	ContainerClient
get_container_acl	Any class	get_container_access_policy	ContainerClient
set_container_acl	Any class	set_container_access_policy	ContainerClient
delete_container	Any class	delete_container	ContainerClient
acquire_container_lease	Any class	acquire_lease	ContainerClient or BlobLeaseClient obtained by calling acquire_lease.
renew_container_lease	Any class	renew	BlobLeaseClient This client can be obtained by calling acquire_lease on ContainerClient.
release_container_lease	Any class	release
break_container_lease	Any class	break
change_container_lease	Any class	change
list_blobs	Any class	list_blobs	ContainerClient
list_blob_names	Any class	We are considering adding it back.	N/A
get_blob_properties	Any class	get_blob_properties	BlobClient
get_blob_metadata	Any class
set_blob_properties	Any class	set_http_headers	BlobClient
set_blob_metadata	Any class	set_blob_metadata	BlobClient
exists	Any class	exists	BlobClient
get_blob_to_path	Any class	download_blob	BlobClient
get_blob_to_stream	Any class
get_blob_to_bytes	Any class
get_blob_to_text	Any class
acquire_blob_lease	Any class	acquire_lease	BlobClient or BlobLeaseClient obtained by calling acquire_lease.
renew_blob_lease	Any class	renew	BlobLeaseClient This client can be obtained by calling acquire_lease on BlobClient. BlobClient
release_blob_lease	Any class	release
break_blob_lease	Any class	break
change_blob_lease	Any class	change
snapshot_blob	Any class	create_snapshot	BlobClient
copy_blob	Any class	start_copy_from_url	BlobClient
abort_copy_blob	Any class	abort_copy	BlobClient
delete_blob	Any class	delete_blob	ContainerClient or BlobClient
batch_delete_blobs	Any class	delete_blobs	ContainerClient. We will consider adding this api to BlobServiceClient if we get any customer ask.
undelete_blob	Any class	undelete_blob	BlobClient
put_block	BlockBlobService	Stage_block	BlobClient
put_block_list	BlockBlobService	commit_block_list	BlobClient
get_block_list	BlockBlobService	get_block_list	BlobClient
put_block_from_url	BlockBlobService	stage_block_from_url	BlobClient
create_blob_from_path	BlockBlobService or PageBlobService	upload_blob	BlobClient
create_blob_from_stream	BlockBlobService or PageBlobService
create_blob_from_bytes	BlockBlobService or PageBlobService
create_blob_from_text	BlockBlobService or PageBlobService
append_blob_from_path	AppendBlobService
append_blob_from_bytes	AppendBlobService
append_blob_from_text	AppendBlobService
append_blob_from_stream	AppendBlobService
set_standard_blob_tier	BlockBlobService	set_standard_blob_tier	BlobClient
batch_set_standard_blob_tier	BlockBlobService	set_standard_blob_tier_blobs	ContainerClient
create_blob	AppendBlobService	create_append_blob	BlobClient
append_block	AppendBlobService	append_block	BlobClient
append_block_from_url	AppendBlobService	append_block_from_url	BlobClient
create_blob	PageBlobService	create_page_blob	BlobClient
set_premium_page_blob_tier	PageBlobService	set_premium_page_blob_tier	BlobClient
incremental_copy_blob	PageBlobService	start_copy_from_url	BlobClient
update_page	PageBlobService	upload_page	BlobClient
update_page_from_url	PageBlobService	upload_pages_from_url	BlobClient
clear_page	PageBlobService	clear_page	BlobClient
get_page_ranges	PageBlobService	get_page_ranges	BlobClient
get_page_ranges_diff	PageBlobService		BlobClient
set_sequence_number	PageBlobService	set_sequence_number	BlobClient
resize_blob	PageBlobService	resize_blob	BlobClient

Build Client with Shared Key Credential

Instantiate client in Version 2.X

from azure.storage.blob import BlockBlobService
service = BlockBlobService("<storage-account-name>", "<account-access-key>", endpoint_suffix="<endpoint_suffix>")

Initiate client in Version 12.

from azure.storage.blob import BlobServiceClient

service = BlobServiceClient(account_url="https://<my-storage-account-name>.blob.core.windows.net/", credential={'account_name': "<storage-account-name>", 'account_key': "<account-access-key>"})

Build Client with SAS token

In version 2.X, to generate the SAS token, you needed to instantiate any of BlockBlobService, AppendBlobService or PageBlobService, then use the class method to generate different level of sas.

from azure.storage.blob import BlockBlobService
from azure.storage.common import (
    ResourceTypes,
    AccountPermissions,
)
from datetime import datetime, timedelta

service = BlockBlobService("<storage-account-name>", "<account-access-key>", endpoint_suffix="<endpoint_suffix>")
                        
token = service.generate_account_shared_access_signature(
    ResourceTypes.CONTAINER,
    AccountPermissions.READ,
    datetime.utcnow() + timedelta(hours=1),
)

# Create a service and use the SAS
sas_service = BlockBlobService(
    account_name="<storage-account-name>",
    sas_token=token,
)

In V12, SAS token generation is a standalone api, it's no longer a class method.

from datetime import datetime, timedelta
from azure.storage.blob import BlobServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

blob_service_client = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential=sas_token)

Build Client with OAuth Credentials

V 2.X using oauth credential to instantiate a service client.

from azure.storage.common import (
    TokenCredential,
)
import adal

context = adal.AuthenticationContext(
    str.format("{}/{}", "<active_directory_auth_endpoint>", "<active_directory_tenant_id>"),
    api_version=None, validate_authority=True)

token = context.acquire_token_with_client_credentials(
    "https://storage.azure.com",
    "<active_directory_application_id>",
    "<active_directory_application_secret>")["accessToken"]
token_credential = TokenCredential(token)

service = BlockBlobService("<storage_account_name>", token_credential=token_credential)

In V12, you can leverage azure-identity package.

from azure.identity import ClientSecretCredential
token_credential = ClientSecretCredential(
    "<active_directory_tenant_id>",
    "<active_directory_application_id>",
    "<active_directory_application_secret>"
)

# Instantiate a BlobServiceClient using a token credential
from azure.storage.blob import BlobServiceClient
blob_service_client = BlobServiceClient("https://<my-storage-account-name>.blob.core.windows.net", credential=token_credential)

Download Blob

In V2.X, you can call get_blob_to_stream, get_blob_to_path, get_blob_to_bytes, get_blob_to_text. These APIs return a Blob object. Here's an example of get_blob_to_text.

from azure.storage.blob import BlockBlobService
service = BlockBlobService("<storage-account-name>", "<account-access-key>", endpoint_suffix="<endpoint_suffix>")
blob_object = service.get_blob_to_text("<container_name>", "<blob_name>")
text_content = blob_object.content

In V12, the download operation can be done through the download_blob API. Here's the equivalent of get_blob_to_text.

from azure.storage.blob import BlobServiceClient
service_client = BlobServiceClient(account_url="https://<my-storage-account-name>.blob.core.windows.net/", credential={'account_name': "<storage-account-name>", 'account_key': "<account-access-key>"})
blob_client = service_client.get_blob_client("<container_name>", "<blob_name>")
stream_downloader = blob_client.download_blob(max_concurrency=2, encoding='UTF-8')
text_content = stream_downloader.readall()