FAQ, GUIDE, REST API, SCOM, System Center

Quick Start – SCOM REST API

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

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 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
"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:REST-API-Alerts_All

Example output:
SCOM_REST_Alert3_result

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:REST-API-Alerts_ResoState_and_Severity

Example output:SCOM_REST_Alert1_result

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:REST-API-Alerts_AlertName

Example output:
SCOM_REST_Alert2_result

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:REST-API-Rule

Example output:SCOM_REST_Rule1_result

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:
REST-API-Monitor-1


Example output:
SCOM_REST_Monitor1_result

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:REST-API-Monitor-2

Example output:SCOM_REST_API_Monitor_2_result

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:
REST-API-Group-1
Example output:
SCOM_REST_API_Groups_1_result

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:
REST-API-Group-2

 

Example output:SCOM_REST_API_Groups_2_result

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:
REST-API-Class
Example output:
SCOM_REST_API_Classes_1_results

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:
REST-API-Agents
Example output:
SCOM_REST_API_Objects_1_results

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:
REST-API-Consoles
Example output:
SCOM_REST_API_Objects_2_results
And this is to compare the above results with the amount of consoles shown in the Operations Console:
SCOM_consoles

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:
REST-API-State
Example output:
SCOM_REST_API_States_1_results

3.6 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:
REST-API-UnsealedMPs
Example output:
SCOM_REST_API_UnsealedMPs_1_results

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 SCOMming! 😉

 4,716 total views,  18 views today

10 thoughts on “Quick Start – SCOM REST API”

  1. Your examples all return the following error:
    Invoke-RestMethod : {“errorMessage”:”The required anti-forgery cookie \”__RequestVerificationToken_L09wZXJhdGlvbnNNYW5hZ2Vy0\” is not present.”,”errorTrace”:” at
    System.Web.Helpers.AntiXsrf.TokenValidator.ValidateTokens(HttpContextBase httpContext, IIdentity identity, AntiForgeryToken sessionToken, AntiForgeryToken fieldToken)\r\n at
    System.Web.Helpers.AntiXsrf.AntiForgeryWorker.Validate(HttpContextBase httpContext, String cookieToken, String formToken)\r\n at
    Microsoft.EnterpriseManagement.OMDataService.Filters.ValidateAntiForgeryTokenAttribute.OnActionExecuting(HttpActionContext actionContext)\r\n at
    System.Web.Http.Filters.ActionFilterAttribute.OnActionExecutingAsync(HttpActionContext actionContext, CancellationToken cancellationToken)\r\n— End of stack trace from previous location where
    exception was thrown —\r\n at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task
    task)\r\n at System.Web.Http.Filters.ActionFilterAttribute.d__0.MoveNext()\r\n— End of stack trace from previous location where exception was thrown —\r\n at
    System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n at
    System.Web.Http.Filters.ActionFilterAttribute.d__5.MoveNext()\r\n— End of stack trace from previous location where exception was thrown —\r\n at
    System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n at System.Web.Http.Filters.ActionFilterAttribute.d__5.MoveNext()\r\n— End of stack trace from previous location where exception
    was thrown —\r\n at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n at
    System.Web.Http.Filters.ActionFilterAttribute.d__0.MoveNext()\r\n— End of stack trace from previous location where exception was thrown —\r\n at
    System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n at
    System.Web.Http.Controllers.ActionFilterResult.d__2.MoveNext()\r\n— End of stack trace from previous location where exception was thrown —\r\n at
    System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n at
    System.Web.Http.Controllers.ExceptionFilterResult.d__0.MoveNext()”}
    At line:30 char:13

    What am I doing wrong?

    1. Hi,

      If you’re using SCOM 2019 UR 1 you must initialize the CSRF token, HTML scripts do not work if the CSRF tokens are not initialized. UR1 added support for cross-site request forgery (CSRF) tokens to prevent CSRF attacks.
      https://docs.microsoft.com/en-us/rest/operationsmanager/#initialize-the-csrf-token

      What’s interesting is that for me it worked although I was running this on SCOM 2019 UR1, anyhow I guess I will have to edit my blog post 🙂

      Try adding the following two lines before the “$Response” line:

      $CSRFtoken = $WebSession.Cookies.GetCookies($UriBase) | ? { $_.Name -eq ‘SCOM-CSRF-TOKEN’ }
      $SCOMHeaders.Add(‘SCOM-CSRF-TOKEN’, [System.Web.HttpUtility]::UrlDecode($CSRFtoken.Value))

      Best regards,
      Leon

      1. That did it, sort of. Instead of placing those two lines prior to the $Response, they needed to go just prior to the $Authentication line.

  2. Nice post !!! Very good collection for designing SCOM 2019 dashboards. Thanks for sharing.

    I am just wondering how to work with Powershell:
    POST http:///OperationsManager/data/powershell

    https://docs.microsoft.com/en-us/rest/api/operationsmanager/data/retrieve%20powershell%20output

    I have tried this in two seperate SCOM 2019 Management Groups and getting the same error as follows:

    No HTTP resource was found that matches the request URI ‘http://server.company.com/OperationsManager/data/powershell’.

    1. Hi Robert,

      I am currently on vacation, I will take a look at this once I get back 🙂

      Best regards,
      Leon

    1. Hi,

      I’m not that familiar with JavaScript so I cannot say if it works or not, easiest is to test it yourself 🙂

      Best regards,
      Leon

  3. Hi Leon,

    Thank you for your post! This was very helpful given the scant amount of information there is around the web for this. I wanted to note a few tweaks that were required for me to get this to work.

    I believe the following block of code needs to appear after the Authentication takes place.

    # 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))

    The authentication is when the Websession is initialized and the $WebSession variable doesn’t become available until after this happens. Then the CSRFtoken can then be abscracted and added to the headers.

    I had to add the -Headers $SCOMHeaders parameter to the second Invoke-RestMethod because it is looking for the CSRFtoken to be present which we added to the $SCOMHeaders earlier.

    I received a message that “criteria” is required in all queries so the first query did not work for me. The second query is missing a single quote at the beginning of ‘Failed to Connect…’

    # 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”
    })

    Thanks again for your post!

    Brian

    1. Hi Brian,

      Thanks for the corrections of the typos, the code has changed when I pasted it in my blog post.

      For the CSRF and Authentication I’ve been playing around with these for quite a while, and for me in my labs this was the way it worked without any issues.
      My tests consisted of trying with and without the Update Rollup which requires CSRF, but based on some other feedback it seems to work different which I’m not really sure why.

      Thanks for the comments though!

      Best regards,
      Leon

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.