This is the second in a series of articles giving extended example of how to use the RestAPI. This article will demonstrate how to generate a report equivalent to the Version 3 "OutputApplications" view using PowerShell. For a shorter example that returns a simpler dataset, you can see the article Use RestAPI and PHP to generate a list of Applications.
Fields in the original report
| Field Name | V3 Description | V4 Comment |
|---|---|---|
| Hostname | The hostname of the device the application is running on | Get this from the Applications endpoint. Possibly a list of devices. Might need to follow the Applications/Application_ID enpoint for some clusters. |
| FQDN | Fully Qualified Domain Name of the device | Get this from the Applications endpoint. Possibly a list of devices. Might need to follow the Applications/Application_ID enpoint for some clusters. |
| SoftwareName | SoftwareName Enterprise application name | Get this from the Applications endpoint. |
| SoftwareVersion | Version | Get this from the Applications endpoint. |
| SoftwareVendor | Software vendor name | Get this from the Applications endpoint. |
| SoftwareEdition | Software Edition (Enterprise, Web, etc) | Get this from the Applications endpoint where applicable. |
| InstanceIdentifier | Unique application name | For database applications, this is in the "name" field of the Applications endpoint. |
| ClusterInformation | The cluster that the physical machine is part of. | See clusters and/or parent_cluster in the Applications endpoint. IN V3 this contained the cluster name and list of nodes separated by ";" for some cluster types, but not all |
| UserCount | Number of users (where applicable) | Get this from the Applications/Application_ID endpoint |
| LastScanDate | Timestamp of last scan | Get this from the Applications endpoint. |
| Location | Location of the application (user defined, inherited from the device location) | Get this from the Applications endpoint device section for non-clustered applications. |
| Language | SQL Server instance language (SQL Server only) | Not exposed via V4 RestAPI |
| ApplicationID | Unique Identifier for the application | Get this from the Applications endpoint. |
| DeviceID | Unique Identifier for the device. Can be used to map to OutputDevices | Get this from the Applications endpoint device section for non-clustered applications. Possibly a list of devices. Might need to follow the Applications/Application_ID enpoint for some clusters. |
| DNSHostname | The hostname for the device as reported by DNS | Get this from the Applications endpoint device section for non-clustered applications. Possibly a list of devices. Might need to follow the Applications/Application_ID enpoint for some clusters. |
| DNSFQDN | The FQDN for the device as reported from DNS | Get this from the Applications endpoint device section for non-clustered applications. Possibly a list of devices. Might need to follow the Applications/Application_ID enpoint for some clusters. |
| Evidence | This column not available in V4 | Not exposed via V4 RestAPI |
Connect to the RestAPI
The RestAPI uses HTTP basic authentication rather than domain credentials. To write a script that extracts data from the RestAPI you will need to know the login name and password for an iQSonar user who has the "access Rest API" permission enabled. By default the admin user always has this permission. These variables will need to be configured for your site:
$user = "admin" $pass = "password" $sonar = "iQSonar Host" $secpass = ConvertTo-SecureString $pass -AsPlainText -Force $credential = New-Object System.Management.Automation.PSCredential($user,$secpass)
The first step is to determine exactly how many applications we're going to be collecting data for. This information is returned in the header of the RestAPI return value. By default a call to the devices endpoint will return a batch of 200 devices, and the user is expected to page through the list of available devices by making successive calls to this endpoint using an offset parameter to specify how many devices have already been seen. The fetch_size parameter is used to determine how many devices are returned per batch. The fastest way to determine the total number of available applications is to explicitly request the first device only. Since we want data from the headers of the result, we use the Invoke-WebRequest PowerShell cmdlet to get this information.
$uri = -join ("http://", $sonar, "/api/v1/applications/?offset=1&fetch_size=1")
$r = Invoke-WebRequest $uri -Credential $credential
# $r.headers has HTML headers, $r.content has text content
$appCount = $r.headers.'X-fetch-count'