-
-
Notifications
You must be signed in to change notification settings - Fork 38
Objects
In PrtgAPI, objects returned from PRTG servers including logs, sensors, channels and notification triggers are modeled within a type hierarchy, based on what the object represents and how it relates to other objects.
There are two types of objects that can be returned by a PrtgAPI request:
- Nodes of the PRTG Network Monitor tree hierarchy
- Models used to describe details about nodes
Nodes represent "true objects" that exist within PRTG, including logs, sensors, channels and notification triggers, whereas Models represent more miscellaneous items, such as sensor totals, supported notification trigger types and system status reports.
Nodes are modeled within PrtgAPI using the IObject interface
An IObject represents an abstract object of an unspecified type. IObject should be thought of being an abstract interface containing both a name and some sort of primary identifier relating to the object's purpose, defined as follows
// Not valid C#
abstract interface IObject<IdentifierName>
{
string Name { get; set; }
// The name of the identifier used here will be different for different object categories
int <IdentifierName> { get; set; }
}In reality, due to limitations of the C# type system the interface is not abstract, and there is no enforcement that an identifier name be specified. Rather, instead of implementing IObject directly, PrtgAPI defines several sub-interfaces that implement the identifier required by IObject, which are then consumed by real objects such as sensors and devices
interface IEventObject : IObject
{
int ObjectId { get; set; }
}
interface IPrtgObject : IObject
{
int Id { get; set; }
}
class Sensor : IPrtgObject
{
...
}In order to retrieve the identifier of an unspecified IObject instance, PrtgAPI defines a GetId extension method on IObject that can be used to lookup the identifier of any IObject instance supported by PrtgAPI.
IObject obj = client.GetSensor(1001);
var id = obj.GetId();PrtgAPI defines three categories of object that implement the IObject interface
IPrtgObjectISubObjectIEventObject
Objects of type IPrtgObject are the first class citizens of PRTG. These objects have a universally unique identifier within your PRTG system. With each new object that is created, the object ID counter is permanently increased.
Examples of types that implement IPrtgObject include
ISubObject types are second class citizens. These types cannot exist on their own, but rather must exist as a "child" (or sub-object) of a uniquely identifiable IPrtgObject. The identifier of an ISubObject will generally only uniquely identify it within the sub-objects of that particular type under the parent object.
Examples of types that implement ISubObject include
IEventObject types represent events that have occurred to an IPrtgObject but do not have a unique identifier of their own. Given two IEventObject objects of the same type, describing the same event that happened at the same time, there is no way to tell whether the event did in fact occur twice without counting the occurrences of identical looking objects within the source data returned from PRTG.
Examples of types that implement IEventObject include
PRTG's most common objects (sensors, devices, groups, probes, etc) are modeled in a type hierarchy used to limit the number of times properties that are shared across multiple types need to be defined (for example, both groups and probes will have a TotalDevices property).
Due to the way that properties are split between types, the most perfect way to define all properties would be via multiple inheritance. As C# does not support multiple inheritance however, PrtgAPI does the best it can to define as many properties in a single base class as possible. To avoid any confusion, PrtgAPI names these base classes according to the types that inherit from them
class PrtgObject : IPrtgObject
{
}
...
class DeviceOrGroupOrProbe : SensorOrDeviceOrGroupOrProbe
{
}
class GroupOrProbe : DeviceOrGroupOrProbe
{
}
class Group : GroupOrProbe
{
}Fortunately, this type system has also proven quite effective when used to restrict the types of objects that can be passed to methods (only want to restrict your method to objects that can contain other objects? Sounds like you want a DeviceOrGroupOrProbe!)
All tree objects derive from the PrtgObject type, which implements the IPrtgObject interface
Object Settings represent represent items that are normally found on the Settings page of objects within the PRTG UI. For more information, see Property Manipulation.
Sensor Targets represent dynamic resources created sensors can apply to. For more information, see Sensor Targets.
Sometimes when creating a sensor PRTG may require additional information from you before it can proceed, such as the OIDLIB to use for an SNMP Sensor, the authentication credentials to use for IPMI, or the OAuth token to use for an external web service.
PrtgAPI allows you to provide this information to PRTG via the use of sensor query targets. Sensor query targets help advise PRTG as to what exactly it should target when attempting to query the parameters required to create a sensor. They are not to be confused with sensor targets, which represent the resources the sensor should monitor once it has already been created. PrtgAPI splits the concept of sensor query targets into two separate categories, depending on the stage at which PRTG desires its additional information:
- Sensor query targets represent individual items that PRTG should refer to when processing a query, such as an SNMP OIDLIB
- Sensor query target parameters represent a set of multiple parameters that PRTG should include when processing a query, such as the username and password to use for IPMI.
PrtgAPI allows the use of sensor query targets when retrieving Sensor Targets and Dynamic Sensor Parameters. When retrieving dynamic sensor parameters, any properties specified in the query parameters will already be defined on the DynamicSensorParameters object. Sensor Query Targets can also be used in conjunction with RawSensorParameters; any parameters defined on the RawSensorParameters object will be implicitly treated as potential Sensor Query Target Parameters, however you can also explicitly specify a Sensor Query Target or separate set of Sensor Query Target Parameters by assigning a value to the RawSensorParameters.QueryParameters property.
Sensor query targets can be retrieved from the QueryTargets property of SensorTypeDescriptor objects returned from GetSensorTypes (C#) and Get-SensorType (PowerShell). As string values are implicitly convertable to SensorQueryTarget, if you know the name of your target already, you can simply type it inline
//Create a set of dynamic sensor parameters for an SNMP Library sensor using the "APC UPS.oidlib" library.
//Since the queryParameters parameter is of type ISensorQueryTargetParameters and we're creating our query
//target object inline, we have to explicitly cast our string to type SensorQueryTarget
var parameters = client.GetDynamicSensorParameters(1001, "snmplibrary", queryParameters: (SensorQueryTarget) "APC UPS.oidlib");# PowerShell accepts either a SensorQueryTarget object, a query target's internal value,
# or a wildcard that PrtgAPI should use to identify the target for you
$params = $device | New-SensorParameters -RawType snmplibrary -QueryTarget "APC UPS.oidlib"When defining sensor query target parameters, unless PrtgAPI determines that a property name would be ambiguous, properties can be referred to case insensitively and without a trailing underscore.
//Create a set of sensor query target parameters for specifying the username_ and password_,
//ignoring case and lack of trailing underscores
var queryParameters = new SensorQueryTargetParameters
{
["USERNAME"] = "admin",
["password"] = "password"
}
var parameters = client.GetDynamicSensorParameters(1001, "ipmisensor", queryParameters: queryParameters);# PowerShell allows you to simply specify a hashtable
$params = $device | New-SensorParameters -RawType ipmisensor -QueryParameters @{
username = "admin"
password = "password"
}If a sensor query target or set of sensor query target parameters is required but was not specified, PrtgAPI will throw an exception listing the possible values that can be specified. In the event both a sensor query target and set of sensor query target parameters is required, this can be achieved via the SensorMultiQueryTargetParameters type (C#) or by specifying both a -QueryTarget and set of -QueryParameters (PowerShell).