PowerShell based Azure Functions

I am writing this for all PowerShell people, after endless hours trawling the web, there’s hardly any info on using Azure Functions with PowerShell and it’s not easy for non-developers or IT Pros who can use PowerShell only. Running PowerShell based Azure Functions allows you to do any type of function based stuff you would normally do with a PowerShell function, feeding it parameter values and getting output. Plus it makes you feel GOOD :) like a developer, where you can sort of create your own APIs!

Using parameters and feeding parameter values to PowerShell functions Vs using Azure Functions, it works slightly different using Azure Functions.

Parameters and parameter values are fed in two different ways, either by using Route paths in your function URL or query based parameters.

All documented here, but let’s take a look at both…

‘Route Path’ based parameters

If I had an Azure Function with a URL of https://marcfunction1.azurewebsites.net/api/ then any relative URL path trailing this would equate to route based parameter values fed into my PowerShell script. The URL to call the Azure Function would look like this:

https://marcfunction1.azurewebsites.net/api/placeholder_function_name/{param1}/{paramBla}/{param3}

An example:

https://marcfunction1.azurewebsites.net/api/austereo/classicrock/value2/value3

Each path being a parameter value to be worked with in my PowerShell based Azure Function.

When the URL above is executed with parameter values, the parameter values can be called upon and utilised inside your script by the the variables below.

  • $REQ_PARAMS_param1
  • $REQ_PARAMS_paramBla
  • $REQ_PARAMS_param3

To setup the these route path parameters, go to the ‘Integrate‘ section of Azure Functions:

2017-10-18_1804

Click on the ‘Advanced Editor‘, you could use the Simple Editor if you want.

2017-10-18_1806

The example below is where you setup both the placeholder name ‘austereo‘ and then all the route path based parameters.

2017-10-18_1824

Below is a full copy of my ‘function.json‘ file which is essentially the brains of the function. You will see a section called route. Mine starts with austereo, which could be any name you like, but if you look at the URL I have used in my examples, you’ll quickly realise that this placeholder name uniquely identifies your Azure Function in amongst all the other Functions. So it’s best to give this a sensible name to easily distinguish it from other functions.

Note that the name you use here for the start of the ‘route path‘ affects both URLs whether you use route path based parameters or query based parameters.

‘Query’ based parameters

Query based parameters are another alternative to feed parameter values into your PowerShell based Azure Function. They are slightly different and are slightly more flexible, whereas you don’t need to pre-define the parameter names prior to execution like you do with route path parameters in the function.json (brains) file. You simply modify the URL using ‘?’ {questions marks}.

https://marcfunction1.azurewebsites.net/api/placeholder_function_name/<Name_Of_Function>?<ParameterName1>=<Parameter1_Value>?<ParameterName2>=<Parameter2_Value>

An example:

https://marcfunction1.azurewebsites.net/api/austereo/AustereoJustPlaying?url=http://legacy.scahw.com.au/classicrock_128.xspf?number=2

Feeding query based parameters into your Azure Function URL are dealt with slightly different in your PowerShell script, swap the PARAM name with QUERY in the variables. See below for what the variables would look like based on my URL examples above.

  • $REQ_QUERY_url
  • $REQ_QUERY_number

Output from the Function

The output of your function is whatever you want it to be from what your function does. However remember this, in my immense time using Azure Functions, I only got it to output strings. So with this in mind, something that can handle strings no matter how large they are is JSON. Remember how I was saying above how working with Azure Functions feels like creating your very own API? Well yes it does, because you should convert your PowerShell object based output from your Azure Function to JSON, so the JSON can be returned ‘at once’ in string format.

$ReturnedResult = $WhateverOutput | ConvertTo-Json

Out-File -Encoding Ascii -FilePath $res -inputObject $ReturnedResult

Calling the Function

Once called, you can either leave the JSON as is, or it’s as simple as converting it back from JSON.

Using the URI route path parameter method:

https://marcfunction1.azurewebsites.net/api/austereo/classicrock_128

Using PowerShell:

$station = 'classicrock_128'
$iwr = Invoke-Webrequest "https://marcfunction1.azurewebsites.net/api/austereo/$station" 
$result = $iwr.ParsedHtml.body.innerText | ConvertFrom-Json
$result

Using the query based parameter method:

https://marcfunction1.azurewebsites.net/api/austereo/AustereoJustPlaying?url=http://legacy.scahw.com.au/classicrock_128.xspf

Using PowerShell:

$url = 'http://legacy.scahw.com.au/classicrock_128.xspf'
$iwr = Invoke-Webrequest "https://marcfunction1.azurewebsites.net/api/austereo/AustereoJustPlaying?url=$url" 
$result = $iwr.ParsedHtml.body.innerText | ConvertFrom-Json
$result

The Actual Function

Below is an example of my actual Function. You will notice that above in the function there is a PowerShell switch statement, I have written it so that it can handle which ever type of parameter you can throw at it – whether it be route path based parameters or query based parameters.

Below is an example of the default Azure Functions template when you setup a new Azure Function:

# POST method: $req
$requestBody = Get-Content $req -Raw | ConvertFrom-Json
$name = $requestBody.name

# GET method: each querystring parameter is its own variable
if ($req_query_name) 
{
 $name = $req_query_name 
}

Out-File -Encoding Ascii -FilePath $res -inputObject "Hello $name"

 

Azure PowerShell

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: