This article details how to generate report using the RestAPI which will mirror as closely as possible the "OutputDevices" report which was available in V3 of iQSonar
...
Field | V3 Comment | RestAPI Comment |
---|---|---|
Hostname | Hostname of the device | Get this from the /devices RestAPI endpoint |
FQDN | Fully QUalified Domain Name of the device | Get this from the /devices/{Device_ID} RestAPI endpoint |
OS | OS description and service pack | Get this from the /devices/{Device_ID} RestAPI endpoint |
OS Install Date | OS description and service pack | Get this from the /devices/{Device_ID} RestAPI endpoint May not always be available |
Location | Location of the device | In V4 this represents the target configuration set used to define the device. Get this from the /devices RestAPI endpoint |
Serial Number | The serial number of the device | Get this from the /devices RestAPI endpoint |
PhysicalCPUCount | Number of physical CPUs or sockets in the Physical Device (which may differ from the Virtual or Logical host when a device is a virtual machine or partition) | IF the device is a physical device, this information is derived from the /devices/{Device_ID} RestAPI endpoint Where the virtualisation host is not scanned, then this field and all the other information about the physical host will not be able to be populated. |
PhysicalCoreCount | Sum of cores across all CPUs in the Physical Device (which may differ from the Virtual or Logical host when a device is a virtual machine or partition) | Get this from the /devices/{Device_ID} RestAPI endpoint; May not always be available |
PhysicalCoresPerCPU | Physical core count divided by the physical CPU count | Get this from the /devices/{Device_ID} RestAPI endpoint; May not always be available |
PhysicalCPUManufacturer | Manufacturer of the CPU on the Physical Device | Get this from the /devices/{Device_ID} RestAPI endpoint; May not always be available |
PhysicalCPUModel | Model of the CPU on the Physical Device | Get this from the /devices/{Device_ID} RestAPI endpoint; May not always be available |
PhysicalCPUSpeed | Speed of the CPU on the Physical Device | Get this from the /devices/{Device_ID} RestAPI endpoint; May not always be available |
PhysicalRAM | Total amount of RAM on the Physical Device | Get this from the /devices/{Device_ID} RestAPI endpoint; May not always be available |
VirtualCPUCount | Number of Virtual CPUs perceived by the device (only populated when the device is Virtual or Logical) | Get this from the /devices/{Device_ID} RestAPI endpoint; Only available if device is virtual or logical |
VirtualCoreCount | Sum of Cores perceived by the device (only populated when the device is Virtual or Logical) | Get this from the /devices/{Device_ID} RestAPI endpoint; Only available if device is virtual or logical |
VirtualRAM | Amount of perceived RAM by the device (only populated when the device is Virtual or Logical) | Get this from the /devices/{Device_ID} RestAPI endpoint; Only available if device is virtual or logical |
DeviceModel | Model of the device | Get this from the /devices RestAPI endpoint for a physical device. |
PhysicalModelSocketCount | Number of sockets that may be populated with physical CPUs on the Physical Device | Get this from the /devices/{Device_ID} RestAPI endpoint; May not always be available |
PhysicalModelCoreCount | Maximum number of cores per CPU according to the model documentation | Get this from the /devices/{Device_ID} RestAPI endpoint; May not always be available |
PhysicalDeviceManufacturer | Manufacturer of the Physical Device | Get this from the /devices/{Device_ID} RestAPI endpoint; May not always be available |
PhysicalHostname | Hostname of the Physical Device | Get this from the /devices/{Device_ID} RestAPI endpoint for virtual devices; May not always be available |
PhysicalFQDN | Fully Qualified Domain Name of the Physical Device | Get this from the /devices/{Device_ID} RestAPI endpoint; May not always be available |
IP Address |
| V4 also exposes IP6 addresses. |
PhysicalMACAddress | If more than 1, will be semi-colon separated. | |
VirtualMACAddress | If more than 1, will be semi-colon separated. | |
ClusterInformation | The virtualization cluster that the physical machine is part of | Only available if it is part of a cluster, and the cluster has been scanned |
ClusterName | Name of cluster | Only available if it is part of a cluster, and the cluster has been scanned |
PartitioningMethod | Virtualization Method (VMware, HyperV, LPAR etc.). If this field is null it indicates the device is physical. | |
DerivedCPU | Not directly available via RestAPI. Must be coded in the script. | |
DerivedCoresPerCPU | Not directly available via RestAPI. Must be coded in the script. | |
Bios | Concatenation of Device.BIOSName, DeviceBIOSManufacturer, Device.BIOSVersion separated by semi-colons. | Get this from the /devices/{Device_ID} RestAPI endpoint. |
LastScanDate | Last date the device was scanned | Get this from the /devices/{Device_ID} RestAPI endpoint. |
DeviceID | The unique identifier for this device | The Rest API gives unique identifiers in GUID format |
PhysicalDeviceID | The unique identifier of the Physical Device (where relevant) – used to map logical devices or Virtual machines back to the Physical Device which hosts them. | Get this from the /devices/{Device_ID} RestAPI endpoint; May not always be available |
PhysicalCPUNotes | Notes that indicate CPU vs socket mismatches or CPU core values that don’t match the CPU model | This V3 data is not directly available via RestAPI. This functionality is part of DataHub for V4, and if required must be coded in the script. |
Notes | Notes related to the device model | This V3 data is not directly available via RestAPI. This functionality is part of DataHub for V4, and if required must be coded in the script. |
ExternalLink | Link to model documentation from the vendor | This V3 data is not available via RestAPI. |
DNSHostname | The hostname of the device as reported from DNS | Get this from the /devices/{Device_ID} RestAPI endpoint; May not always be available |
DNSFQDN | The fully qualified hostname of the device as reported from DNS | Get this from the /devices/{Device_ID} RestAPI endpoint; May not always be available |
PhysicalDNSHostname | The hostname of the physical device as reported from DNS | Get this from the /devices/{Device_ID} RestAPI endpoint; May not always be available |
PhysicalDNSFQDN | The fully qualified hostname of the physical device as reported from DNS | Get this from the /devices/{Device_ID} RestAPI endpoint; May not always be available |
MeasurementComment | Will contain additional info such as “Believed to be: Oracle Linux Server release 5.7” where appropriate | This V3 data is not available via RestAPI. |
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
$fs = 100 # fetch_size $offset = 1 # offset $seen = 1; # first offset is 1, not 0 while ( $seen -lt $devicecount) { # Outer loop, grab a batch (defined by fetch_size) of devices $url = -join ("http://", $sonar, "/api/v1/devices/?offset=", $offset, "&fetch_size=", $fs) $devices = Invoke-RestMethod $url -Credential $credential $i = 1 while ($i -lt $devices.count) { # inner loop - process individual devices in this batch # We want to populate some of the data fields in the CSV file - what can we fill in just from the DEVICES end point $row = New-Object System.Object $row | Add-Member -MemberType NoteProperty -Name "DeviceID" -Value $dev.device_id # If the path was only partly successful we might not have a serial number. However we can safely store the empty string. # if you are processing RestAPI using PHP or a different scripting language that is stricter about handling undefined variables, # you need error handling code around here too. $row | Add-Member -MemberType NoteProperty -Name "Serial-Number" -Value $dev.serial_number # For certain devices, for example some SNMP devices, or for storage devices we might not get a hostname! Explicitly call out a device with no hostname. # Also if hostname is not defined, there will be no qualified name(s) if (!$devices[$i].host_name) { # Hostname is not defined $row | Add-Member -MemberType NoteProperty -Name "Hostname" -Value "(undefined)" $row | Add-Member -MemberType NoteProperty -Name "FQDN" -Value "(undefined)" $row | Add-Member -MemberType NoteProperty -Name "DNSFQDN" -Value "(undefined)" } else { # Hostname is defined $row | Add-Member -MemberType NoteProperty -Name "Hostname" -Value $dev.host_name # If the array is not present, $num gets value 0, and so the inner loop will not fire # we have already set FQDN and DNSFQDN to "(undefined)" where there is no hostname, but we can sometimes have a hostname but no FQDN $num = $devices[$i].qualified_name.count if ($num -eq 0) { $row | Add-Member -MemberType NoteProperty -Name "FQDN" -Value "(undefined)" $row | Add-Member -MemberType NoteProperty -Name "DNSFQDN" -Value "(undefined)" } else { $j = 0 $fqdn = "(No FQDN)" while ($j -lt $num) { if ($devices[$i].qualified_name[$j].name_type -eq "DNSFQDN") { # DNSFQDN can also be used for FQDN. $fqdn = $devices[$i].qualified_name[$j].name $row | Add-Member -MemberType NoteProperty -Name "DNSFQDN" -Value $devices[$i].qualified_name[$j].name $row | Add-Member -MemberType NoteProperty -Name "FQDN" -Value $devices[$i].qualified_name[$j].name } elseif ($devices[$i].qualified_name[$j].name_type -eq "FQDN") { $row | Add-Member -MemberType NoteProperty -Name "FQDN" -Value $devices[$i].qualified_name[$j].name } $j = $j + 1 } } } # Locations is an array containing one or more locations. We can store locations[0].name as the location $row | Add-Member -MemberType NoteProperty -Name "Location" -Value $devices[$i].locations[0].name # The Last Scan Date should always be there, but if absent PowerShell will happily record a NULL value for us. $row | Add-Member -MemberType NoteProperty -Name "LastScanDate" -Value $devices[$i].last_scan $csv += $row $i = $i + 1; # keep track for inner loop $seen = $seen + 1; # keep track for outer loop } # Finished this batch $offset = $seen } |
Getting the rest of the info
There is a lot more information saved about each device which is not returned in the summary provided by the devices endpoint.
...
Providing feedback to the user
Once we start iterating down into subsequent API calls for individual devices, the script will run for much longer than when we limit ourselves to the top level data. Therefore we need to provide some feedback so that the user does not assume the script has crashed. When we have finally processed all of the data, we can report to the user that we are finished, and save the CSV file.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
#
# To find out how many devices there are, ask for the first device and look at the header for the device count
# offset=1 means start with first device. fetch_size=1 means only return one record.
$uri = -join ("http://", $sonar, "/api/v1/devices/?offset=1&fetch_size=1")
$r = Invoke-WebRequest $uri -Credential $credential
# $r.headers has HTML headers, $r.content has text content
$deviceCount = $r.headers.'X-fetch-count'
# Let the user know how many devices we can see
$output = -join ( "There are: ", $deviceCount, " devices in total")
write-host $output
#
# ... set up CSV
#
$fs = 100 # fetch_size
$offset = 1 # offset
$seen = 1; # first offset is 1, not 0
while ( $seen -lt $devicecount)
{
# Outer loop, grab a batch (defined by fetch_size) of devices
$url = -join ("http://", $sonar, "/api/v1/devices/?offset=", $offset, "&fetch_size=", $fs)
$devices = Invoke-RestMethod $url -Credential $credential
$i = 1
while ($i -lt $devices.count)
{
# inner loop - process individual devices in this batch
# do something with the data
$csv += $row
$i = $i + 1; # keep track for inner loop
$seen = $seen + 1; # keep track for outer loop
if ( $seen % 10 -eq 0) {
# progress indicator - display a "." every 10 devices
write-host "." -nonewline
}
}
# Finished this batch
$offset = $seen
}
write-host " Done. Saving output to OutputDevices.csv now."
# Save the output to a file
$csv | Export-csv OutputDevices.csv -NoTypeInformation
|
Getting the rest of the info
There is a lot more information saved about each device which is not returned in the summary provided by the devices endpoint.
The way to access this information is by using the additional endpoints defined by devices/device-id
This endpoint in turn contain links to more endpoints. As of Gwynn R3, these endpoints are:
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
# Is this device physical or virtual if ($currDevice.is_virtual -eq "false") { # This is a physical target # We can fill in physical hardware details directly, and leave the entries for virtual hardware blank # Physical device RAM $row | Add-Member -MemberType NoteProperty -Name "PhysicalRAM" -Value = total_memory_mb # Physical Device CPU Info # Sometimes we don't get CPU Information if ($currDevice.cpu_count -eq 0) or (!$currDevice.cpu_count) { # Physical CPU info not avialble $row | Add-Member -MemberType NoteProperty -Name "PhysicalCPUCount" -Value "n/a" $row | Add-Member -MemberType NoteProperty -Name "PhysicalCoreCount" -Value "n/a" $row | Add-Member -MemberType NoteProperty -Name "PhysicalCoresPerCPU" -Value "n/a" $row | Add-Member -MemberType NoteProperty -Name "PhysicalCPUManufacturer" -Value "n/a" $row | Add-Member -MemberType NoteProperty -Name "PhysicalCPUModel" -Value "n/a" $row | Add-Member -MemberType NoteProperty -Name "PhysicalCPUSpeed" -Value "n/a" } else { # we have at least some CPU info $row | Add-Member -MemberType NoteProperty -Name "PhysicalCPUCount" -Value $currDevice.cpu_count $row | Add-Member -MemberType NoteProperty -Name "PhysicalCoreCount" -Value $currDevice.core_count # Further details will be derived from cpu[0] if present if (!$currDevice.cpu[0].manufacturer) { # additional info missing $row | Add-Member -MemberType NoteProperty -Name "PhysicalCoresPerCPU" -Value "n/a" $row | Add-Member -MemberType NoteProperty -Name "PhysicalCPUManufacturer" -Value "n/a" $row | Add-Member -MemberType NoteProperty -Name "PhysicalCPUModel" -Value "n/a" $row | Add-Member -MemberType NoteProperty -Name "PhysicalCPUSpeed" -Value "n/a" } else { $row | Add-Member -MemberType NoteProperty -Name "PhysicalCoresPerCPU" -Value $currDevice.cpu[0].core_count $row | Add-Member -MemberType NoteProperty -Name "PhysicalCPUManufacturer" -Value $currDevice.cpu[0].manufacturer $row | Add-Member -MemberType NoteProperty -Name "PhysicalCPUModel" -Value $currDevice.cpu[0].cpu_model $row | Add-Member -MemberType NoteProperty -Name "PhysicalCPUSpeed" -Value $currDevice.cpu[0].cpu_speed } } $row | Add-Member -MemberType NoteProperty -Name "PhysicalModelSocketCount" -Value "n/a" # not exposed in V4 RestAPI $row | Add-Member -MemberType NoteProperty -Name "PhysicalModelCoreCount" -Value "n/a" # not exposed in V4 RestAPI $row | Add-Member -MemberType NoteProperty -Name "PhysicalDeviceManufacturer" -Value $currDevice.manufacturer $row | Add-Member -MemberType NoteProperty -Name "PhysicalHostname" -Value $dev.host_name # # Add this later # $row | Add-Member -MemberType NoteProperty -Name "PhysicalMACAddress" -Value $null } |
Additional details for
...
virtual hosts
For virtual hosts, we will have virtual device info corresponding to the physical device info stored above.
Additionally if iQSonar has scanned the virtualization host and identified the host that the VM is running on, we will also have the the details for the host server and a pointer to any cluster that the host might be part of.
Info |
---|
Related articles
Filter by label (Content by label) | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
...