January 15th, 2021

How to migrate to the new Azure Python Management Libraries

Kaihui Sun
Kaihui Sun
Engineer 2

Why did we create the new Azure SDK for Python Management Libraries?

The goal of our management libraries is to enhance the productivity of developers managing Azure resources and provide idiomatic, consistent, approachable, diagnosable, and dependable code to easily integrate with Azure resources. We’ve been listening to customer feedback and we’ve made sure that our new effort has incorporated those suggestions and requests. Finally, we understand that ease of use, service coverage, documentation, and consistency are equally important when it comes to Azure resource management.

We have made improvements in the following areas: * Create easy-to-use APIs with productivity that is on par with the best libraries of the language ecosystems. * Provide APIs that are idiomatic to Python. * Evolve over time in a very compatible fashion. * Focus as much on documentation and samples, as on APIs. * Change how we create the libraries at their core. (See our blog post, AutoRest and OpenAPI: The backbone of Azure SDK, for more details)

Which SDKs have been upgraded to the new version?

We are constantly improving the SDK to provide a better developer experience. You can find the full list of latest versions at azure.github.io/azure-sdk.

The versions that start with “b” means the packages are still in beta state. The versions without “b” are stable versions and ready for production uses. If you intend to use the SDK in a production environment, please use one of the stable versions.

NOTE: Since the package name remains the same between the old and new generation of SDKs, your application may automatically pull the latest new version. If you do not intend to upgrade, you can always pin a specific version of the package.

For example, you can run command pip install azure-mgmt-storage==11.2.0 to install previous version.

How to migrate to the new Azure SDK for Python Management libraries?

Some of the key differences between old and new management libraries are that they depend on different core libraries and code-generators.

The following is the key differences and highlights:

Azure Identity Support for Authentication

There are two differences: * ServicePrincipalCredentials in azure.common for identity verification has been replaced with TokenCredential based classes in azure.identity. * The keyword credentials in Client is replaced by credential

To use Azure Identity, we need to install the dependecy using pip install azure-identity.

After installation of the package, we will need to modify the existing authentication code to use the new Identity features:

# Previous Version
import azure.mgmt.compute
from azure.common.credentials import ServicePrincipalCredentials

credentials = ServicePrincipalCredentials(
    client_id=client_id,
    secret=client_secret,
    tenant=tenant_id
)
compute_client = azure.mgmt.compute.ComputeManagementClient(credentials=credentials, subscription_id=self.subscription_id)

# New Version
import azure.mmgt.compute
from azure.identity import ClientSecretCredential

credential = ClientSecretCredential(
    tenant_id=tenant_id,
    client_id=client_id,
    client_secret=client_secret
)
compute_client = azure.mgmt.compute.ComputeManagementClient(credential=credential, subscription_id=self.subscription_id)

Long Running Operations (LRO) Method Names

In the new version, many operations like ComputeManagementClient.virtual_machines.begin_create_or_update return an object of type AzureOperationPoller; these methods are asynchronous. Older libraries that aren’t based on azure.core typically use names like create_or_update. In the new version, libraries are based on azure.core and they add the begin_ prefix to method names to clearly indicate that they are asynchronous. Migrating old code to a newer version of SDK typically means adding the begin_ prefix to method names. That being said, most method signatures remain the same.

For example, we want to create a new VM in Azure:

# Previous Version
result = compute_client.virtual_machines.create_or_update(
    group_name,
    vm_name,
    parameters
)
result = result.result()

# New Version
result = compute_client.virtual_machines.begin_create_or_update(
    group_name,
    vm_name,
    parameters
)
vm = result.result()

Unified operation parameter style

In previous library versions, many operations allow you to express object argument either as discrete objects or as inline JSON, but some operations do not.

For example, there is an check name availability operation in storage. The request body is:

{
  "name": "sto3363",
  "type": "Microsoft.Storage/storageAccounts"
}

In the previous library version, you just need to provide a string which is string type like: StorageClient.storage_accounts.check_name_availability(name="sto3363").

In order to keep the style consistent in the new libraries, all operations that need request body will need to express objects argument. So the operation check_name_availability in the new libraries will be:

account_name_model = {
  "name": "sto3363",
  "type": "Microsoft.Storage/storageAccounts"
}
result = storage_client.storage_accounts.check_name_availability(account_name=account_name_model)

Summary

In this blog post we have explained the basic information of the new Azure SDK for Python Management Libraries and how to migrate to the new version of the SDK from old versions. For more information on how to use the python SDK, please refer to Use the Azure libraries (SDK) for Python.

Azure SDK Releases

Azure SDK Blog Contributions

Thank you for reading this Azure SDK blog post! We hope that you learned something new and welcome you to share this post. We are open to Azure SDK blog contributions. Please contact us at azsdkblog@microsoft.com with your topic and we’ll get you setup as a guest blogger.

Azure SDK Links

Category
Azure SDK
Topics
managementpythonsdk

Author

Kaihui Sun
Kaihui Sun
Engineer 2

0 comments

Discussion are closed.

Read next