First published on TECHNET on May 25, 2011
As I’m playing around with our pre-beta build of Orchestrator, I’m building lots of little tools for interacting with it in a number of ways. I had been doing some PowerShell to interact with the COM interfaces so I could import and export runbooks, but I also needed an easy way to access things like the start parameters of a runbook so I could invoke it with the right parameters. Since Orchestrator 2012 has a new REST-based web service with lots of functionality, I naturally thought of how I could use that. I didn’t want to build a full-fledged app, so I wondered if I could interact with it using PowerShell scripts. The answer is – of course!
A quick
Bing
search led me to this blog post,
http://spowser.wordpress.com/2009/03/13/powershell-rest-client/
, where the author creates a simple REST client using a script. I Adapted that code a little and produced a quick script that would let me send URL strings and get back an XML object, a raw XML string, or a JSON-formatted string. It was surprisingly easy. The hard part is making sure you have the URL query string correct. I’ll build out more stuff on that later, but for now I just wanted to share the simple REST client.
Here’s the code. There are three functions; “Request-REST” which does the request and gets back the data, “Create-Credentials” which simplifies creating a NetworkCredential object for use by Request-Rest, and a Fix-URI function to ensure the URI string is formatted correctly with a trailing slash.
function Request-Rest{
[CmdletBinding()]
PARAM (
[Parameter(Mandatory=$true)]
[String] $URL,
[Parameter(Mandatory=$true)]
[System.Net.NetworkCredential] $credentials,
[Parameter(Mandatory=$false)]
[String] $UserAgent = "PowerShell API Client",
[Parameter(Mandatory=$false)]
[Switch] $JSON,
[Parameter(Mandatory=$false)]
[Switch] $Raw
)
#Create a URI instance since the HttpWebRequest.Create Method will escape the URL by default.
$URL = Fix-Url $Url
$URI = New-Object System.Uri($URL,$true)
#Create a request object using the URI
$request = [System.Net.HttpWebRequest]::Create($URI)
#Build up a nice User Agent
$request.UserAgent = $(
"{0} (PowerShell {1}; .NET CLR {2}; {3})" -f $UserAgent, $(if($Host.Version){$Host.Version}else{"1.0"}),
[Environment]::Version,
[Environment]::OSVersion.ToString().Replace("Microsoft Windows ", "Win")
)
$request.Credentials = $credentials
if ($PSBoundParameters.ContainsKey('JSON'))
{
$request.Accept = "application/json"
}
try
{
[System.Net.HttpWebResponse] $response = [System.Net.HttpWebResponse] $request.GetResponse()
}
catch
{
Throw "Exception occurred in $($MyInvocation.MyCommand): `n$($_.Exception.Message)"
}
$reader = [IO.StreamReader] $response.GetResponseStream()
if (($PSBoundParameters.ContainsKey('JSON')) -or ($PSBoundParameters.ContainsKey('Raw')))
{
$output = $reader.ReadToEnd()
}
else
{
[xml]$output = $reader.ReadToEnd()
}
$reader.Close()
Write-Output $output
$response.Close()
}
function Create-Credentials{
[CmdletBinding()]
PARAM (
[Parameter(Mandatory=$true)]
[String] $domain,
[Parameter(Mandatory=$true)]
[String] $username,
[Parameter(Mandatory=$true)]
[String] $password
)
$creds = New-Object System.Net.NetworkCredential($username,$password,$domain)
return $creds
}
Function Fix-Url ($url) {
if($url.EndsWith('/') -Or $url.EndsWith('\')) {
return $url
}
"$url/"
}
Now just create a credentials object like this:
$creds = Create-Credentials "DOMAIN" "USERNAME" "PASSWORD"
and then use the credentials in the command. Here are examples of the three formats:
Request-Rest -URL "http://SCOSERVER:81/Orchestrator.svc/Folders/" -credentials $creds
Request-Rest -URL "http://SCOSERVER:81/Orchestrator.svc/Folders/" -credentials $creds –Raw
Request-Rest -URL "http://SCOSERVER:81/Orchestrator.svc/Folders/" -credentials $creds –JSON
Depending on the switch you used you will either get an XML object, a raw XML string, or JSON-formatted string.
Enjoy!
