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 migliorare la leggibilità, in alcuni esempi è stato utilizzato il parser JSON jq, installabile dai comuni repository Redhat o CentOS.
Intestazione dello script bash
Parametri comuni da impostare come intestazione dello script bash per gli esempi di script seguenti (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 seguenti possono essere copiati e incollati così come sono, ad eccezione degli ID oggetto che devono essere sostituiti con quelli esistenti sul sistema su cui vengono eseguite le richieste. Alcune 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 di data e ora nelle richieste deve essere fornita nel formato ISO 8601 e nel formato durata
Sessione SKOOR
Accesso a SKOOR:
SESSION_ID=$(curl --silent -k "https://$HOST/skoor-webservice/session/login?username=$USER&password=$PASSWORD" | jq -r '.sessionId') >/dev/null
Disconnettersi sempre al termine di tutte le richieste. In caso contrario, le sessioni rimarranno aperte per 24 ore
Disconnessione:
curl -k "https://$HOST/skoor-webservice/session/logout?sessionId=$SESSION_ID"
Utenti
Interrogazione di tutti gli utenti SKOOR e analisi di nomi e ruoli utilizzando jq:
curl --silent -k "https://$HOST/skoor-webservice/users?sessionId=$SESSION_ID" | jq -r '.[] | "\(.name) \(.role)"'
Gruppi
Interrogazione di un gruppo specifico con ID 495:
curl -k -X GET "https://$HOST/skoor-webservice/groups/495?sessionId=$SESSION_ID"
Interrogazione di un gruppo utilizzando un filtro di ricerca con codifica URL. Il risultato deve contenere tutti i gruppi al di sotto dell'ID gruppo padre 207.
Filtro di ricerca originale: gruppi con un 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 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
Interrogazione del dispositivo con ID 383:
curl -k -X GET "https://$HOST/skoor-webservice/devices/383?sessionId=$SESSION_ID"
Creazione di un dispositivo sotto il gruppo con ID 308:
Corpo della richiesta per un dispositivo di sottotipo server con il nome SKOOR Server. Imposta il collector predefinito su ID 2 che è il collector 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"
Creazione di un'istanza di dispositivo da un template sotto il gruppo con ID 332. A tale scopo, verrà utilizzato il metodo copy dell'API REST. L'ID del dispositivo (180 nell'esempio) deve essere impostato sull'ID del template 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"
Eliminazione del 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"
Job
Interrogazione del job con ID 1675 con soglie e valori:
curl -ks -X GET "https://$HOST/skoor-webservice/jobs/1675?thresholds=true&values=true&sessionId=$SESSION_ID"
Ricerca di un job utilizzando un filtro di ricerca.
Filtro di ricerca con codifica URL per cercare i job sotto il 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 i job di sottotipo webcollector sotto il gruppo 310 con risultato analizzato tramite 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)"'
Creazione di un job sotto il dispositivo con ID 555:
Corpo della richiesta per un job di sottotipo webcollector con nome TEST generated e tre valori restituiti. Crea il job sotto il dispositivo con ID 555. L'intervallo di esecuzione verrà 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 job con ID 1608:
Corpo della richiesta per il job con ID 1608 sul dispositivo con ID 555. Imposta le soglie per questo job:
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 job 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 della cronologia dei valori del job con ID 1326:
Le informazioni di data e ora devono essere fornite nel formato ISO 8601 e nel formato durata
curl -ks -X GET "https://$HOST/skoor-webservice/jobs/1326/value-history?timestamp_begin=2018-04-16T08%3A00%3A00Z×tamp_end=2018-04-16T10%3A00%3A00Z&scale=PT10M&key=returnValue1&mode=avg&values=true&sessionId=$SESSION_ID"
SLC
Interrogazione della cronologia degli stati SLC con ID 6:
curl -k -X GET "https://$HOST/skoor-webservice/slcs/6/state-history?timestamp_begin=2017-10-01T00:00%2B01:00×tamp_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 degli stati dello SLO con ID 116:
curl -k -X GET "https://$HOST/skoor-webservice/slos/116/state-history?timestamp_begin=2018-01-01T00:00%2B01:00×tamp_end=2018-12-12T23:59%2B01:00&recalc=true&sessionId=$SESSION_ID"
Interrogazione degli oggetti figlio dello SLO con ID 176:
curl -k -X GET "https://$HOST/skoor-webservice/slos/176/children?sessionId=$SESSION_ID"
Creazione dello SLO sotto il gruppo con ID 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"
Creazione dell'istanza SLO dal template SLO con ID 179. Il nome dello 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
Interrogazione delle interruzioni tra 2019-02-21T09:00+01:00 e 2019-03-21T23:59+01:00 (con codifica URL). L'impostazione predefinita è una durata minima di 10 minuti (PT10M) e solo 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
Interrogazione delle 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"
Aggiunta di una rivalutazione al gruppo con ID 207:
I parametri begin ed end devono essere impostati in UTC seguiti dal fuso orario Z o +00:00 oppure dall'ora locale seguita dal fuso orario (ad es. +02:00). Il parametro timezone influisce solo sull'array times
Se l'ora del parametro begin non corrisponde all'ora di inizio dell'array times, la manutenzione verrà visualizzata solo in modalità di modifica (Edit revaluation). Tenere presente che 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 dalle 2019-04-13T07:20:00Z alle 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"