Documentazione

Esempi di API REST

La seguente sezione contiene esempi di script bash su come eseguire azioni utilizzando l'API REST di SKOOR con l'utilità curl. La maggior parte degli input e degli output è formattata in JSON. Per una maggiore leggibilità, in alcuni esempi è stato utilizzato il parser JSON jq, che può essere installato dai comuni repository Redhat o CentOS.

Intestazione dello script Bash

Parametri comuni da impostare come intestazione dello script bash per gli esempi di script riportati di seguito (USER e PASSWORD devono essere adattati a un utente reale di SKOOR):

#!/bin/bash
HOST=reltest
USER=admin
PASSWORD=admin

Esempi di richiesta

Le richieste e i corpi delle richieste negli esempi seguenti possono essere copiati e incollati così come sono, ad eccezione degli id degli oggetti che devono essere sostituiti da quelli esistenti sul sistema in cui vengono eseguite le richieste. Le parti dei corpi delle richieste devono essere fornite anche se non contengono valori significativi per la creazione o l'aggiornamento degli oggetti.

La maggior parte delle informazioni sulla data e sull'ora nelle richieste devono essere fornite nel formato ISO 8601 e nel formato della durata.

Sessione SKOOR

Accedere a SKOOR:

SESSION_ID=$(curl --silent -k "https://$HOST/skoor-webservice/session/login?username=$USER&password=$PASSWORD" | jq -r '.sessionId') >/dev/null

Effettuare sempre il logout al termine di tutte le richieste. Le sessioni rimangono aperte per 24 ore, altrimenti

Disconnessione:

curl -k "https://$HOST/skoor-webservice/session/logout?sessionId=$SESSION_ID"

Utenti

Interrogare tutti gli utenti di SKOOR e analizzare i nomi e i ruoli usando jq:

curl --silent -k "https://$HOST/skoor-webservice/users?&sessionId=$SESSION_ID" | jq -r '.[] | "\(.name) \(.role)"'

Gruppi

Interrogare un gruppo specifico con id 495:

curl -k -X GET "https://$HOST/skoor-webservice/groups/495?sessionId=$SESSION_ID"

Interrogare un gruppo utilizzando un filtro di ricerca codificato dall'URL. Il risultato dovrebbe contenere tutti i gruppi al di sotto dell'id 207 del gruppo padre .

Filtro di ricerca originale: gruppi con id non uguale a 207:

{"type":"group","mode": "and","conditions": [{"item":"id","operator": "ne","expression":"207"}]}

Filtro di ricerca con codifica URL (la codifica/decodifica può essere effettuata utilizzando un lavoro HTTP di SKOOR o uno dei numerosi servizi presenti su Internet):

%7B%22type%22%3A%22group%22%2C%22mode%22%3A%20%22and%22%2C%22conditions%22%3A%20%5B%7B%22item%22%3A%22id%22%2C%22operator%22%3A%20%22ne%22%2C%22expression%22%3A%22207%22%7D%5D%7D

Interrogazione:

curl -k -X GET "https://$HOST/skoor-webservice/groups/207/search?filterDefinition=%7B%22type%22%3A%22group%22%2C%22mode%22%3A%20%22and%22%2C%22conditions%22%3A%20%5B%7B%22item%22%3A%22id%22%2C%22operator%22%3A%20%22ne%22%2C%22expression%22%3A%22207%22%7D%5D%7D&sessionId=$SESSION_ID"

Dispositivi

Interrogare il dispositivo con id 383:

curl -k -X GET "https://$HOST/skoor-webservice/devices/383?sessionId=$SESSION_ID"

Creare un dispositivo sotto il gruppo con id 308:

Richiesta di un dispositivo di sottotipo server con il nome SKOOR Server. Impostare il collettore predefinito sull'id 2, che è il collettore locale:

DEVICE_BODY='{
	"type": "device",
	"subType": "server",
	"name": "SKOOR Server",
	"address": "",
	"netmask": "",
	"deviceName": "localhost",
	"properties": [],
	"parameter": {},
	"permissions": {
		"read": true,
		"write": true,
		"execute": true
	},
	"isTemplate": false,
	"instanceType": "sub",
	"collectorId": 2,
	"hasChildren": false
}'

Richiesta:

echo $DEVICE_BODY | curl -s -k -X POST -H "Content-Type: application/json" -d @- "https://$HOST/skoor-webservice/devices?parentType="group"&parentId="308"&sessionId=$SESSION_ID"

Creare un'istanza di dispositivo da un modello sotto il gruppo con id 332. A tal fine, verrà utilizzato il metodo copy dell'API REST. L'id del dispositivo (180 nell'esempio) deve essere impostato sull'id del modello di dispositivo :

curl -k -X POST "https://$HOST/skoor-webservice/devices/180/copy?destinationName="rest-test"&destinationAddress="localhost"&parentType="group"&parentId=332&destinationType="instance"&collectorId=2&jobsStopped=false&sessionId=$SESSION_ID"

Eliminare il dispositivo con id 558:

Gli oggetti eliminati possono essere ripristinati solo dal backup della configurazione!

curl -k -X DELETE "https://localhost/skoor-webservice/devices/558?recursive=true&sessionId=$SESSION_ID"

Lavori

Interrogare il lavoro id 1675 con soglie e valori:

curl -ks -X GET "https://$HOST/skoor-webservice/jobs/1675?thresholds=true&values=true&sessionId=$SESSION_ID"

Cerca un lavoro utilizzando un filtro di ricerca.

Filtro di ricerca con codifica URL per cercare i lavori sotto il gruppo con id 216 che hanno una proprietà personalizzata con la chiave test_property impostata sul valore abc:

curl -ks -X GET "https://$HOST/skoor-webservice/groups/216/search?filterDefinition=%7B%22type%22%3A%22job%22%2C%22mode%22%3A%22and%22%2C%22conditions%22%3A%5B%7B%22item%22%3A%22property_key%22%2C%22operator%22%3A%22eq%22%2C%22expression%22%3A%22abc%22%2C%22propertyKey%22%3A%22test_property%22%7D%5D%7D&sessionId=$SESSION_ID"

Filtro di ricerca in testo semplice per i lavori del sottotipo webcollector sotto il gruppo 310 con risultato analizzato con jq:

curl -ks -X GET -G "https://$HOST/skoor-webservice/groups/310/search?sessionId=$SESSION_ID" --data-urlencode "filterDefinition={\"type\":\"job\",\"mode\":\"and\",\"conditions\":[{\"item\":\"subType\",\"operator\":\"eq\",\"expression\":\"webcollector\"}]}" | jq -r '.items[] | "\(.deviceName) \(.name) \(.id)"'

Creare un lavoro sotto l'id del dispositivo 555:

Corpo della richiesta per un lavoro del sottotipo webcollector con nome TEST generato e tre valori di ritorno. Creare il lavoro sotto il dispositivo con id 555. L'intervallo di esecuzione sarà impostato a 0 secondi (PT0S: nessun intervallo):

JOB_BODY='{
	"type": "job",
	"name": "TEST generated",
	"deviceId": 555,
	"subType": "webcollector",
	"interval": "PT0S",
	"stopped": false,
	"parameters": {
		"intervalMode": 0,
		"filename": "",
		"returnValue": [
			{
				"valueName": "Return value 1"
			},
			{
				"valueName": "Return value 2"
			},
			{
				"valueName": "Return value 3"
			}
		]
	},
	"isTemplate": false,
	"properties": [],
	"permissions": {
		"read": true,
		"write": true,
		"execute": true
	},
	"instanceType": "none",
	"stateForced": false,
	"thresholds": null,
	"values": null,
	"message": null
}'

Richiesta:

echo $JOB_BODY | curl -s -k -X POST -H "Content-Type: application/json" -d @- "https://$HOST/skoor-webservice/jobs?parentType="device"&parentId="555"&sessionId=$SESSION_ID"

Aggiorna lavoro con id 1608:

Richiesta del corpo del lavoro con id 1608 sul dispositivo id 555. Impostare le soglie per questo lavoro:

JOB_BODY_UPDATE='{
	"type": "job",
	"id": 1608,
	"name": "Richmond",
	"deviceId": 555,
	"deviceName": "TEST generated device",
	"subType": "webcollector",
	"interval": "PT0S",
	"stopped": false,
	"parameters": {
		"intervalMode": 0,
		"filename": "",
		"returnValue": [
			{
				"valuePrecision": 3,
				"valueName": "myValue"
			}
		]
	},
	"isTemplate": false,
	"properties": [],
	"permissions": {
		"read": true,
		"write": true,
		"execute": true
	},
	"instanceType": "none",
	"currentState": "ok",
	"stateForced": false,
	"thresholds": {
		"major": {
			"mode": "or",
			"conditions": [
				{
					"key": "returnValue1",
					"operator": ">",
					"value": 60.0,
					"repetition": 1,
					"inFuture": null,
					"adaptiveValues": null
				}
			]
		}
	},
	"values": {},
	"message": null,
	"collectorId": 2
}'

Richiesta:

echo $JOB_BODY_UPDATE | curl -s -k -X PUT -H "Content-Type: application/json" -d @- "https://$HOST/skoor-webservice/jobs/1608?sessionId=$SESSION_ID"

Arresto/avvio del lavoro con id 1605:

curl -ks -X GET -G "https://$HOST/skoor-webservice/jobs/1605?sessionId=$SESSION_ID" | jq -r '.stopped = false' | curl -s -k -X PUT -H "Content-Type: application/json" -d @- "https://$HOST/skoor-webservice/jobs/1605?sessionId=$SESSION_ID"

Interrogazione dello storico dei valori del lavoro id 1326:

Le informazioni sulla data e sull'ora devono essere fornite nel formato ISO 8601 e nel formato della durata.

curl -ks -X GET "https://$HOST/skoor-webservice/jobs/1326/value-history?timestamp_begin=2018-04-16T08%3A00%3A00Z&timestamp_end=2018-04-16T10%3A00%3A00Z&scale=PT10M&key=returnValue1&mode=avg&values=true&sessionId=$SESSION_ID"

SLC

Interrogazione dello storico dello stato SLC con id 6:

curl -k -X GET "https://$HOST/skoor-webservice/slcs/6/state-history?timestamp_begin=2017-10-01T00:00%2B01:00&timestamp_end=2017-12-12T23:59%2B01:00&recalc=true&sessionId=$SESSION_ID"

SLO

Interrogazione dello SLO con id 116:

curl -k -X GET "https://$HOST/skoor-webservice/slos/116?sessionId=$SESSION_ID"

Interrogazione della cronologia di stato dello SLO id 116:

curl -k -X GET "https://$HOST/skoor-webservice/slos/116/state-history?timestamp_begin=2018-01-01T00:00%2B01:00&timestamp_end=2018-12-12T23:59%2B01:00&recalc=true&sessionId=$SESSION_ID"

Interrogare gli oggetti figli di SLO id 176:

curl -k -X GET "https://$HOST/skoor-webservice/slos/176/children?sessionId=$SESSION_ID"

Creare SLO sotto il gruppo id 296:

Corpo della richiesta per uno SLO di sottotipo top con il nome SLO TEST:

SLO_BODY='{
	"type": "slo",
	"subType": "top",
	"name": "TEST SLO",
	"deviceId": 0,
	"deviceName": "",
	"stateOperation": "and",
	"pushState": "any",
	"sortMode": "link",
	"warning": 0,
	"minor": 0,
	"major": 0,
	"minorWarning": 0,
	"minorMinor": 0,
	"warningWarning": 0,
	"isTemplate": false,
	"ignoreMaintenance": true,
	"isReason": true,
	"properties": [],
	"parameters": {
		"children": 0,
		"costsPerMin": 0,
		"currency": "",
		"riskFactor": 0
	},
	"permissions": {
		"read": true,
		"write": true,
		"execute": true
	},
	"instanceType": "none"
}'

Richiesta:

echo $SLO_BODY | curl -s -k -X POST -H "Content-Type: application/json" -d @- "https://$HOST/skoor-webservice/slos?parentType=group&parentId=296&sessionId=$SESSION_ID"

Creare un'istanzaSLO dal modello SLO con id 179. Il nome dello SLO sarà rest-test-slo e l'oggetto genitore sarà lo slo con id 177:

curl -k -X POST "https://$HOST/skoor-webservice/slos/179/copy?destinationName=rest-test-slo_1&parentType=slo&parentId=177&destinationType=instance&sessionId=$SESSION_ID"

Interruzioni

Interrogare le interruzioni tra il 2019-02-21T09:00+01:00 e il 2019-03-21T23:59+01:00 (URL codificato). Il valore predefinito è una durata minima di 10 minuti (PT10M) e solo per lo stato Major:

curl -k -X GET "https://$HOST/skoor-webservice/devices/383/outages?begin=2019-02-21T09:00%2B01:00&end=2019-03-21T23:59%2B01:00&recalc=false&sessionId=$SESSION_ID"

Rivalutazioni

Interrogare le rivalutazioni del gruppo 207 dal 2019-04-01T00:00:00Z:

curl -k -X GET "https://$HOST/skoor-webservice/groups/207/revaluations?begin=2019-04-01T00:00:00Z&sessionId=$SESSION_ID"

Aggiungere una rivalutazione al gruppo id 207:

I parametri di inizio e fine devono essere impostati in UTC seguito dal fuso orario Z o +00:00 o dall'ora locale seguita dal fuso orario (ad es. +02:00). Il parametro fuso orario influisce solo sull'array di orari

Se l'ora di inizio del parametro non corrisponde all'ora di inizio dell'array di orari, la manutenzione verrà visualizzata solo in modalità di modifica (Modifica rivalutazione). Si tenga presente che il MET distingue automaticamente tra ora legale e ora solare. In questo caso, impostare l'ora di inizio sull'ora locale.

Corpo della richiesta per una rivalutazione una tantum da 2019-04-13T07:20:00Z a 2019-04-13T08:20:00Z:

REVALUATION_BODY='{
	"begin": "2019-04-13T07:20:00Z",
	"end": "2019-04-13T08:20:00Z",
	"created": null,
	"type": "maintenance",
	"adjustTo": "undefined",
	"inPast": null,
	"incident": null,
	"name": "Test-Maintenance",
	"active": [
		{
			"type": "one_time",
			"name": null,
			"timezone": "UTC",
			"times": [
				{
					"begin": "07:20",
					"duration": "PT1H",
					"date": "2019-04-13"
				}
			],
			"exception": false
		}
	]
}'

Richiesta:

echo $REVALUATION_BODY | curl -k -X POST -H "Content-Type: application/json" -d @- "https://$HOST/skoor-webservice/groups/207/revaluations?sessionId=$SESSION_ID"
Precedente
SKOOR Webservice
Successivo
API REST per l'esportazione del cruscotto