-
-
Notifications
You must be signed in to change notification settings - Fork 38
Groups
Groups can be retrieved from a PRTG Server via the GetGroups method
var groups = client.GetGroups();If you wish to filter for groups that meet certain search criteria you can specify a Property to filter on using one of several overloads
//Get groups whose name match "Servers"
var groups = client.GetGroups(Property.Name, "Servers");//Get groups under probes whose name contains "office"
var groups = client.GetGroups(Property.Probe, FilterOperator.Contains, "office");Queries can also be specified via LINQ style query expressions, allowing high performance queries to be executed via dynamically generated request parameters.
var names = client.QueryGroups(g => g.Name == "Servers")
.Select(s => s.Name)
.Take(20);For more information on using LINQ style queries, see Queries.
When retrieving a particular group you insist should exist, it is possible to use the singular GetGroup method, returning a single Group rather than a List<Group> as with GetGroups.
var group = client.GetGroup(1234);If a group with the specified object ID cannot be found (or somehow multiple objects were found) GetGroup will throw an InvalidOperationException. If you are not sure whether a group exists, you should use GetGroups instead and check for the presence of any results.
var group = client.GetGroups(Property.Id, 1234).FirstOrDefault();
if (group != null)
Console.WriteLine($"Found group {group}!");Filters are implemented internally via the SearchFilter class. One or more SearchFilter objects can be specified to filter on multiple properties.
//Get all groups with more than 10 sensors under probes whose name contains "office"
var filters = new[]
{
new SearchFilter(Property.TotalSensors, FilterOperator.GreaterThan, 10),
new SearchFilter(Property.Probe, FilterOperator.Contains, "office")
};
var groups = client.GetGroups(filters);GetGroups can be used in conjunction with other methods in order to chain results together.
//Get all devices for all groups whose name contains "infrastructure"
var devices = client.GetGroups(Property.Name, FilterOperator.Contains, "infrastructure").SelectMany(
group => client.GetDevices(Property.ParentId, group.Id)
);Care should be taken when attempting to filter for sensors based on the name of a group. As sensors do not have a property which binds them to the Object ID of their groups, if you have multiple groups containing the same name, you may not be able to reliably establish the sensors under that group. This can be alleviated by retrieving all devices under the group (using the device's ParentId) and then retrieving all sensors that are under the devices.
When chaining results, consider whether your results could be acquired quicker by constructing an array of filters containing the criteria you are after; i.e. you do not need to ask for probes before groups if you know the name of the probe you'd like to find groups under.
When querying PRTG for the sensors that belong to a specified group, by default PRTG will only traverse the devices directly under the specified group. As such, any groups nested one or more levels deep will not return their child sensors. PrtgAPI does not automatically account for this via the C# API. This logic can easily be implemented however by analysing the TotalSensors, TotalDevices and TotalGroups properties of the specified parent group. For an example implementation of this, please see the method GetAdditionalRecords.
For information on creating new groups please see Object Creation.
Groups can be retrieved with PowerShell via the Get-Group cmdlet. (Note: for complete instructions on using Get-Group, please see Get-Help Get-Group)
C:\> Get-Group
Name Id Status Probe Devices Up Down Down Warning Paused
Sensors (Ack)
---- -- ------ ----- ------- -------- ---- ----- ------- ------
Root 0 Up 11 20 10 2 3 100
Servers 2070 Up Local Probe 8 14 8 0 1 80PrtgAPI automatically formats Group objects in a table, displaying the most relevant properties. To view all properties of groups, pipe your groups to Format-List
Get all groups named "Servers" (case insensitive)
C:\> Get-Group servers
Name Id Status Probe Devices Up Down Down Warning Paused
Sensors (Ack)
---- -- ------ ----- ------- -------- ---- ----- ------- ------
Servers 2070 Up Local Probe 8 14 8 0 1 80Wildcards can also be used
Get-Group *serv*,*roo*Get-Group can filter on a number of properties, including Id, Tags
C:\> Get-Group -Id 0,2197
Name Id Status Probe Devices Up Down Down Warning Paused
Sensors (Ack)
---- -- ------ ----- ------- -------- ---- ----- ------- ------
Root 0 Up 11 20 10 2 3 100
Servers 2070 PausedByUser Local Probe 8 14 8 0 1 80# Get all groups containing the C_OS_VMware tag
Get-Group -Tags C_OS_VMwareWhen filtering by tags, PrtgAPI provides two parameters that can be used
-
-Tags: Filter for objects that contain all specified tags -
-Tag: Filter for objects that contain any specified tags
# Get all groups in Manhattan, New York
Get-Groups -Tags ny,manhattan
# Get all Manhattan and Queens groups
Get-Groups -Tag manhattan,queensGet-Group accepts both Group and Probe objects via the pipeline. When an object is piped to Get-Group, the object is used as a filter in conjunction with any other filters that may be specified
Get-Probe micro* | Get-GroupGet-Group | Select -First 1 | Get-Group *serv*For group properties that are not explicitly defined as parameters on Get-Group, these properties can still can be specified as dynamic parameters
# Get all devices that are the first or second object under their parent
Get-Group -Position 1,2Cmdlet parameters that are typically used for accepting pipeline input (e.g. -Probe) can also be used for filtering by a single object name
# Get all devices under all groups whose name includes "contoso"
Get-Group -Probe *contoso*To filter by custom fields the New-SearchFilter cmdlet can be used (alias: flt)
flt totalsensors greaterthan 10 | Get-GroupWhen chaining results, consider whether your results could be acquired quicker by constructing an array of filters containing the criteria you are after; i.e. you do not need to ask for probes before groups if you know the name of the probe you'd like to find groups under.
For more information on New-SearchFilter see Filters
Group objects can also be used as the input to cmdlets (including cmdlets retrieving sensors and manipulating state). For more information see the See Also section below.
When querying PRTG for the sensors that belong to a specified group, by default PRTG will only traverse the devices directly under the specified group. As such, any groups nested one or more levels deep will not return their child sensors.
To account for this, the Get-Sensor, Get-Device and Get-Group cmdlets will automatically recurse all child groups under the specified parent group until all sensors, devices or groups have been retrieved. If you do not wish to recurse child objects, this behavior can be disabled by specifying -Recurse:$false
# Only retrieve the sensors from the devices directly under
# the group with ID 1001
Get-Group -Id 1001 | Get-Sensor -Recurse:$falseFor information on creating new groups please see Object Creation.