Azure PowerShell: Invoke Runbook using Webhooks and Windows PowerShell
Azure Automation PowerShell Workflow Runbook
Azure Automation enables users to automate tasks that are manual and repetitive in nature by using Runbooks. Runbooks are nothing but a set of tasks that perform some automated implementation in Azure Automation.
Runbooks in Azure Automation are based on Windows PowerShell or Windows PowerShell Workflow. We can code and implement the logic that we want to automate using PowerShell. In this article we will be using PowerShell to fetch JSON data from a REST Service endpoint and mail the data to the business users.
Create Runbook
Let’s get started by creating the runbook.
Specify the Name and we have selected the Runbook type as ‘PowerShell Workflow’. Click Create.
Let edit the runbook which is currently empty.
We will be adding the below PowerShell code which uses the ‘Invoke-WebRequest’ command to call the REST Endpoint and get the JSON data. Once the JSON data has been retrieved, we will use ‘ConvertFrom-Json’ to convert the data from JSON to PowerShell Custom Objects. After that we will use ‘ConvertTo-HTML’ to convert the data to HTML format which will be used as the mail body.
Since we have to mail the data retrieved from REST endpoint to the users, we will be using Office 365 SMTP to relay the mail. Once the parameters are entered we will use the ‘Send-MailMessage’ command to E-mail the data retrieved from REST endpoint to the business users. Once the mail has been send, a custom message indicating successful mail delivery will be shown in the output pane.
workflow FetchRESTData_MailToUsers
{
$request = 'http://services.groupkt.com/state/get/USA/all'
$result = Invoke-WebRequest $request -UseBasicParsing
$JSONResult = $result | ConvertFrom-Json | select -expand RestResponse | select -expand result
$Body = $JSONResult | Select country,name,capital,largest_city| Sort-Object name | ConvertTo-HTML
$SmtpServer = 'smtp.office365.com'
$SmtpUser = 'Priyaranjan@SharePointChronicle.com'
$smtpPassword = ‘<Input Office 365 Password Here>’
$MailtTo = 'kspriyaranjan@gmail.com'
$MailFrom = 'Priyaranjan@SharePointChronicle.com'
$MailSubject = "Test using $SmtpServer"
$Credentials = New-Object System.Management.Automation.PSCredential -ArgumentList $SmtpUser, $($smtpPassword | ConvertTo-SecureString -AsPlainText -Force)
Send-MailMessage -To "$MailtTo" -from "$MailFrom" -Subject $MailSubject -Body "$Body" -SmtpServer $SmtpServer -BodyAsHtml -UseSsl -Credential $Credentials
write-Output "Custom Message : REST Service JSON Data parsed and Email Sent to Business Users"
}
On running the above command in the Test Pane we can see the custom message that is shown after the mail delivery indicating successful run of the runbook .
We have also received the data retrieved from the REST endpoint as a mail in the inbox as shown below.
Since we have successfully tested the runbook, let’s publish it.
This completes the creation of the PowerShell runbook in azure
Webhook
A webhook allows us to start a runbook that we have created in Azure Automation using a single HTTP request. We can use the webhook from a variety of external services like GitHub, Visual Studio Team Services, and custom applications from which we can start Azure runbooks that helps us run some predefined logic. An overall webhook flow is shown in the below image. In this article we will see how to invoke the azure runbook using webhooks from various client applications.
Image Source : /en-us/
Create a Webhook
We have already covered how to create the runbook in Azure and saw how to retrieve JSON Data from REST Endpoint and mail it to business users. Now we need a method to invoke the runbook remotely from our client application. We will be using Webhook for this purpose.
We can create a webhook from the Runbook page of the Azure Automation Account. Thus we can say that the webhook is hooked to a runbook upon its creation. Select the ‘Webhook’ option as shown below:
This will open up the page where we have to specify the below parameters that will be used to create the webhook:
- Name: Specify a name for the webhook
- Enabled: By default, it is enabled. If we disable it, we cannot access it from client applications. We can enable/disable it even after webhook creation.
- Expires: Every webhook comes with an expiration date beyond which it cannot be used. We can change once the webhook is created.
- URL : This is an important property of the webhoook as we will be using this URL to issue the POST HTTP request. The URL cannot be changed and contains an security token that enables the HTTP request to issue the call without any further authentication.
Note: We should note down the URL securely as it serves the purpose of a password. Any user having this URL can issue an HTTP POST request and run the runbook without any further authentication due to the presence of the security token in the URL. Moreover, we can see this URL only during the webhook creation time.
Click OK to save the webhook parameters. The Webhook URL looks like below
Click on Create to provision the runbook webhook.
Going to the runbook page, we can see that the webhook has been created.
Invoke Webhook from PowerShell
We can invoke the Azure Runbook Webhook from the local machine using PowerShell. Ensure that we are using PowerShell 3.0 or above as ‘Invoke-RestMethod’ command is available only in the higher versions.
$request = 'https://s3events.azure-automation.net/webhooks?token=GpU3Gd4E86eBzboUC5ptXl%2f9rXVP%2fuTdC16wJ1M4KsU%3d'
$result = Invoke-RestMethod -Method Post -Uri $request
On running the above script from PowerShell we have invoked the webhook which triggered the runbook that get JSON Data from a REST endpoint and have mailed it to business user. The email screenshot is shown below:
Summary
Thus we saw how to create an Azure PowerShell Runbook and invoke it using webhooks from PowerShell.