Adding SMS notifications to your Windows Azure projects

• Download demo - 5.8 KB

Introduction

In this short post, we’ll see how easy it is to add basic SMS notifications to your Windows Azure projects using the Service Management API (SM-API), Windows PowerShell (along with Cerebrata's Azure Management Cmdlets) and the popular text and voice messaging service, Twilio. If everything goes to plan, you should be receiving SMS notifications within about 15 minutes. 

Scenario 

In this example, we are going to send an SMS notification when a hosted service goes down. This might be useful to a DevOp or an Administrator who is responsible for monitoring and managing an organization’s applications after hours. 

We are going to use PowerShell—we assume most people doing this type of work are using PowerShell—but you could easily invoke the SM-API REST calls through raw HTTPS requests in the language of your choice. In fact, you would almost certainly take the latter approach if you wanted to configure complex rules and alerts, for example, when specific events fire or when some performance counter threshold is hit.

Prerequisites 

Twilio 

To keep things moving quickly, we are going to assume you have a Twilio account. Twilio is a web-service API that lets you quickly build voice and SMS applications using their infrastructure; we use it to send the SMS messages. You can sign up for their free account here. 

There are a number of lightweight wrappers available (C#, Java, PHP) that let you quickly work with their REST API. In the example below, we make use of the twilio-csharp wrapper to show you how easy it is to send SMS messages in C#  

public void SendSmsMessage(){
    const string accountSid = "ACaaa6f2a6caed4959ba559596xxxxxxxx";
    const string authToken = "a2bc2575c75d44db27a0f8c1xxxxxxxx";
    const string sender = "+4475xxxxxxxx";
    const string recipient = "+4475xxxxxxxx"; 
    const string message = " Twilio is awesome!"; 

    TwilioRestClient twilioClient = new TwilioRestClient(accountSid, authToken);
    twilioClient.SendSmsMessage(sender, recipient, message); 
}    

This simple example translates into the following in PowerShell 

Add-Type -Path "D:\Twillo-DLL\Twilio.Api.dll"

$twilio = new-object Twilio.TwilioRestClient($accountSid, $authToken)

$msg = $twilio.SendSmsMessage($sender, $recipient , $message)

PowerShell and Cerebrata Azure Management Cmdlets  

On the PowerShell side, we will be using Cerebrata's Azure Management Cmdlets—a suite of PowerShell Cmdlets that wrap up a large portion of Microsoft’s SM-API, including Cmdlets for managing your Windows Azure hosted services, Windows Azure storage (Blobs, Tables and Queues) and SQL Azure instances. The Cerebrata Azure Management Cmdlets are particularly useful in continuous integration scenarios, when you are trying to streamline and automate deployment tasks. The screenshot below lists some of their Cmdlets to give you a flavor of what they do. 

Windows Azure Service Management API 101 

Okay, so before we dive in and start connecting the different parts, I just wanted to quickly mention the Service Management API. For those of you who don’t know, Microsoft provide a RESTful API to Windows Azure that lets you automate many tasks that would otherwise have to be done manually via the portal. It supports the entire Azure Service lifecycle: deployment, configuration, staging, suspension and deletion. The management service may be accessed from within a service running in Windows Azure, or directly over the Internet from any application that can send an HTTPS request and receive an HTTPS response. Obviously, a full review of the API is beyond the scope of this post (see the Windows Azure docs for a detailed explanation) but to give you an idea of what’s possible, let’s take a look at a basic example.

All operations available via the SM-API are accessed using your Windows Azure subscription ID. In fact, your ID forms part of the URI for every call that you make to the SM-API.

https://management.core.windows.net/<subscriptionId>

Note that all operations to the SM-API are made over SSL and so must use the HTTPS protocol. 

If we take storage account functionality as an example, we can access the available services via the following URI

https://management.core.windows.net/<subscriptionId>/services/storageservices 

From here, we can List Storage Accounts, Get Storage Account Properties, Get Storage Account Keys and Regenerate Storage Account Keys. You can also use the SM-API to create, delete and update storage accounts.

If we take a look at List Storage Accounts, the operation used to obtain the URIs to use for other operations on storage accounts, we make a GET request to the following URI

https://management.core.windows.net/<subscription-id>/services/storageservices 

If all goes well, the request will return a response with a 200 (OK) status code, the response headers and a response body structured as follows:

<?xml version="1.0" encoding="utf-8"?>
  <StorageServices xmlns="http://schemas.microsoft.com/windowsazure">
    <StorageService>
      <Url>storage-account-request-uri</Url>    
      <ServiceName>storage-account-name</ServiceName>  
    </StorageService>  
  </StorageServices> 

The Url is the SM-API request URI used to perform the Get Storage Account Properties request against the storage account, and the ServiceName is the name of the storage account. Specifically, the name is the DNS prefix name and can be used to access Blobs, Queues and Tables in the storage account.

As already mentioned, the SM-API lets you automate and streamline large portions of your Windows Azure deployment, including operations on Storage Accounts, Hosted Services, Certificates, Affinity Groups, Locations and the Traffic Manager. To get a complete list of operations that can be performed, check out Microsoft’s SM-API documention.

Working with the Service Management API 

In order to do anything useful with the SM-API, you need to construct and issue the SM-API requests and process the responses. This can be done in the language of your choosing but involves a certain amount of overhead that isn’t particularly interesting. We’ve included a C# project that shows how to construct and issue the SM-API requests and how to process the resulting response. This project calls the same operations as described above, namely the List Storage Accounts which returns the URIs to be used when performing operations on storage accounts. 

In most continuous integrations scenarios, you simply want to issue commands and perform actions based on your specific workflow. For this reason, there are a number of PowerShell Cmdlets that wrap up the SM-API and let you work with it via the command line. This makes scripting commands really simple and should be familiar to those who are administering and streamlining Windows Azure deployments.

PowerShell and the Service Management API  

The Windows Azure PowerShell Cmdlets by Microsoft provide a basic wrapper to the SM-API, including Cmdlets for managing your Subscriptions, Windows Azure Diagnostics, SQL Azure, Service Bus and the Traffic Manager.

The Cerebrata Azure Management Cmdlets provide PowerShell Cmdlets for managing your Subscriptions, Windows Azure Diagnostics, SQL Azure, Traffic Manager and Windows Azure Storage. The ability to manage your storage (Blobs, Tables and Queues) is one of the biggest differentiators between the two products. The storage related Cmdlets let you backup and restore your storage account data. It also includes Cmdlets that can transfer files from your local machine to Windows Azure. 

Using the code 

The final PowerShell script, which checks the status of a Windows Azure deployment and sends an SMS alert accordingly, is surprisingly simple. The script basically has five parts. 

1. We provide a Windows Azure subscription ID and a valid certificate.
    
2. We specify the hosted service name and the environment slot we wish to query.
    
3. We specify the Twilio account details so that we can send messages via their REST API.
    
4. We check our deployment status every minute using Cerebrata’s Management Cmdlets. You'll almost certainly want to change the processing logic here; the script as is will send a notification every minute.
    
5. We send an SMS notification when our deployment status is not  ‘Running’.  

# Subscription ID
$SubID = "a83f48c8-e343-4b8b-9263-XXXXXXXXXXXX"

$Cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate
$Cert = Get-ChildItem -path cert:\CurrentUser\My\728BAD496C1F5CE767D9D005990DC2CF01A59C0C

# Hosted service name and environment slot
$ServiceName = 'lukejefferson'
$Slot = 'Production'

# Twilio
$sid = "ACaaa6f2a6caed4959baXXXXXXXXXXXXXX"
$token = "a2bc2575c75d44db27XXXXXXXXXXXXXX"
$from = "+4420718XXXXX" 
$to = "+4479213XXXXX"

Add-Type -Path "C:\Temp\Twilio.Api.dll"
$twilio = new-object Twilio.TwilioRestClient($sid, $token)

$SleepTime = 60

$error.clear()

while($true)
{
    $status = New-Object Cerebrata.AzureUtilities.ManagementClient.ServiceManagementEntities.DeploymentStatus
    $deploymentProperty = Get-Deployment -Slot $Slot  -ServiceName $ServiceName -SubscriptionId $SubID -Certificate $Cert 
    $status = $deploymentProperty.DeploymentStatus
    if($status -ne "Running")
    {  
        $messageBody = "ServiceName: " + $ServiceName + "`n" + "Slot: " + $Slot + "`n" + "Status: " + $status
        $msg = $twilio.SendSmsMessage($from, $to , $messageBody)
    }
    Sleep $SleepTime
}  

Note: several variables have had their values obscured. Remember you will need to replace these with your own values.

And if all goes well, you should receive an SMS notification when the services drops out of its running state, as illustrated below. 

Summary  

This post has shown how quickly you can add basic alerting functionality using the Windows Azure Service Management API, PowerShell (along with the Cerebrata Azure Management Cmdlets) and the popular text & voice messaging service, Twilio. Hopefully it’s given you an idea of what’s possible and got you thinking about how and where you might add notifications to your applications. The next step might be to configure alerts to fire when event log data rules or performance counters thresholds are met by inspecting Windows Azure Diagnostic data. 

History 

Please email ljefferson@cerebrata.com with any edits, suggestions or questions. 

April 30 2012 - first version submitted.