-
-
Notifications
You must be signed in to change notification settings - Fork 38
Requests
PrtgAPI supports three types of requests
Synchronous requests block the current thread until their results have returned
client.GetSensors();
Synchronous requests are ideal when writing a Console Application, or some other application where the PRTG processing has a thread to itself. Synchronous requests use an asynchronous HTTP Client internally, however return to synchronous methods as soon as the request has completed.
From PrtgAPI 0.7.4
Certain operations allow you to operate against multiple Object IDs in a single request. When operating against a large number of items, this can provide a substantial performance improvement. Care should be taken when processing multiple operations in a single request, as there will be a much shorter time frame during which execution can be aborted in the event you have made a mistake.
# Pause the objects with IDs 1001, 1002 and 1003 forever
client.PauseObject(new[] {1001, 1002, 1003});
All State and Property Manipulation cmdlets as well as Rename-Object
operate in batch mode by defaultThis can be overridden by specifying -Batch:$false
# Pause the sensors with IDs 1001, 1002 and 1003 forever, one at a time
Get-Sensor -Id 1001,1002,1003 | Pause-Object -Forever -Batch:$false
If Remove-Object
is invoked with -Force
and -Batch:$false
has not otherwise been specified, Remove-Object
will automatically enable batch mode to speed up the request. If Remove-Object
is invoked without any parameters, PrtgAPI will prompt for confirmation and execute removal one by one.
From PrtgAPI 0.7.4
When piping commands together in PowerShell, it is sometimes desirable to perform multiple operations against a single source object (for example, unpausing an object and then refreshing it). While this can be achieved by executing multiple separate commands, it is also possible to perform multiple operations in a single command via the -PassThru
parameter.
When -PassThru
is specified, PrtgAPI will output the input object of a cmdlet for use in the next cmdlet in the pipeline.
# Resume and refresh all paused WMI CPU Load sensors
Get-Sensor -Tags wmicpu* -Status Paused | Resume-Object -PassThru | Refresh-Object
Objects are output from operation cmdlets as they are processed. As such, when operating in Batch Mode, objects will be output to the next cmdlet only after all input objects have been read.
Note that when executing in -PassThru
mode, PrtgAPI always outputs the original object that was piped into the cmdlet. This is due to the fact that API requests are handled asynchronously by PRTG; as such, by the time a request has completed, there is no guarantee that the target object has updated by the time you try to re-retrieve it.
Asynchronous requests are implemented using await
/async
. All internal async calls are configured with ConfigureAwait(false)
, and so are safe to use in Synchronization Contexts (such as WinForms and ASP.NET)
var sensors = await client.GetSensorsAsync();
Stream requests allow you to process data from PRTG as it is returned, instead of waiting for all of the data to come back at once. This is performed by splitting large requests up into several smaller requests and returning the responses to the caller in the order they come in.
When you call a Stream method, the method returns an IEnumerable<T>
almost immediately. Only when the collection is enumerated are the requests sent to the server. If PrtgAPI detects that more than 20,000 objects will be returned from the request, PRTG will execute requests serially to prevent too many requests from queuing up and timing out. Otherwise, all of the requests will be executed all at once. Internally, the IEnumerable<T>
is a generator that forces a collection of Task<>
objects to yield their results. As a result of this, Stream requests block their calling threads when they wait for more data.
var sensors = client.StreamSensors();
foreach(var sensor in sensors)
{
Console.WriteLine(sensor.Name);
}
If you wish to reduce the load on your PRTG Server, you may optionally force specify that PRTG should stream serially. Sensor, Device, Group and Probe method overloads that support filtering do not support serial streaming. (from PrtgAPI 0.7.4)
// Serial stream all sensors
var sensors = client.StreamSensors(true);
// Serial stream a custom request, sorting all devices by their Object IDs ascending
var parameters = new DeviceParameters
{
SortBy = Property.Id
};
var devices = client.StreamDevices(parameters, true);
Stream requests are supported on the following object types