Quick Start - SCOM REST API

Written By Leon Laude

There is not much information available of the System Center Operations Manager (SCOM) REST API, this blog post will be a quick start on how to start using the SCOM REST API.

1. Introduction

5f9df-featured_image-scom_rest_api.png

I am very new to REST API so this is not going to be a deep dive post, instead it will be a brief introduction of what it REST API actually is and what it can do.

I will also provide some SCOM REST API examples so that SCOM users/admins out there can get started playing around with this, as there is a big lack of examples out there.

1.1 What is REST API?

REST API, or RESTful API, is an application program interface that uses HTTP requests to GET, POST, PUT and DELETE data.

  • REST = REpresentational State Transfer

  • API = Application Programming Interface

REST is commonly used worldwide because of its minimal bandwidth usage, compared to SOAP (Simple Object Access Protocol).

REST is a logical choice for building APIs that can allow users to connect, manage and interact with various of different services.

A REST API breaks down transactions to create a series of small modules, each module addresses a particular underlying part of the transaction.

So what happens when during a REST API call?

When a client creates a REST API call, a representation of the state of the requested resource will be transferred from the server.

Example:
A developer calls the LinkedIn API to fetch a specific profile on LinkedIn, the API will then return the state of the requested profile, that could for example be the first and last name of the user, the job title, the company etc...

2. SCOM REST API Reference

The full REST API reference for System Center Operations Manager (SCOM) can be found on the official Microsoft documentation page over here:
https://docs.microsoft.com/en-us/rest/api/operationsmanager

Note: Operations Manager 2019 UR1 supports Cross-Site Request Forgery (CSRF) tokens to prevent CSRF attacks. If you are using Operations Manager 2019 UR1, you must initialize the CSRF token. HTML scripts do not work if the CSRF tokens are not initialized.

More information:
https://docs.microsoft.com/en-us/rest/operationsmanager/#initialize-the-csrf-token

3. SCOM REST API Examples

3.1 Alerts

To retrieve alerts with the SCOM REST API, we will need to enter a criteria, this could be the alert severity, resolution state, alert name or something else.

I will provide a few different examples on how to fetch SCOM alerts by using different criteria.

3.1.1 Retrieve all new alerts

The following PowerShell script will call the SCOM REST API and retrieve all new alerts that are in a critical state.

The script:

# Set SCOM Header and the Body
$SCOMHeaders = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$SCOMHeaders.Add('Content-Type', 'application/json; charset=utf-8')
$BodyRaw = "Windows"
$Bytes = [System.Text.Encoding]::UTF8.GetBytes($BodyRaw)
$EncodedText = [Convert]::ToBase64String($Bytes)
$JSONBody = $EncodedText | ConvertTo-Json

# The SCOM REST API authentication URL
$URIBase = 'http://<Your SCOM MS>/OperationsManager/authenticate'

# Initiate the Cross-Site Request Forgery (CSRF) token, this is to prevent CSRF attacks
$CSRFtoken = $WebSession.Cookies.GetCookies($URIBase) | ? { $_.Name -eq 'SCOM-CSRF-TOKEN' }
$SCOMHeaders.Add('SCOM-CSRF-TOKEN', [System.Web.HttpUtility]::UrlDecode($CSRFtoken.Value))

# Authentication
$Authentication = Invoke-RestMethod -Method Post -Uri $URIBase -Headers $SCOMHeaders -body $JSONBody -UseDefaultCredentials -SessionVariable WebSession

# The query which contains the criteria for our alerts
$Query = @(@{ "classId" = ""

# Get all alerts
"displayColumns" = "severity", "monitoringobjectdisplayname", "name", "age", "repeatcount"})

# Convert our query to JSON format
$JSONQuery = $Query | ConvertTo-Json

$Response = Invoke-RestMethod -Uri 'http://<Your SCOM MS>/OperationsManager/data/alert' -Method Post -Body $JSONQuery -ContentType "application/json" -WebSession $WebSession

# Print out the alert results
$Alerts = $Response.Rows
$Alerts
Example Script

Example Script

Example Output

Example Output

3.1.2 Retrieve alerts with a specific severity and resolution state

The following PowerShell script will call the SCOM REST API and alerts that have a specific severity and resolution state.

The script:

# Set the Header and the Body
$SCOMHeaders = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$SCOMHeaders.Add('Content-Type', 'application/json; charset=utf-8')
$BodyRaw = "Windows"
$Bytes = [System.Text.Encoding]::UTF8.GetBytes($BodyRaw)
$EncodedText = [Convert]::ToBase64String($Bytes)
$JSONBody = $EncodedText | ConvertTo-Json

# The SCOM REST API authentication URL
$URIBase = 'http://<Your SCOM MS>/OperationsManager/authenticate'

# Initiate the Cross-Site Request Forgery (CSRF) token, this is to prevent CSRF attacks
$CSRFtoken = $WebSession.Cookies.GetCookies($UriBase) | ? { $_.Name -eq 'SCOM-CSRF-TOKEN' }
$SCOMHeaders.Add('SCOM-CSRF-TOKEN', [System.Web.HttpUtility]::UrlDecode($CSRFtoken.Value))

# Authentication
$Authentication = Invoke-RestMethod -Method Post -Uri $uriBase -Headers $SCOMHeaders -body $JSONBody -UseDefaultCredentials -SessionVariable WebSession

# The query which contains the criteria for our alerts
$Query = @(@{ "classId" = ""

# Get all alerts with severity '2' (critical) and resolutionstate '0' (new)
"criteria" = "((Severity = '2') AND (ResolutionState = '0'))"
"displayColumns" ="severity","monitoringobjectdisplayname","name","age","repeatcount" })

# Convert our query to JSON format
$JSONQuery = $Query | ConvertTo-Json

$Response = Invoke-RestMethod -Uri 'http://<Your SCOM MS>/OperationsManager/data/alert' -Method Post -Body $JSONQuery -WebSession $WebSession

# Print out the alert results
$Alerts = $Response.Rows
$Alerts
Example Script

Example Script

Example Output

Example Output

3.1.3 Retrieve all alerts with a specific alert name

The following PowerShell script will call the SCOM REST API and retrieve all alerts with a specific alert name.

The script:

# Set the Header and the Body
$SCOMHeaders = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$SCOMHeaders.Add('Content-Type', 'application/json; charset=utf-8')
$BodyRaw = "Windows"
$Bytes = [System.Text.Encoding]::UTF8.GetBytes($BodyRaw)
$EncodedText = [Convert]::ToBase64String($Bytes)
$JSONBody = $EncodedText | ConvertTo-Json

# The SCOM REST API authentication URL
$URIBase = 'http://<Your SCOM MS>/OperationsManager/authenticate'

# Initiate the Cross-Site Request Forgery (CSRF) token, this is to prevent CSRF attacks
$CSRFtoken = $WebSession.Cookies.GetCookies($UriBase) | ? { $_.Name -eq 'SCOM-CSRF-TOKEN' }
$SCOMHeaders.Add('SCOM-CSRF-TOKEN', [System.Web.HttpUtility]::UrlDecode($CSRFtoken.Value))

# Authentication
$Authentication = Invoke-RestMethod -Method Post -Uri $uriBase -Headers $SCOMHeaders -body $JSONBody -UseDefaultCredentials -SessionVariable WebSession

# The query which contains the criteria for our alerts
$Query = @(@{ "classId" = ""

# Get all alerts with a specific name
"criteria"          = "((Name = 'Failed to Connect to Computer'))"
"displayColumns" = "severity", "monitoringobjectdisplayname", "name", "age", "repeatcount"})

# Convert our query to JSON format
$JSONQuery = $Query | ConvertTo-Json

$Response = Invoke-RestMethod -Uri 'http://<Your SCOM MS>/OperationsManager/data/alert' -Method Post -Body $JSONQuery -WebSession $WebSession

# Print out the alert results
$Alerts = $Response.Rows
$Alerts
Example Script

Example Script

Example Output

Example Output

3.2 Rules

To retrieve rules with the SCOM REST API, a certain criteria must be given, normally we would look for a rule by its name, so we will use the DisplayName criteria.

3.2.1 Retrieve a rule with a specific name

The following PowerShell script will call the SCOM REST API and retrieve a specific rule by its display name:

The script:


# Set the Header and the Body$SCOMHeaders = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$SCOMHeaders.Add('Content-Type', 'application/json; charset=utf-8')
$BodyRaw = "Windows"
$Bytes = [System.Text.Encoding]::UTF8.GetBytes($bodyraw)
$EncodedText = [Convert]::ToBase64String($Bytes)
$JSONBody = $EncodedText | ConvertTo-Json

# The SCOM REST API authentication URL
$UriBase = 'http://<Your SCOM MS>/OperationsManager/authenticate'

# Initiate the Cross-Site Request Forgery (CSRF) token, this is to prevent CSRF attacks
$CSRFtoken = $WebSession.Cookies.GetCookies($UriBase) | ? { $_.Name -eq 'SCOM-CSRF-TOKEN' }
$SCOMHeaders.Add('SCOM-CSRF-TOKEN', [System.Web.HttpUtility]::UrlDecode($CSRFtoken.Value))

# Authentication
$Authentication = Invoke-RestMethod -Method Post -Uri $UriBase -Headers $SCOMHeaders -Body $JSONBody -UseDefaultCredentials -SessionVariable WebSession

# Criteria: Enter the displayname of the SCOM rule
$Criteria = "DisplayName LIKE 'Processor % Processor Time Total Windows Server 2016 and 1709+'"

# Convert our criteria to JSON format
$JSONBody = $Criteria | ConvertTo-Json

$Response = Invoke-WebRequest -Uri 'http://<Your SCOM MS>/OperationsManager/data/rules' -Method Post -Body $JSONBody -WebSession $WebSession

# Convert our response from JSON format to a custom object or hash table
$Rule = ConvertFrom-Json -InputObject $Response.Content

# Print out the rule result
$Rule.rows
Example Script

Example Script

Example Output

Example Output

3.3 Monitors

To retrieve monitors with the SCOM REST API, a certain criteria must be given, normally we would look for a rule by its name, so we will use the "DisplayName" criteria.

3.3.1 Retrieve a monitor with a specific name

The following PowerShell script will call the SCOM REST API and retrieve a specific monitor by its display name:

The script:

# Set the Header and the Body
$SCOMHeaders = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$SCOMHeaders.Add('Content-Type','application/json; charset=utf-8')
$BodyRaw = "Windows"
$Bytes = [System.Text.Encoding]::UTF8.GetBytes($bodyraw)
$EncodedText =[Convert]::ToBase64String($Bytes)
$JSONBody = $EncodedText | ConvertTo-Json

# The SCOM REST API authentication URL
$UriBase = 'http://<Your SCOM MS>/OperationsManager/authenticate'

# Initiate the Cross-Site Request Forgery (CSRF) token, this is to prevent CSRF attacks
$CSRFtoken = $WebSession.Cookies.GetCookies($UriBase) | ? { $_.Name -eq 'SCOM-CSRF-TOKEN' }
$SCOMHeaders.Add('SCOM-CSRF-TOKEN', [System.Web.HttpUtility]::UrlDecode($CSRFtoken.Value))

# Authentication
$Authentication = Invoke-RestMethod -Method Post -Uri $UriBase -Headers $SCOMHeaders -Body $JSONBody -UseDefaultCredentials -SessionVariable WebSession

# Criteria: Enter the displayname of the SCOM monitor
$Criteria = "DisplayName LIKE 'Logical Disk Free Space Monitor'"

# Convert our criteria to JSON format
$JSONBody = $Criteria | ConvertTo-Json

$Response = Invoke-WebRequest -Uri 'http://<Your SCOM MS>/OperationsManager/data/class/monitors' -Method Post -Body $JSONBody -WebSession $WebSession
  
# Convert our response from JSON format to a custom object or hash table
$Monitors = ConvertFrom-Json -InputObject $Response.Content

# Print out the monitor results
$Monitors.rows
Example Script

Example Script

Example Output

Example Output

3.3.2 Retrieve a monitor by name and wildcard

The following PowerShell script will call the SCOM REST API and retrieve a specific monitor by its display name and a wildcard, this can be useful if you don't really know the full display name of the monitor, or if you want to get all monitors with for example the name "SQL Server".

The script:

# Set the Header and the Body
$SCOMHeaders = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$SCOMHeaders.Add('Content-Type','application/json; charset=utf-8')
$BodyRaw = "Windows"$Bytes = [System.Text.Encoding]::UTF8.GetBytes($bodyraw)
$EncodedText =[Convert]::ToBase64String($Bytes)
$JSONBody = $EncodedText | ConvertTo-Json

# The SCOM REST API authentication URL
$UriBase = 'http://<Your SCOM MS>/OperationsManager/authenticate'

# Initiate the Cross-Site Request Forgery (CSRF) token, this is to prevent CSRF attacks
$CSRFtoken = $WebSession.Cookies.GetCookies($UriBase) | ? { $_.Name -eq 'SCOM-CSRF-TOKEN' }
$SCOMHeaders.Add('SCOM-CSRF-TOKEN', [System.Web.HttpUtility]::UrlDecode($CSRFtoken.Value))

# Authentication
$Authentication = Invoke-RestMethod -Method Post -Uri $UriBase -Headers $SCOMHeaders -Body $JSONBody -UseDefaultCredentials -SessionVariable WebSession

# Criteria: Enter the displayname of the SCOM monitor
$Criteria = "DisplayName LIKE '%SQL Server%'"

# Convert our criteria to JSON format
$JSONBody = $Criteria | ConvertTo-Json

$Response = Invoke-WebRequest -Uri 'http://<Your SCOM MS>/OperationsManager/data/class/monitors' -Method Post -Body $JSONBody -WebSession $WebSession

# Convert our response from JSON format to a custom object or hash table
$Monitors = ConvertFrom-Json -InputObject $Response.Content

# Print out the monitor results
$Monitors.rows
Example Script

Example Script

Example Output

Example Output

3.4 Groups

To retrieve groups with the SCOM REST API, we must provide a criteria, normally we would look for a group by its name, so we will use the "DisplayName" criteria.

3.4.1 Retrieve a group with a specific name

The following PowerShell script will call the SCOM REST API and retrieve a specific group by its display name:

The script:

# Set the Header and the Body
$SCOMHeaders = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$SCOMHeaders.Add('Content-Type','application/json; charset=utf-8')
$BodyRaw = "Windows"
$Bytes = [System.Text.Encoding]::UTF8.GetBytes($bodyraw)
$EncodedText =[Convert]::ToBase64String($Bytes)
$JSONBody = $EncodedText | ConvertTo-Json

# The SCOM REST API authentication URL
$UriBase = 'http://<Your SCOM MS>/OperationsManager/authenticate'

# Initiate the Cross-Site Request Forgery (CSRF) token, this is to prevent CSRF attacks
$CSRFtoken = $WebSession.Cookies.GetCookies($UriBase) | ? { $_.Name -eq 'SCOM-CSRF-TOKEN' }
$SCOMHeaders.Add('SCOM-CSRF-TOKEN', [System.Web.HttpUtility]::UrlDecode($CSRFtoken.Value))

# Authentication
$Authentication = Invoke-RestMethod -Method Post -Uri $UriBase -Headers $SCOMHeaders -Body $JSONBody -UseDefaultCredentials -SessionVariable WebSession

# Criteria: Enter the display name of the SCOM group
$Criteria = "DisplayName LIKE 'All Windows Computers'"

# Convert our criteria to JSON format
$JSONBody = $Criteria | ConvertTo-Json

$Response = Invoke-WebRequest -Uri 'http://<Your SCOM MS>/OperationsManager/data/scomGroups' -Method Post -Body $JSONBody -WebSession $WebSession

# Convert our response from JSON format to a custom object or hash table
$Groups = ConvertFrom-Json -InputObject $Response.Content

# Print out the group results
$Groups.scopeDatas
Example Script

Example Script

Example Output

Example Output

3.4.2 Retrieve a group by name and wildcard

The following PowerShell script will call the SCOM REST API and retrieve a group by its display name and wildcard, this is useful if you don't know the group name, or if you only know part of the name.

The script:

# Set the Header and the Body
$SCOMHeaders = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$SCOMHeaders.Add('Content-Type','application/json; charset=utf-8')
$BodyRaw = "Windows"$Bytes = [System.Text.Encoding]::UTF8.GetBytes($bodyraw)
$EncodedText =[Convert]::ToBase64String($Bytes)
$JSONBody = $EncodedText | ConvertTo-Json

# The SCOM REST API authentication URL
$UriBase = 'http://<Your SCOM MS>/OperationsManager/authenticate'

# Initiate the Cross-Site Request Forgery (CSRF) token, this is to prevent CSRF attacks
$CSRFtoken = $WebSession.Cookies.GetCookies($UriBase) | ? { $_.Name -eq 'SCOM-CSRF-TOKEN' }
$SCOMHeaders.Add('SCOM-CSRF-TOKEN', [System.Web.HttpUtility]::UrlDecode($CSRFtoken.Value))

# Authentication
$Authentication = Invoke-RestMethod -Method Post -Uri $UriBase -Headers $SCOMHeaders -Body $JSONBody -UseDefaultCredentials -SessionVariable WebSession

# Criteria: Enter the display name of the SCOM group
$Criteria = "DisplayName LIKE '%Contoso%'"

# Convert our criteria to JSON format
$JSONBody = $Criteria | ConvertTo-Json

$Response = Invoke-WebRequest -Uri 'http://<Your SCOM MS>/OperationsManager/data/scomGroups' -Method Post -Body $JSONBody -WebSession $WebSession

# Convert our response from JSON format to a custom object or hash table
$Groups = ConvertFrom-Json -InputObject $Response.Content

# Print out the group results
$Groups.scopeDatas
Example Script

Example Script

Example Output

Example Output

3.5 Classes

To retrieve a SCOM object with the SCOM REST API, we must provide a criteria, like with all the rest we would normally search a SCOM class by its name, so we will use the "DisplayName" criteria.

3.5.1 Retrieve a class with a specific name

The following PowerShell script will call the SCOM REST API and retrieve a specific class by its display name:

The script:

# Set the Header and the Body
$SCOMHeaders = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$SCOMHeaders.Add('Content-Type','application/json; charset=utf-8')
$BodyRaw = "Windows"
$Bytes = [System.Text.Encoding]::UTF8.GetBytes($bodyraw)
$EncodedText =[Convert]::ToBase64String($Bytes)
$JSONBody = $EncodedText | ConvertTo-Json

# The SCOM REST API authentication URL
$UriBase = 'http://<Your SCOM MS>/OperationsManager/authenticate'

# Initiate the Cross-Site Request Forgery (CSRF) token, this is to prevent CSRF attacks
$CSRFtoken = $WebSession.Cookies.GetCookies($UriBase) | ? { $_.Name -eq 'SCOM-CSRF-TOKEN' }
$SCOMHeaders.Add('SCOM-CSRF-TOKEN', [System.Web.HttpUtility]::UrlDecode($CSRFtoken.Value))

# Authentication
$Authentication = Invoke-RestMethod -Method Post -Uri $UriBase -Headers $SCOMHeaders -Body $JSONBody -UseDefaultCredentials -SessionVariable WebSession

# Criteria: Enter the displayname of the SCOM class
$Criteria = "DisplayName LIKE 'Windows Server Computer Group'"

# Convert our criteria to JSON format
$JSONBody = $Criteria | ConvertTo-Json

$Response = Invoke-WebRequest -Uri 'http://<Your SCOM MS>/OperationsManager/data/scomClasses' -Method Post -Body $JSONBody -WebSession $WebSession

# Convert our response from JSON format to a custom object or hash table
$Class = ConvertFrom-Json -InputObject $Response.Content

# Print out the class results
$Class.scopeDatas
Example Script

Example Script

Example Output

Example Output

3.6 Objects

As with all the previous SCOM REST API calls, we must provide a criteria to retrieve a SCOM object, we will continue using the the "DisplayName" criteria, as this is the easiest to find objects.

3.6.1 Retrieve all SCOM agents

The following PowerShell script will call the SCOM REST API and retrieve a specific object by its display name:

The script:

# Set the Header and the Body
$SCOMHeaders = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$SCOMHeaders.Add('Content-Type’,’application/json; charset=utf-8')
$BodyRaw = "Windows"
$Bytes = [System.Text.Encoding]::UTF8.GetBytes($bodyraw)
$EncodedText =[Convert]::ToBase64String($Bytes)
$JSONBody = $EncodedText | ConvertTo-Json

# The SCOM REST API authentication URL
$UriBase = 'http://<Your SCOM MS>/OperationsManager/authenticate'

# Initiate the Cross-Site Request Forgery (CSRF) token, this is to prevent CSRF attacks
$CSRFtoken = $WebSession.Cookies.GetCookies($UriBase) | ? { $_.Name -eq 'SCOM-CSRF-TOKEN' }
$SCOMHeaders.Add('SCOM-CSRF-TOKEN', [System.Web.HttpUtility]::UrlDecode($CSRFtoken.Value))

# Authentication
$Authentication = Invoke-RestMethod -Method Post -Uri $UriBase -Headers $SCOMHeaders -Body $JSONBody -UseDefaultCredentials -SessionVariable WebSession

# Criteria: Enter the displayname of the SCOM object
$Criteria = "DisplayName LIKE '%Microsoft Monitoring Agent%'"

# Convert our criteria to JSON format$JSONBody = 
$Criteria | ConvertTo-Json

$Response = Invoke-WebRequest -Uri 'http://<Your SCOM MS>/OperationsManager/data/scomObjects' -Method Post -Body $JSONBody -WebSession $WebSession

# Convert our response from JSON format to a custom object or hash table
$Object = ConvertFrom-Json -InputObject $Response.Content

# Print out the object results
$Object.scopeDatas
Example Script

Example Script

Example Output

Example Output

3.6.2 Retrieve all the installed SCOM consoles

The following PowerShell script will call the SCOM REST API and retrieve all the Operations Consoles installed on any monitored computer:

The script:

# Set the Header and the Body$SCOMHeaders = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$SCOMHeaders.Add('Content-Type','application/json; charset=utf-8')
$BodyRaw = "Windows"
$Bytes = [System.Text.Encoding]::UTF8.GetBytes($bodyraw)
$EncodedText =[Convert]::ToBase64String($Bytes)
$JSONBody = $EncodedText | ConvertTo-Json

# The SCOM REST API authentication URL
$UriBase = 'http://<Your SCOM MS>/OperationsManager/authenticate'

# Initiate the Cross-Site Request Forgery (CSRF) token, this is to prevent CSRF attacks
$CSRFtoken = $WebSession.Cookies.GetCookies($UriBase) | ? { $_.Name -eq 'SCOM-CSRF-TOKEN' }
$SCOMHeaders.Add('SCOM-CSRF-TOKEN', [System.Web.HttpUtility]::UrlDecode($CSRFtoken.Value))

# Authentication
$Authentication = Invoke-RestMethod -Method Post -Uri $UriBase -Headers $SCOMHeaders -Body $JSONBody -UseDefaultCredentials -SessionVariable WebSession

# Criteria: Enter the displayname of the SCOM object
$Criteria = "DisplayName LIKE '%System Center Operations Manager Console%'"

# Convert our criteria to JSON format
$JSONBody = $Criteria | ConvertTo-Json

$Response = Invoke-WebRequest -Uri 'http://<Your SCOM MS>/OperationsManager/data/scomObjects' -Method Post -Body $JSONBody -WebSession $WebSession

# Convert our response from JSON format to a custom object or hash table
$Object = ConvertFrom-Json -InputObject $Response.Content

# Print out the object results
$Object.scopeDatas
Example Script

Example Script

Example Output

Example Output

And this is to compare the above results with the amount of consoles shown in the Operations Console:

5739d-scom_consoles.png

3.7 States

We can also retrieve states of different objects with the SCOM REST API, once again we must provide a criteria to retrieve the state of our SCOM object.

3.7.1 Retrieve the health state of a monitored computer

The following PowerShell script will call the SCOM REST API and retrieve the health state of a monitored computer in SCOM:

The script:

# Set the Header and the Body
$SCOMHeaders = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$SCOMHeaders.Add('Content-Type', 'application/json; charset=utf-8')
$BodyRaw = "Windows"$Bytes = [System.Text.Encoding]::UTF8.GetBytes($BodyRaw)
$EncodedText = [Convert]::ToBase64String($Bytes)
$JSONBody = $EncodedText | ConvertTo-Json

# The SCOM REST API authentication URL
$URIBase = 'http://<Your SCOM MS>/OperationsManager/authenticate'

# Initiate the Cross-Site Request Forgery (CSRF) token, this is to prevent CSRF attacks
$CSRFtoken = $WebSession.Cookies.GetCookies($UriBase) | ? { $_.Name -eq 'SCOM-CSRF-TOKEN' }
$SCOMHeaders.Add('SCOM-CSRF-TOKEN', [System.Web.HttpUtility]::UrlDecode($CSRFtoken.Value))
  
# Authentication
$Authentication = Invoke-RestMethod -Method Post -Uri $URIBase -Headers $SCOMHeaders -body $JSONBody -UseDefaultCredentials -SessionVariable WebSession

# The query which contains the criteria for our alerts$Query = @(@{ "classId" = ""
  
    # Criteria: Enter the name of the monitored computer (do not use the FQDN)
    "criteria" = "DisplayName = 'Operations Manager Management Group'"
    "displayColumns"    = "displayname", "healthstate", "name", "path"})

# Convert our query to JSON format
$JSONQuery = $Query | ConvertTo-Json

$Response = Invoke-RestMethod -Uri 'http://<Your SCOM MS>/OperationsManager/data/state' -Method Post -Body $JSONQuery -ContentType "application/json" -WebSession $WebSession

# Print out the state results
$State = $Response.rows
$State
Example Script

Example Script

Example Output

Example Output

3.8 Retrieve Unsealed Management Packs

To retrieve a list of unsealed management packs, we will need to use a "GET" request method instead of a "POST" method.

The following PowerShell script will call the SCOM REST API and retrieve all unsealed management packs in the SCOM environment:

The script:

# Set the Header and the Body
$SCOMHeaders = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$SCOMHeaders.Add('Content-Type','application/json; charset=utf-8')
$BodyRaw = "Windows"
$Bytes = [System.Text.Encoding]::UTF8.GetBytes($bodyraw)
$EncodedText =[Convert]::ToBase64String($Bytes)
$JSONBody = $EncodedText | ConvertTo-Json

# The SCOM REST API authentication URL
$UriBase = 'http://<Your SCOM MS>/OperationsManager/authenticate'

# Initiate the Cross-Site Request Forgery (CSRF) token, this is to prevent CSRF attacks
$CSRFtoken = $WebSession.Cookies.GetCookies($UriBase) | ? { $_.Name -eq 'SCOM-CSRF-TOKEN' }
$SCOMHeaders.Add('SCOM-CSRF-TOKEN', [System.Web.HttpUtility]::UrlDecode($CSRFtoken.Value))

# Authentication
$Authentication = Invoke-RestMethod -Method Post -Uri $UriBase -Headers $SCOMHeaders -Body $JSONBody -UseDefaultCredentials -SessionVariable WebSession

$Response = Invoke-WebRequest -Uri 'http://<Your SCOM MS>/OperationsManager/data/UnsealedManagementPacks' -Method Get -WebSession $WebSession

# Convert our response from JSON format to a custom object or hash table
$UnsealedMPs = ConvertFrom-Json -InputObject $Response.Content

# Print out a list of all unsealed management packs
$UnsealedMPs
Example Script

Example Script

Example Output

Example Output

4. Conclusion

There is a lot of information that can be retrieved with REST API, however if you've never worked with REST API before like me, it can be very confusing on where to even start. Microsoft does help in this matter, but for them to know the customer's issues, they first need to know about it, so if you are struggling with SCOM's REST API, make sure to send feedback about it over at the SCOM UserVoice page.

I hope that my examples gives you a start on how to use SCOM's REST API, they are not complex and I made them as simple as I could, I might add more later on when I have more time to dig into this.

Happy SCOMing! 😉

Leon Laude
Previous

SCOMathon 2020 Roundup
Next

Monitoring REST APIs with PowerShell and SCOM