Gaurav Mantri's Personal Blog.

Updates to Windows Azure Service Management REST API

Today, 7th of June 2012 is a big day for Windows Azure. A lot of new features are coming (IaaS, Support for Non-Windows Operating Systems, Windows Azure Websites etc. etc. [I could go on-and-on with the new features]). Check out Windows Azure website at https://www.windowsazure.com for more details.

However in this blog post, I will only focus on the updates made to Windows Azure Service Management API (WASM-API) today.

Preface

As you know, WASM-API is used to manage your hosted services (err.. Cloud Services Smile), storage accounts and much more. Essentially the things you could do on Windows Azure Portal (BTW, do check out the new and extremely fantastic portal as well at https://manage.windowsazure.com/), you could those same things with WASM-API. In fact, the tools we’ve developed at Cerebrata makes heavy use of the same APIs. I’ll not go in details about how to use these APIs. I’m assuming that you’re already familiar with the API.

Furthermore, in this post we’ll only focus on updated/new functionality in the API for existing functionality. For example, there are a new set of APIs published today for managing Virtual Networks which we’re not going to cover in this post. That is something I will cover in some other post (provided nobody else has beaten me to it).

So Let’s Start!!!

New Version

We’ve got a new WASM-API version and that is 2012-03-01. Previous version was 2011-10-01.

What’s New

Following is the list of new functions made available in this release:

Get Package

This function is one of the operations that you can perform on a hosted service. It basically retrieves the package files (cspkg and cscfg files) and copies them in a blob container in a storage account.

More information link: http://msdn.microsoft.com/en-us/library/windowsazure/jj154121

I think it’s quite an important function. I remember answering a question on MSDN forum where somebody asked the exact same question. I guess, now I need to go back to that question and change my answer Smile.

Check Hosted Service Name Availability

This function again is one of the operations you can perform on hosted services. As the name suggests, it checks the availability of a hosted service name. You could use this functionality first before actually trying to create a hosted service.

More information link: http://msdn.microsoft.com/en-us/library/windowsazure/jj154116

Check Storage Account Name Availability

This function is one of the operations you can perform on storage accounts. Like the function above, this function checks the availability of a storage account name. You could use this functionality first before actually trying to create a storage account.

More information link: http://msdn.microsoft.com/en-us/library/windowsazure/jj154125

What’s Updated

Following is the list of functions which are updated and are providing some new information. In general, there are two major changes:

  1. When it comes to hosted services, now you can’t define Anywhere US, Anywhere Europe, or Anywhere Asia regions as the location for your hosted service. You must specify an exact location for your hosted service. In fact, these values are not even returned by List Locations function.
  2. Now you can define custom metadata for your hosted service and storage account. They are termed as “Extended Properties” which is essentially a collection of name/value pairs. You can have a maximum of 50 extended properties of a hosted service or a storage account.

Hosted Services & Deployments

Following functions which are used to manage hosted services and deployments are updated in the latest release:

Create Hosted Service

Apart from what you could have done in the previous version, you can now:

  • Define extended properties for a hosted service at the time of creating it.

More information link: http://msdn.microsoft.com/en-us/library/windowsazure/gg441304

Update Hosted Service

Apart from updating label and/or description of a hosted service, you can now:

  • Update extended properties of a hosted service

More information link: http://msdn.microsoft.com/en-us/library/windowsazure/gg441303

List Hosted Services

Now this function returns additional details about hosted services like:

  • Properties of hosted service which include description, affinity group, location, label, status, created date/time and last updated date/time.
  • Extended properties for hosted service.

More information link: http://msdn.microsoft.com/en-us/library/windowsazure/ee460781

IMHO status, created and last updated date/time values can be quite useful.

Get Hosted Service Properties

Now this function returns additional details about a hosted service like:

  • Status, created date/time and last updated date/time.
    • Extended properties for hosted service.
    • Planned downtime information about a Persistent VM like start & end time of a planned downtime and VM update status.

    More information link: http://msdn.microsoft.com/en-us/library/windowsazure/ee460806

  • Please note that these additional properties are only returned when “embed-detail” parameter is specified and is set to true Otherwise the information returned by this function is similar to the information returned by the previous version of this function. Furthermore, if the hosted service was created using any one of the Anywhere US, Anywhere Europe, Anywhere Asia regions, the Location element will return the location where the hosted service is now allocated.

Create Deployment

Apart from what you could have done in the previous version, you can now:

  • Define extended properties for a deployment at the time of creating it.
  • Use a Shared Access Signature (SAS) URI as value for PackageUrl element.

More information link: http://msdn.microsoft.com/en-us/library/windowsazure/ee460813

Surprisingly, you don’t get the extended properties of a deployment in Get Hosted Service Properties operation which I found kind of odd.

Change Deployment Configuration

Apart from what you could have done in the previous version, you can now:

  • Update extended properties of a deployment with this function.

More information link: http://msdn.microsoft.com/en-us/library/windowsazure/ee460809

Upgrade Deployment

Apart from what you could have done in the previous version, you can now:

  • Update extended properties of a deployment with this function.

More information link: http://msdn.microsoft.com/en-us/library/windowsazure/ee460809

Storage Accounts

Following functions which are used to manage storage accounts are updated in the latest release:

Create Storage Account

Apart from what you could have done in the previous version, you can now:

  • Enable or disable geo-replication of storage account data at the time of creating it. Please note that by default geo-replication is enabled on your storage account.
  • Define extended properties for a hosted service at the time of creating it.

More information link: http://msdn.microsoft.com/en-us/library/windowsazure/hh264518

Update Storage Account

Apart from updating label and/or description of a storage account, you can now:

  • Enable/disable geo-replication status for a storage account.
  • Update extended properties of a hosted service

More information link: http://msdn.microsoft.com/en-us/library/windowsazure/hh264516

Note about enabling/disabling geo-replication:

If you have enabled geo-replication you can elect to disable it by setting this element to false. When disabled, your data is no longer replicated to a secondary data center and any data in the secondary location will be removed.

Enabling geo-replication once it has been disabled will result in the storage account being billed for replicating the current copy of data to the secondary data center. After the existing copy of the data is replicated to the secondary data center, updates are geo-replicated at no additional charge.


List Storage Accounts

Like “List Hosted Services” function, now this function returns additional details about storage accounts like:

  • Properties of storage account which include description, affinity group, location, label, and status.
  • Endpoints for blob, queue and table storage.
  • Extended properties for storage account.

More information link: http://msdn.microsoft.com/en-us/library/windowsazure/ee460787

Get Storage Account Properties

In the new version, this function returns a lot more information about a storage account like:

  • Properties of storage account which include description, affinity group, location, label, and status.
  • Information about storage account geographic replication like if this is enabled for a storage account or not, what’s the primary and secondary regions, their status and last failover time.
  • Endpoints for blob, queue and table storage.
  • Extended properties for storage account.
  • Indication if the storage account is capable of performing virtual machine related operations.

More information link: http://msdn.microsoft.com/en-us/library/windowsazure/ee460802

Affinity Groups

Following functions which are used to manage affinity groups are updated in the latest release:


List Affinity Groups

    This function now returns additional details about affinity groups like:
  • Indication of whether an affinity group is capable of performing virtual machine related operations.

More information link: http://msdn.microsoft.com/en-us/library/windowsazure/ee460797

Get Affinity Group Properties

    This function now returns additional details about an affinity group like:
  • Indication of whether this affinity group is capable of performing virtual machine related operations.

More information link: http://msdn.microsoft.com/en-us/library/windowsazure/ee460789

Locations

Following function which provided information about data center location is updated in the latest release:


List Locations

The list returned by this function will NOT return This function now will NOT return the Anywhere US, Anywhere Europe, Anywhere Asia locations.

More information link: http://msdn.microsoft.com/en-us/library/windowsazure/ee460797

Summary

As you can see a lot of exciting and new stuff is happening in the world of Windows Azure. Following table summarizes the post above:

New Functions:

Name Comments
Get Package Retrieves the deployment package files and saves it in a blob container of your choice.
Check Hosted Service Name Availability Checks the availability of a hosted service name.
Check Storage Account Name Availability Checks the availability of a storage account name.

Updated Functions:

Name What’s Changed
Create Hosted Service Ability to define extended properties for a hosted service.
Update Hosted Service Ability to update extended properties for a hosted service.
List Hosted Services Returns additional information about hosted services like status, creation date/time etc. Also returns extended properties.
Get Hosted Service Properties Returns additional information about a hosted service.
Create Deployment Ability to specify SAS URI as package URI as well as ability to define extended properties for a deployment.
Change Deployment Configuration Ability to update extended properties for a deployment.
Upgrade Deployment Ability to update extended properties for a deployment.
Create Storage Account Ability to enable/disable geo-replication on a storage account as well as the ability to define extended properties for a storage account.
Update Storage Account Ability to enable/disable geo-replication on a storage account as well as the ability to update extended properties for a storage account.
List Storage Accounts Returns additional information about storage accounts like status, endpoints etc. Also returns extended properties.
Get Storage Account Properties Returns additional information about a storage account like status, endpoints, geo-replication status etc. Also returns extended properties.
List Affinity Groups Returns whether an affinity group is capable of performing virtual machine related operations.
Get Affinity Group Properties Returns whether an affinity group is capable of performing virtual machine related operations.
List Locations Will not return the Anywhere US, Anywhere Europe, Anywhere Asia locations.

In the next post, I will talk about the changes in the Windows Azure Storage API.

Stay Tuned!!!

Comments

  1. Devendra says:

    Can you tell me how to use REST API from Web Sites…?
    I tried a lot.. but could not get…

    • There’s a REST API for Websites but unfortunately it is not publicly exposed yet. I would recommend keeping an eye on the Service Management REST API documentation for the release. In the meantime, you could use Windows Azure Cmdlets or CLI tools which support website management. You could possibly look at the source code for these as well to get an idea about the REST API as these tools are nothing but wrappers over REST API. Hope this helps.

Trackbacks

  1. [...] I wrote a blog post yesterday summarizing some of the changes to the Windows Azure Service Management API. You can read this post here: http://gauravmantri.com/2012/06/07/updates-to-windows-azure-service-management-rest-api/. [...]

  2. [...] Updates to Windows Azure Service Management REST API: “…in this post we’ll only focus on updated/new functionality in the API for existing functionality.” [...]

Speak Your Mind

*