Documentazione

Esempi di API REST

La sezione seguente contiene esempi di script bash su come eseguire azioni utilizzando l'API REST SKOOR con l'utilità curl. La maggior parte degli input e degli output è formattata in JSON. Per facilitare la lettura, in alcuni esempi è stato utilizzato il parser JSON jq, che può essere installato dai repository comuni 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 SKOOR reale):

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

Esempi di richiesta

Le richieste e i corpi delle richieste negli esempi riportati di seguito possono essere copiati e incollati così come sono, ad eccezione degli ID oggetto che devono essere sostituiti con quelli esistenti nel sistema in cui vengono eseguite le richieste. È necessario fornire parti dei corpi delle richieste anche se non contengono valori significativi per la creazione o l'aggiornamento degli oggetti.

La maggior parte delle informazioni relative alla data e all'ora nelle richieste deve essere fornita nel formato ISO 8601 e nel formato della durata.

Sessione SKOOR

Accedi a SKOOR:

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

Si prega di effettuare sempre il logout dopo aver completato tutte le richieste. Le sessioni rimangono aperte per 24 ore, altrimenti

Disconnettersi:

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

Utenti

Interroga tutti gli utenti SKOOR e analizza nomi e ruoli utilizzando jq:

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

Gruppi

Interroga un gruppo specifico con id 495:

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

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

Filtro di ricerca originale: gruppi con id diverso da 207:

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

Filtro di ricerca codificato URL (la codifica/decodifica può essere eseguita utilizzando un job HTTP SKOOR o uno dei numerosi servizi disponibili 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

Query:

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

Interroga il dispositivo con id 383:

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

Crea un dispositivo sotto il gruppo con id 308:

Corpo della richiesta per un dispositivo di sottotipo server con il nome SKOOR Server. Impostare il collettore predefinito su 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 del dispositivo da un modello sotto il gruppo con id 332. A tal fine, verrà utilizzato il metodo di copia dell'API REST. L'id del dispositivo (180 nell'esempio) deve essere impostato sull'id del modello del 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 con 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 al di sotto del gruppo con id 216 che hanno una proprietà personalizzata con 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 lavori del sottotipo webcollector sotto il gruppo 310 con risultato analizzato utilizzando 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 dispositivo 555:

Corpo della richiesta per un lavoro di 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 su 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"

Aggiornamento del lavoro con id 1608:

Corpo della richiesta per il lavoro con id 1608 sul dispositivo con id 555. Imposta 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"

Interrompi/avvia il 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"

Richiedi cronologia valori del lavoro con ID 1326:

Le informazioni relative a data e 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

Richiesta della cronologia 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

Query SLO con id 116:

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

Richiesta della cronologia dello stato di 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"

Richiesta oggetti secondari di SLO id 176:

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

Crea SLO sotto l'id di gruppo 296:

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

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"

Crea istanza SLO dal modello SLO con id 179. Il nome SLO sarà rest-test-slo e l'oggetto padre 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

Richiesta di interruzioni tra 2019-02-21T09:00+01:00 e 2019-03-21T23:59+01:00 (codifica URL). L'impostazione predefinita è una durata minima di 10 minuti (PT10M) e solo 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

Interroga 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"

Aggiungi una rivalutazione al gruppo id 207:

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

Se l'ora del parametro di inizio non corrisponde all'ora di inizio dell'array dei tempi, la manutenzione verrà visualizzata solo in modalità di modifica (Modifica rivalutazione). Si prega di notare che MET distinguerà 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 dalle 07:20:00 del 13/04/2019 alle 08:20:00 del 13/04/2019:

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