PowerShell REST API

By using the PowerShell scripting language, you can develop a client application that interacts with the IBM Spectrum Protect Plus REST API.

Applicable PowerShell releases: The provided examples are based on PowerShell Core 7.0 and 7.1.

Getting a session ID by using PowerShell

Assume that you want to work with an IBM Spectrum Protect Plus virtual appliance with the following configuration:

  • IPv4 address: 10.0.0.100

  • Username: Sarah

  • Password: MyPassw0rd!

  • SSL verification: False, ignore warnings.

The following PowerShell script loads values to access the REST API.

$sppUrl      = "https://10.0.0.100"
$sppUsername = "Sarah"
$sppPassword = ConvertTo-SecureString -String "MyPassw0rd!" -AsPlainText -Force
$sppCred     = New-Object `
   -TypeName System.Management.Automation.PSCredential `
   -ArgumentList ($sppUsername, $sppPassword)

$sppResponse = Invoke-RestMethod `
    -Method Post `
    -Uri $($sppUrl + '/api/endeavour/session') `
    -Authentication Basic `
    -Credential $sppCred `
    -Headers @{
        'Accept'       = 'application/json'
        'Content-type' = 'application/json'
    } `
    -SkipCertificateCheck

Write-Output $sppResponse

The request prompts a response that is structured as shown:

sessionid         : db13bc848462424d919afef01ec691cd
user              : @{links=; name=sppadmin; type=NATIVE_USER; ..., id=1000}
demo              : False
preferences       : @{inactivityTimeout=30; ...; minPasswordLength=8}
tenantAdmin       : True
userGroups        : {}
timeZone          : UTC
useServerTime     : False
passwordExpired   : False
usernameExpired   : False
accountDisabled   : False
passwordAge       : 0
passwordExpiresAt : 0

After the previous script runs, the following PowerShell snippet is used to retrieve a session ID from the target IBM Spectrum Protect Plus application:

$sppSessionid = $sppResponse.sessionid

Write-Output $sppSessionid
db13bc848462424d919afef01ec691cd

You can use the obtained session ID for subsequent operations. For more information about session IDs, follow the instructions in Creating a session ID.

Sending a request to the REST API by using PowerShell

Assume that you append the following PowerShell snippet to the previous script. The snippet sends an HTTP request to the REST API to display a list of jobs:

$sppHeaders = @{
    'X-Endeavour-Sessionid' = $sppSessionid
    'Accept'                = 'application/json'
    'Content-type'          = 'application/json'
    }

$sppResponse = Invoke-RestMethod `
    -Method  Get `
    -Uri     $($sppUrl + '/api/endeavour/job/') `
    -Headers $sppHeaders `
    -SkipCertificateCheck

Write-Output $sppResponse

The request prompts a response that is structured as shown:

links                          total page jobs
-----                          ----- ---- ----
@{self=; up=; create=; stats=}     4    1 {@{links=; name=Maintenance; ...

The jobs object is formatted in JSON. Get this object and convert it to a system array:

$sppJobs = $sppResponse.jobs | ConvertTo-JSON | ConvertFrom-JSON

Write-Output $sppJobs

The request prompts a response that is structured as shown:

links                        : @{self=@{rel=self; href=https://10.0.0.100/...
name                         : Maintenance
description                  : Auto-generated job for maintenance
policyId                     : 1001
...

links                        : ...
name                         : Storage Server Inventory
description                  : Auto-generated job for maintenance
policyId                     : 1002
...

links                        : ...
name                         : Hypervisor Inventory
description                  :
policyId                     : 1003
...

links                        : ...
name                         : Application Server Inventory
description                  :
policyId                     : 1004
...

You can retrieve the properties that you require. For example, retrieve the properties name and policyId:

Write-Output $sppJobs | Select-Object -Property name,policyId | Format-Table

The request prompts a response that is structured as shown:

name                         policyId
----                         --------
Maintenance                  1001
Storage Server Inventory     1002
Hypervisor Inventory         1003
Application Server Inventory 1004

The IBM Spectrum Protect Plus REST API has a consistent structure. You can use PowerShell scripts that are similar to this example to develop applications that send requests to the REST API.

Decoding URIs with parameters by using PowerShell

You can decode URI strings with parameters by using a PowerShell snippet.

Assume that you captured the following HTTP request by using Mozilla Firefox:

curl 'https://10.0.0.100/api/hypervisor?from=hlo&pageSize=100&
↪sort=%5B%7B%22property%22:%22name%22,%22direction%22:%22ASC%22%7D%5D&
↪filter=%5B%7B%22property%22:%22type%22,%22value%22:%22vmware%22,
↪%22op%22:%22=%22%7D%5D'
  -H 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:71.0) ...'
...

A PowerShell snippet that is similar to the following example can be used to decode the URI string:

$uriOriginal = "https://10.0.0.100/api/hypervisor?from=hlo&pageSize=100&" `
  + "sort=%5B%7B%22property%22:%22name%22,%22direction%22:%22ASC%22%7D%5D&" `
  + "filter=%5B%7B%22property%22:%22type%22,%22value%22:%22vmware%22," `
  + "%22op%22:%22=%22%7D%5D"

$uriDecoded = [System.Web.HttpUtility]::UrlDecode($uriOriginal)
Write-Output $uriDecoded

The request prompts a response that is structured as shown:

https://10.0.0.100/api/hypervisor?from=hlo&pageSize=100&
↪sort=[{"property":"name","direction":"ASC"}]&
↪filter=[{"property":"type","value":"vmware","op":"="}]

Tip

If you receive the error message, “Unable to find type [System.Web.HttpUtility]”, ensure that you are using PowerShell Core 7.0 or 7.1. Load the Microsoft .NET Framework class System.Web into the PowerShell session:

Add-Type -AssemblyName System.Web