mirror/librenms-librenms
1
0
Fork 0
mirror of https://github.com/librenms/librenms.git synced 2024-10-07 16:52:45 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Standardize device and device group maintenance API (#14153)

Browse Source 
* Standardise device and devicegroup maintenance API

* styleci fixes
This commit is contained in:
rhinoau
2022-07-29 00:38:46 +08:00
committed by GitHub
parent 91e7b062c5
commit d248e6561f
3 changed files with 116 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/API/DeviceGroups.md
+44 -7
View File
@@ -150,15 +150,28 @@ Route: `/api/v0/devicesgroups/:name/maintenance`
Input (JSON):
- title: Some title for the Maintenance
- notes: Some description for the Maintenance
- start: Start time of Maintenance in format H:m
- duration: Duration of Maintenance in format H:m
- `title`: *optional* - Some title for the Maintenance
Will be replaced with device group name if omitted
- `notes`: *optional* - Some description for the Maintenance
- `start`: *optional* - start time of Maintenance in full format `Y-m-d H:i:00`
eg: 2022-08-01 22:45:00
Current system time `now()` will be used if omitted
- `duration`: *required* - Duration of Maintenance in format `H:i` / `Hrs:Mins`
eg: 02:00
Example:
Example with start time:
```curl
curl -X POST -d '{"title":"Device group Maintenance","notes":"A 2 hour Maintenance triggered via API","start":"04:30","duration":"2:00"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/localhost/maintenance
curl -H 'X-Auth-Token: YOURAPITOKENHERE' \
-X POST https://librenms.org/api/v0/devicegroups/Cisco%20switches/maintenance/ \
--data-raw '
{
"title":"Device group Maintenance",
"notes":"A 2 hour Maintenance triggered via API with start time",
"start":"2022-08-01 08:00:00",
"duration":"2:00"
}
'
```
Output:
@@ -166,6 +179,30 @@ Output:
```json
{
"status": "ok",
"message": "Device group Cisco switches (2) will begin maintenance mode at 5:00 for 2:00 h"
"message": "Device group Cisco switches (2) will begin maintenance mode at 2022-08-01 22:45:00 for 2:00h"
}
```
Example with no start time:
```curl
curl -H 'X-Auth-Token: YOURAPITOKENHERE' \
-X POST https://librenms.org/api/v0/devicegroups/Cisco%20switches/maintenance/ \
--data-raw '
{
"title":"Device group Maintenance",
"notes":"A 2 hour Maintenance triggered via API with no start time",
"duration":"2:00"
}
'
```
Output:
```json
{
"status": "ok",
"message": "Device group Cisco switches (2) moved into maintenance mode for 2:00h"
}
```
doc/API/Devices.md
+43 -5
View File
@@ -1109,13 +1109,28 @@ Route: `/api/v0/devices/:hostname/maintenance`
Input (JSON):
- notes: Some description for the Maintenance
- duration: Duration of Maintenance in format H:m
- `title`: *optional* - Some title for the Maintenance
Will be replaced with hostname if omitted
- `notes`: *optional* - Some description for the Maintenance
Will also be added to device notes if user prefs "Add schedule notes to devices notes" is set
- `start`: *optional* - start time of Maintenance in full format `Y-m-d H:i:00`
eg: 2022-08-01 22:45:00
Current system time `now()` will be used if omitted
- `duration`: *required* - Duration of Maintenance in format `H:i` / `Hrs:Mins`
eg: 02:00
Example:
Example with start time:
```curl
curl -X POST -d '{"notes":"A 2 hour Maintenance triggered via API","duration":"2:00"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/localhost/maintenance
curl -H 'X-Auth-Token: YOURAPITOKENHERE' \
-X POST https://librenms.org/api/v0/devices/localhost/maintenance/ \
--data-raw '
"title":"Device Maintenance",
"notes":"A 2 hour Maintenance triggered via API with start time",
"start":"2022-08-01 08:00:00",
"duration":"2:00"
}
'
```
Output:
@@ -1123,10 +1138,33 @@ Output:
```json
{
"status": "ok",
"message": "Device localhost.localdomain (57) moved into maintenance mode for 2:00 h"
"message": "Device localhost (1) will begin maintenance mode at 2022-08-01 22:45:00 for 2:00h"
}
```
Example with no start time:
```curl
curl -H 'X-Auth-Token: YOURAPITOKENHERE' \
-X POST https://librenms.org/api/v0/devices/localhost/maintenance/ \
--data-raw '
"title":"Device Maintenance",
"notes":"A 2 hour Maintenance triggered via API with no start time",
"duration":"2:00"
}
'
```
Output:
```json
{
"status": "ok",
"message": "Device localhost (1) moved into maintenance mode for 2:00h"
}
```
### `add_device`
Add a new device. Most fields are optional. You may omit snmp
includes/html/api_functions.inc.php
+29 -10
View File
@@ -457,28 +457,35 @@ function maintenance_device(Illuminate\Http\Request $request)
return api_error(400, 'No information has been provided to set this device into maintenance');
}
// This will add a device using the data passed encoded with json
$hostname = $request->route('hostname');
// use hostname as device_id if it's all digits
$device = ctype_digit($hostname) ? DeviceCache::get($hostname) : DeviceCache::getByHostname($hostname);
$device = ctype_digit($hostname) ? Device::find($hostname) : Device::findByHostname($hostname);
if (! $device) {
return api_error(404, "Device $hostname does not exist");
if (is_null($device)) {
return api_error(404, "Device $hostname not found");
}
if (! $request->json('duration')) {
return api_error(400, 'Duration not provided');
}
$notes = $request->json('notes');
$title = $request->json('title') ?? $device->displayName();
$alert_schedule = new \App\Models\AlertSchedule([
'title' => $device->displayName(),
'title' => $title,
'notes' => $notes,
'recurring' => 0,
'start' => date('Y-m-d H:i:s'),
]);
$start = $request->json('start') ?? \Carbon\Carbon::now()->format('Y-m-d H:i:00');
$alert_schedule->start = $start;
$duration = $request->json('duration');
if (Str::contains($duration, ':')) {
[$duration_hour, $duration_min] = explode(':', $duration);
$alert_schedule->end = \Carbon\Carbon::now()
$alert_schedule->end = \Carbon\Carbon::createFromFormat('Y-m-d H:i:s', $start)
->addHours($duration_hour)->addMinutes($duration_min)
->format('Y-m-d H:i:00');
}
@@ -491,7 +498,11 @@ function maintenance_device(Illuminate\Http\Request $request)
$device->save();
}
return api_success_noresult(201, "Device {$device->hostname} ({$device->device_id}) moved into maintenance mode" . ($duration ? " for {$duration}h" : ''));
if ($request->json('start')) {
return api_success_noresult(201, "Device {$device->hostname} ({$device->device_id}) will begin maintenance mode at $start" . ($duration ? " for {$duration}h" : ''));
} else {
return api_success_noresult(201, "Device {$device->hostname} ({$device->device_id}) moved into maintenance mode" . ($duration ? " for {$duration}h" : ''));
}
}
function device_availability(Illuminate\Http\Request $request)
@@ -2143,7 +2154,11 @@ function maintenance_devicegroup(Illuminate\Http\Request $request)
$device_group = ctype_digit($name) ? DeviceGroup::find($name) : DeviceGroup::where('name', $name)->first();
if (! $device_group) {
return api_error(404, 'Device group not found');
return api_error(404, "Device group $name not found");
}
if (! $request->json('duration')) {
return api_error(400, 'Duration not provided');
}
$notes = $request->json('notes');
@@ -2170,7 +2185,11 @@ function maintenance_devicegroup(Illuminate\Http\Request $request)
$alert_schedule->save();
$alert_schedule->deviceGroups()->attach($device_group);
return api_success_noresult(201, "Device group {$device_group->name} ({$device_group->id}) will begin maintenance mode at $start" . ($duration ? " for {$duration}h" : ''));
if ($request->json('start')) {
return api_success_noresult(201, "Device group {$device_group->name} ({$device_group->id}) will begin maintenance mode at $start" . ($duration ? " for {$duration}h" : ''));
} else {
return api_success_noresult(201, "Device group {$device_group->name} ({$device_group->id}) moved into maintenance mode" . ($duration ? " for {$duration}h" : ''));
}
}
function get_devices_by_group(Illuminate\Http\Request $request)