9. Sanet Rest Api

Contenuti

• Sanet Rest Api

  • Introduzione

  • Installazione

    • Abilitazione il modulo

    • Configurazione principale

  • API REST

    • Formato delle richieste

      • URL Base

      • Passaggio parametri (GET)

    • Formato delle risposte

      • Risposte con successo

      • Risposte di errore

    • Parametri per filtrare/ordinare/limitare

      • Filtri sul valori dei campi

      • Limite sui risultati

      • Ordinamento dei risultati

    • Valori speciali per parametri

  • ELENCO API DISPONIBILI

    • Nodi

      • Lista dei nodi

      • Info su un nodo

      • Cambiamenti di stato primary condition

    • Interfacce

      • Lista interfacce

      • Info interfaccia

      • Traffico interfaccia

    • Storage

      • Lista storage

    • Servizi

      • Lista servizi

    • Device

      • Lista device

    • Condition

      • Lista condition

    • Datasource

      • Lista datasource

      • Valore massimo datasource

      • Valore medio datasource

      • Valore minimo datasource

      • Somma di datasource

    • Tag

      • Elenco dei tagtree

      • Elenco dei tag

      • Ultimo valore dei datasource contenuti in un tag

      • Valori mensili dell'anno precedente dei datasource contenuti in un tag

    • Allarmi

      • Allarmi in corso

    • Log

      • Elenco dei log

9.1. Introduzione

Il modulo rest_api permette di effettuare interrogazioni sullo stato di Sanet una API REST basata su protocollo HTTP.

Important

Questo modulo non e' attivo di default.

9.2. Installazione

9.2.1. Abilitazione il modulo

Per abilitare il modulo, inserire nel file:

{{SANET_INSTALL_DIR}}/conf/settings.py

la seguente riga:

if 'rest_api' not in INSTALLED_APPS: INSTALLED_APPS.append('rest_api')

9.2.2. Configurazione principale

Per utilizzare le REST API e' necessario definire un token di autenticazione che deve essere specificato in tutte le richieste.

Il token e' una stringa di caratteri lunga a piacere.

Per personalizzare il token di autenticazione (il default è una chiave casuale), inserire la seguente riga nel file di configurazione di Sanet:

REST_API_AUTH_COOKIE = " ... "

Esempi:

REST_API_AUTH_COOKIE = "*!@!)@#5dc(*@NJ#$(108123-181@->?]"

REST_API_AUTH_COOKIE = "thisismysecrettoken"

Warning

il token di autenticazione deve essere univoco per installazione.

9.3. API REST

9.3.1. Formato delle richieste

9.3.1.1. URL Base

La URL base per le richieste e':

https://....<base url>...../rest_api/ <parte variabile> [ ? <parametri in GET> ]

9.3.1.2. Passaggio parametri (GET)

Le richieste possono prevedere un numero variabili di parametri passati in GET nella URL della richiesta.

9.3.1.2.1. Parametri principali

Questi sono i parametri GET che sono validi per qualunque URL:

Nome parametro	Obbligatorio	Descrizione
sanet3auth	Si	Stinga contenente il token di sicurezza valido. Deve essere uguale al parametro di configurazione REST_API_AUTH_COOKIE
tenantid		Serve a specificare il tenant sul quale effettuare la ricerca. Se non specificato viene utilizzato il tenant primary.
username		Serve a filtrare la ricerca in base alla visibilità dell'utente specificato.

9.3.1.2.2. Parametri opzionali

E' possibile passare in GET un numero arbitrario di parametri opzionali.

https://.........../rest_api/.... ? <param1> & <param2> & <param3> ....

La semantica dei parametri dipende da quale API viene richiamata.

9.3.2. Formato delle risposte

9.3.2.1. Risposte con successo

In caso di successo, le risposte vengono inviate al cliente con una risposta HTTP con codice 200.

Il contentuto della response HTTP (l'output della richiesta) sono dei dati codificati in formato JSON,

I dati della risposta sono strutturati sempre con questa struttura:

{
        "elapsed_time": <tempo di elaborazione>,
        "operation"   : <nome dell'operazione richiesta sulla risorsa>,
        "result"      : <dati veri e propri prodotti dell'interrogazione effettuata>
}

In base al tipo di interrogazione effettuata possono essere aggiunti più o meno campi.

9.3.2.2. Risposte di errore

In caso di errori o anomalie, le risposte vengono inviate al cliente con una risposta HTTP con codice di errore coerente con il tipo di segnalazione.

Il contentuo della reponse HTTP sara' stringa contente il messaggio di errore in formato intelleggibile.

9.3.3. Parametri per filtrare/ordinare/limitare

9.3.3.1. Filtri sul valori dei campi

Molte delle API (url) che restituiscono un elenco di elementi possono ricevere in GET un numero arbitrario di filtri.

Esempio:

https://.........../rest_api/.... ?name="ciccio"

Un filtro e' una stringa di caratteri con la seguente sintassi:

<filter def>=<value>

La parte filter def "codifica" il tipo di filtro.

La parte value codifica il/i valore/i su cui filtrare.

Questi sono i tipi di valori ammesi per un filtro:

• null

  • Il valore verra' considerato come il valore booleano corrispondente.

    <filter def>=null
    

• true | false

  • Il valore verra' considerato come il valore booleano corrispondente.

    <filter def>=true
    

    <filter def>=false
    

• un stringa di numeri interi

  • Il valore verra' considerato come l'intero corrispente

    <filter def>=22
    

• una stringa di caratteri compatibile con un numero in virgola mobile

  • Il valore verra' considerato un numero float

    <filter def>=3.14
    

• una stringa alfanumerica racchiusa tra doppi apici (")

  • Il valore verra' considerato come una stringa di caratteri, doppi apici esclusi.

    <filter def>="Hello world"
    

• una lista di valori

  • Una sequenza dei tipi precenti racchiusa tra parentisi quadre ([]) e separata da virgola (,)

    <filter def>=[10,20,30,40]
    <filter def>=["UP","DOWN"]
    

• una stringa alfanumerica senza doppi apici (caso speciale)

  • Il valore verra' considerato come una stringa di caratteri

  • Valido solo per filtri semplici il cui valore non contiene spazi

    <filter def>=Hello
    

E' possibile specificare valori speciali per alcuni campi. Si veda Valori speciali per parametri.

9.3.3.1.1. Nome dei campi nei filtri

I filtri sui campi hanno la seguente sintassi:

<field>=<value>

Esempio:

cluster=null

is_primary=true

name="localhost"

name=localhost         (caso speciale)

9.3.3.1.2. Nome dei custom field nei filtri

Se il "campo" su cui si vuole filtrare e' un custom field, il field deve essere indicato cosi'

<custom group>.<custom field>=<value>

Esempio: Supponendo di avere un customfield telephone del customgroup inventory-data, un filtro potrebbe essere:

custom-group inventory-data
    field telephone  type str  long-name "Telephone"  description "Telephone number"  order 0
    field serial     type num  long-name "Serial"     description "Serial"            order 0
exit

Il filtro da specificare sui campi potrebbe essere:

inventory-data.telephone="0516318342"

inventory-data.serial="12345"

9.3.3.1.3. Filtri di confronto

Hanno la seguente sintassi:

<field>__<op>=<value>

Dove field e' il nome di un campo (o del customfield) indica il tipo di confronto:

OP	SEMANTICA
gt	>
gte	>=
lt	<
lge	<=
isnull	true|false verifica che il valore non sia "null"
contains	Il campo <field> contiene la stringa specificata
icontains	Il campo <field> contiene la stringa specificata (case insensitive)
in	Il campo <field> rientra tra i valori specificati nella lista <value>
range	Il campo <field> rientra tra i valori compresi nel range specificato della lista di due elementi espressa con <value> (es. [10,30]).

Esempi su campi normali:

status__gte=10

status__lt=33

status__isnull=true

status__in=["UP","DN"]

timestamp__range=[1582022058,1582194858]

Esempi su customfield:

inventory-data.telephone__contains="0516318342"

inventory-data.telephone__isnull=true

inventory-data.telephone__isnull=false

9.3.3.1.4. Filtri di join

Alcuni oggetti hanno delle relazioni con altri oggeti attraverso foreign key.

E' possibile "seguire" la catena di join specificando il nome delle foreignkey e utilizzano il doppio underscore (__) per filtrare sul campo dell'entita' in join

<foreign_key>__<field> [ __<field> ] [__<op>]=<value>

Esempio:

cluster__isnull=false                            Filtra tutti gli elementi che hanno la foreign key "cluster" valorizzata.

cluster__name=c1                                 Filtra tutti gli elementi che hanno la foreign key "cluster" che referenzia l'oggetto cluster "c1".

elementtemplate__telement__name=server-linux     Filtra tutti gli elementi che referenziano un template "server-linux".

Important

Per utilizzare questo tipo di filtri bisogna conoscere lo schema ER del database di Sanet.

9.3.3.2. Limite sui risultati

E' possibili limitare il numero di risultati aggiungendo il parametro '_limit'.

Esempio:

https://.........../rest_api/events?_limit=10

9.3.3.3. Ordinamento dei risultati

Con il parametro '_order' e' possibile specificare su quale/i campi ordinare i risultati.

La sintassi e':

_order=<nome campo>[,<nome campo, ...]

Esempio:

https://.........../rest_api/events?_order=timestamp

https://.........../rest_api/events?_order=timestamp,status

9.3.3.3.1. Ordinamento crescente/decrescente

Per default l'ordinamento e' crescente.

Per impostare un ordinamento decrescente bisogna anteporre il carattere '-' al nome del campo su cui si sta effettuando l'ordinamento.

Esempio:

_order=-timestamp

_order=condition_path,-timestamp

9.3.4. Valori speciali per parametri

Per acluni campi e' possibile specificare sia valori in formato "numerico" che in formato "stringa":

• Datasource

  • status

    STRINGA	VALUE	Descrizione
    OK	0	Normal value
    SV	10	Strange avlue
    CA	20	Cascade error
    DO	30	Dependson
    UN	40	Uncheckable
    ER	50	Unknown error

• Condition, Event

  • status

  • statuslast

    STRINGA	VALORE	Descrizione
    DN	10	Down
    FA	20	Failing
    UD	30	Uncheckable Down
    UU	40	Uncheckable UP
    DD	45	Dependson Down
    DU	46	Dependson Up
    IN	70	Suspended
    UP	100	Up

9.4. ELENCO API DISPONIBILI

9.4.1. Nodi

9.4.1.1. Lista dei nodi

DESCRIZIONE

Per ricevere una lista di tutti i nodi, la url da interrogare è la seguente:

http://<hostname>/sanet/rest_api/nodes

Esempio:

http://<hostname>/sanet/rest_api/nodes?sanet3auth=12345

INPUT

Accetta in input un numero arbitrario di filtri. Si rimanda alla sezione: Parametri per filtrare/ordinare/limitare.

OUTPUT

Come risposta si riceverà il json standard Risposte con successo con una lista di dizionari, contenenti informazioni sui nodi filtrati, nel campo result.

{
 'elapsed_time': 0.005944013595581055,
 'operation': u'fetch_all_node',
 'result': [
                {
                'cluster_distinguisher': None,
                'cluster_element_id': None,
                'cluster_id': None,
                'cluster_instance': None,
                'cluster_instance_time': None,
                'cluster_role': 0,
                'cluster_xform': None,
                'description': u'',
                'dft_timeout': 1,
                'dns6_name': None,
                'dns_name': None,
                'effective_ip': u'127.0.0.1',
                'ip4_mgt': None,
                'ip6_mgt': None,
                'is_abstract': False,
                'kind': 1,
                'name': u'localhost',
                'parent_id': None,
                'path': u'localhost',
                'snmp_community': u'public',
                'snmp_port': 161,
                'snmp_v3_authdata': None,
                'snmp_version': 2,
                'tenant_id': u'16d3c6af68a84588a70d446a4d30d540',
                'timezone': u'Europe/Rome',
                'use_ipv4': True,
                'uuid': u'23ca1860edbd4711822edb319717c616'
                }
        ]
}

9.4.1.2. Info su un nodo

DESCRIZIONE

Per ricevere infomazioni su un nodo specifico, la url da interrogare è una delle seguenti:

https://<url base>/rest_api/node/<uuid o nome del nodo>

Esempio:

https://<url base>/rest_api/node/localhost?sanet3auth=12345

INPUT

Nessuno.

OUTPUT

Come risposta si riceverà il json standard Risposte con successo con un dizionario, contenente informazioni sul nodo richiesto, nel campo result.

{
 'elapsed_time': 0.010519027709960938,
 'operation': 'get_node_info',
 'result': {
            'cluster_distinguisher': None,
            'cluster_element_id': None,
            'cluster_id': None,
            'cluster_instance': None,
            'cluster_instance_time': None,
            'cluster_role': 0,
            'cluster_xform': None,
            'description': u'',
            'dft_timeout': 1,
            'dns6_name': None,
            'dns_name': None,
            'effective_ip': u'127.0.0.1',
            'ip4_mgt': None,
            'ip6_mgt': None,
            'is_abstract': False,
            'kind': 1,
            'name': u'localhost',
            'parent_id': None,
            'path': u'localhost',
            'snmp_community': u'public',
            'snmp_port': 161,
            'snmp_v3_authdata': None,
            'snmp_version': 2,
            'tenant_id': u'16d3c6af68a84588a70d446a4d30d540',
            'timezone': u'Europe/Rome',
            'use_ipv4': True,
            'uuid': u'23ca1860edbd4711822edb319717c616'
           }
}

9.4.1.3. Cambiamenti di stato primary condition

DESCRIZIONE

Per ricevere la lista dei cambiamenti di stato della condition primary di uno specifico nodo, la url da interrogare è la seguente:

https://<url base>/rest_api/node/<uuid o nome del nodo>/get_primary_condition_status_change[?ts_start=<timestamp>&ts_end=<timestamp>]

Esempio

https://<url base>/rest_api/node/localhost/get_primary_condition_status_change?sanet3auth=12345

INPUT

Parametri opzionali da fornire in GET sono ts_start e ts_end. Se non valorizzati, vengono valutati i dati delle ultime otto ore.

OUTPUT

Come risposta si riceverà il json standard Risposte con successo con nel campo result una lista di tuple

(ts_start, ts_end, status)

Alla risposta vengono aggiunti anche i seguenti campi:

• element_name: nome del nodo

• element_uuid: uuid del nodo

• element_path: path del nodo

• condition_path: path della condition

Esempi

Esempi di richieste:

https://<url base>/rest_api/node/localhost/get_primary_condition_status_change?sanet3auth=12345
https://<url base>/rest_api/node/localhost/get_primary_condition_status_change?sanet3auth=12345&ts_start=1473142136&ts_end=1473170936

https://<url base>/rest_api/node/9401493b9e5844e0b0a4baf757fa5404/get_primary_condition_status_change?sanet3auth=12345
https://<url base>/rest_api/node/9401493b9e5844e0b0a4baf757fa5404/get_primary_condition_status_change?sanet3auth=12345&ts_start=1473142136&ts_end=1473170936

Output:

{
 'condition_path': u'localhost;;icmp-reachability;reach',
 'elapsed_time': 0.020576000213623047,
 'element_name': u'localhost',
 'element_path': u'localhost',
 'element_uuid': u'23ca1860edbd4711822edb319717c616',
 'operation': 'get_primary_condition_status_change',
 'result': [
            (1501132183, 1501160983, 100)
           ]
}

9.4.2. Interfacce

9.4.2.1. Lista interfacce

DESCRIZIONE

Per ricevere una lista di tutte le interfacce, la url da interrogare è la seguente:

https://<url base>/rest_api/interfaces

Esempio:

https://<url base>/rest_api/interfaces?sanet3auth=12345

INPUT

Accetta in input un numero arbitrario di filtri. Si rimanda alla sezione: Parametri per filtrare/ordinare/limitare.

OUTPUT

Come risposta si riceverà il json standard Risposte con successo con una lista di dizionari, contenenti informazioni sulle interfacce filtrate, nel campo result.

Esempio di risposta:

{
 'elapsed_time': 0.008428812026977539,
 'operation': u'fetch_all_interface',
 'result': [
            {
             'backbone': False,
             'cluster_distinguisher': None,
             'cluster_id': None,
             'cluster_instance': None,
             'cluster_role': 0,
             'cluster_xform': None,
             'description': u'',
             'distinguisher': u'eth0',
             'ifindex': u'2',
             'is_abstract': False,
             'kind': 2,
             'name': u'eth0',
             'parent_id': u'23ca1860edbd4711822edb319717c616',
             'path': u'localhost:eth0',
             'uuid': u'08fec5c2500c47d18e97eee7947a38e7',
             'xform': u"byRegexpUnique(1.3.6.1.2.1.2.2.1.2@, '^'+re_escape($distinguisher)+'$')"
            }
           ]
}

9.4.2.2. Info interfaccia

DESCRIZIONE

Per ricevere infomazioni su una interfaccia specifica, la url da interrogare è una delle seguenti:

https://<url base>/rest_api/interface/<uuid o nome dell'interfaccia>
https://<url base>/rest_api/interface/<uuid o nome dell'interfaccia/get_interface_info

Esempio:

https://<url base>/rest_api/interface/08fec5c2500c47d18e97eee7947a38e7/get_interface_info

INPUT

Nessuno.

OUTPUT

Come risposta si riceverà il json standard Risposte con successo con un dizionario, contenente informazioni sull'interfaccia richiesta, nel campo result.

Esempio di risposta:

{
 'elapsed_time': 0.006204843521118164,
 'operation': 'get_interface_info',
 'result': {
            'backbone': False,
            'cluster_distinguisher': None,
            'cluster_id': None,
            'cluster_instance': None,
            'cluster_role': 0,
            'cluster_xform': None,
            'description': u'',
            'distinguisher': u'eth0',
            'ifindex': u'2',
            'is_abstract': False,
            'kind': 2,
            'name': u'eth0',
            'parent_id': u'23ca1860edbd4711822edb319717c616',
            'path': u'localhost:eth0',
            'uuid': u'08fec5c2500c47d18e97eee7947a38e7',
            'xform': u"byRegexpUnique(1.3.6.1.2.1.2.2.1.2@, '^'+re_escape($distinguisher)+'$')"
           }
}

9.4.2.3. Traffico interfaccia

DESCRIZIONE

Per ricevere informazioni sul traffico di un'interfaccia specifica, la url da chiamare è la seguente:

http://<url base>/rest_api/interface/<uuid o nome dell'interfaccia>/get_traffic[?ts_start=&ts_end=]

Esempio:

http://<url base>/rest_api/interface/08fec5c2500c47d18e97eee7947a38e7/get_traffic?sanet3auth=12345

INPUT

Parametri opzionali da fornire in GET sono ts_start e ts_end. Se non valorizzati, vengono valutati i dati delle ultime otto ore.

OUTPUT

Come risposta si riceverà il json standard Risposte con successo con i seguenti campi aggiuntivi:

• element_name: nome dell'interfaccia

• element_uuid: uuid dell'interfaccia

• element_path: path dell'interfaccia

e un dizionario nel campo result contenente le seguenti chiavi:

• out_max: traffico in uscita massimo

• out_avg: traffico in uscita medio

• in_max: traffico in entrata massimo

• in_avg: traffico in entrata medio

Esempi:

https://<url base>/rest_api/interface/foo:eth0/get_traffic?sanet3auth=12345
https://<url base>/rest_api/interface/foo:eth0/get_traffic?sanet3auth=12345&ts_start=1473142136&ts_end=1473170936
https://<url base>/rest_api/interface/1b85b8c803c74d699adcce914af7d0c9/get_traffic?sanet3auth=12345
https://<url base>/rest_api/interface/1b85b8c803c74d699adcce914af7d0c9/get_traffic?sanet3auth=12345&ts_start=1473142136&ts_end=1473170936

Esempio di output:

{
 'elapsed_time': 0.011709928512573242,
 'element_name': u'eth0',
 'element_path': u'localhost:eth0',
 'element_uuid': u'08fec5c2500c47d18e97eee7947a38e7',
 'operation': 'get_traffic',
 'result':
          {
            'in_avg': 221.68289183222956,
            'in_max': 15201.112582781458,
            'out_avg': 30.25014716703459,
            'out_max': 2074.2958057395144
          }
}

9.4.3. Storage

9.4.3.1. Lista storage

DESCRIZIONE

Per ricevere una lista di tutti gli storage, la url da interrogare è la seguente:

https://<url base>/rest_api/storages

INPUT

Accetta in input un numero arbitrario di filtri. Si rimanda alla sezione: Parametri per filtrare/ordinare/limitare.

OUTPUT

Come risposta si riceverà il json standard Risposte con successo con una lista di dizionari, contenenti informazioni sugli storage filtrati, nel campo result.

9.4.4. Servizi

9.4.4.1. Lista servizi

DESCRIZIONE

Per ricevere una lista di tutti i servizi, la url da interrogare è la seguente:

https://<url base>/rest_api/services

INPUT

Accetta in input un numero arbitrario di filtri. Si rimanda alla sezione: Parametri per filtrare/ordinare/limitare.

OUTPUT

Come risposta si riceverà il json standard Risposte con successo con una lista di dizionari, contenenti informazioni sui servizi filtrati, nel campo result.

9.4.5. Device

9.4.5.1. Lista device

DESCRIZIONE

Per ricevere una lista di tutti i device, la url da interrogare è la seguente:

https://<url base>/rest_api/devices

INPUT

Accetta in input un numero arbitrario di filtri. Si rimanda alla sezione: Parametri per filtrare/ordinare/limitare.

OUTPUT

Come risposta si riceverà il json standard Risposte con successo con una lista di dizionari, contenenti informazioni sui device filtrati, nel campo result.

9.4.6. Condition

9.4.6.1. Lista condition

DESCRIZIONE

Per ricevere una lista di tutte le condition, la url da interrogare è la seguente:

https://<url base>/rest_api/conditions

INPUT

Accetta in input un numero arbitrario di filtri. Si rimanda alla sezione: Parametri per filtrare/ordinare/limitare.

OUTPUT

Come risposta si riceverà il json standard Risposte con successo con una lista di dizionari, contenenti informazioni sulle condition filtrate, nel campo result.

{u'elapsed_time': 0.0059909820556640625,
 u'operation': u'fetch_all_condition',
 u'result': [{u'datagroup_id': u'a84d8b2b82914a538bc495ce2cdd7d9a',
              u'dependson_id': None,
              u'expr': u'$var == 1',
              u'lastdone': 1500138760,
              u'max_tries': 1,
              u'mtime': 1500138438,
              u'name': u'check',
              u'path': u'localhost;;dgpassive;check',
              u'primary': False,
              u'priority': 0,
              u'status': 10,
              u'statuschange_action': None,
              u'statuslast': 40,
              u'statuslastchange': 1500138760,
              u'title': u'Controllo passivo',
              u'tries': 1,
              u'uncheckable_fallback': None,
              u'uuid': u'333095c2f8884b45a1dc0af1e6985bca'},
             {u'datagroup_id': u'a43d7d53c36149f09809cc32b31f6771',
              u'dependson_id': None,
              u'expr': u"1.3.6.1.2.1.1.6.0@ == 'this is a test'",
              u'lastdone': 1500139617,
              u'max_tries': 1,
              u'mtime': 1500139613,
              u'name': u'check',
              u'path': u'localhost;;test-trap-regexp;check',
              u'primary': False,
              u'priority': 0,
              u'status': 10,
              u'statuschange_action': None,
              u'statuslast': 10,
              u'statuslastchange': 1500139617,
              u'title': u'Simple condition',
              u'tries': 0,
              u'uncheckable_fallback': None,
              u'uuid': u'5ad5e373451d4ea5b31c38a940e78ac2'},
             {u'datagroup_id': u'ab43c217e32d49068d4aa55c5c262035',
              u'dependson_id': None,
              u'expr': u"1.3.6.1.2.1.1.6.0@ == 'this is a test'",
              u'lastdone': 1500139617,
              u'max_tries': 1,
              u'mtime': 1500139613,
              u'name': u'check',
              u'path': u'localhost;;test-trap;check',
              u'primary': False,
              u'priority': 0,
              u'status': 10,
              u'statuschange_action': None,
              u'statuslast': 10,
              u'statuslastchange': 1500139617,
              u'title': u'Simple condition',
              u'tries': 0,
              u'uncheckable_fallback': None,
              u'uuid': u'97f2f82c827d44868d08794baf5d3e65'}]}

9.4.6.1.1. Esempi

• Tutte le condition che contengono "localhost" nel path:

  https://<url base>/rest_api/conditions ? sanet3auth=.... & path__contains=localhost
  

• Tutte le condition con status "DOWN" ("DN" o 10)

  https://<url base>/rest_api/conditions ? sanet3auth=.... & status=DN
  
  https://<url base>/rest_api/conditions ? sanet3auth=.... & status=10
  

• Tutte le condition appartenente al nodo localhost

  https://<url base>/rest_api/conditions ? sanet3auth=.... & element__name=localhost
  

9.4.7. Datasource

9.4.7.1. Lista datasource

DESCRIZIONE

Per ricevere una lista di tutti i datasource, la URL da interrogare è la seguente:

https://<url base>/rest_api/datasources

INPUT

Accetta in input un numero arbitrario di filtri. Si rimanda alla sezione: Parametri per filtrare/ordinare/limitare.

OUTPUT

Come risposta si riceverà il json standard Risposte con successo con una lista di dizionari, contenenti informazioni sui datasource filtrati, nel campo result.

9.4.7.2. Valore massimo datasource

DESCRIZIONE

Per ricevere il valore massimo di uno specifico datasource in un arco temporale, la url da interrogare è la seguente:

https://<url base>/rest_api/datasource/<uuid del datasource>/get_max_value

INPUT

Parametri opzionali da fornire in GET sono

• ts_start

• ts_end

• timespec

Se ts_start e ts_end non vengono valorizzati, saranno valutati i dati delle ultime otto ore.

Il parametro timespec permette di specificare, secondo la sintassi usanta in entables (Times), fasce temporali all'interno dell'intervallo [ts_start, ts_end].

OUTPUT

Come risposta si riceverà il json standard Risposte con successo con i seguenti campi aggiuntivi:

• element_name: nome dell'elemento

• element_uuid: uuid dell'elemento

• datasource_path: path del datasource

• datasource_name: nome del datasource

• datasource_uuid: uuid del datasource

e il valore richiesto nel campo result.

9.4.7.3. Valore medio datasource

DESCRIZIONE

Per ricevere il valore medio di uno specifico datasource in un arco temporale, la url da interrogare è la seguente:

https://<url base>/rest_api/datasource/<uuid del datasource>/get_avg_value

INPUT

Parametri opzionali da fornire in GET sono

• ts_start

• ts_end

• timespec

Se ts_start e ts_end non vengono valorizzati, saranno valutati i dati delle ultime otto ore.

Il parametro timespec permette di specificare, secondo la sintassi usanta in entables (Times), fasce temporali all'interno dell'intervallo [ts_start, ts_end].

OUTPUT

Come risposta si riceverà il json standard Risposte con successo con i seguenti campi aggiuntivi:

• element_name: nome dell'elemento

• element_uuid: uuid dell'elemento

• datasource_path: path del datasource

• datasource_name: nome del datasource

• datasource_uuid: uuid del datasource

e il valore richiesto nel campo result.

9.4.7.4. Valore minimo datasource

DESCRIZIONE

Per ricevere il valore minimo di uno specifico datasource in un arco temporale, la url da interrogare è la seguente:

https://<url base>/rest_api/datasource/<uuid del datasource>/get_min_value

INPUT

Parametri opzionali da fornire in GET sono

• ts_start

• ts_end

• timespec

Se ts_start e ts_end non vengono valorizzati, saranno valutati i dati delle ultime otto ore.

Il paraemtro timespec permette di specificare, secondo la sintassi usanta in entables (Times), fasce temporali all'interno dell'intervallo [ts_start, ts_end].

OUTPUT

Come risposta si riceverà il json standard Risposte con successo con i seguenti campi aggiuntivi:

• element_name: nome dell'elemento

• element_uuid: uuid dell'elemento

• datasource_path: path del datasource

• datasource_name: nome del datasource

• datasource_uuid: uuid del datasource

e il valore richiesto nel campo result.

9.4.7.5. Somma di datasource

DESCRIZIONE

Per ricevere statistiche (minimo, massimo, media) della somma di datasource in un arco temporale, la url da interrogare è la seguente:

https://<url base>/rest_api/datasource/sum

INPUT

Parametri obbligatori da fornire in GET sono

• uuids_or_paths : elenco di uuid o path, separati da virgola, dei datasource che si vogliono sommare

Parametri opzionali da fornire in GET sono

• ts_start

• ts_end

Se ts_start e ts_end non vengono valorizzati, saranno valutati i dati delle ultime otto ore.

OUTPUT

Come risposta si riceverà il json standard Risposte con successo con i seguenti campi aggiuntivi:

• datasource_uuids_paths: elenco di uuid o path dei datasource recuperati

e con i seguenti dati nel campo result.

• series: la serie completa con la somma dei datasource

• max: picco massimo della serie in series

• ts_max: timestamp relativo al picco massimo

• min: picco minimo della serie in series

• ts_min: timestamp relativo al picco massimo

• avg: media della serie in series

Nel caso in cui si verificasse un errore, nel campo errors sara' presente una descrizione del problema.

Note

Nel caso in cui uno o piu' datasource, per qualsiasi motivo, non dovessero essere recuperati l'API si comportera' nel seguente modo': * nel campo errors verranno indicati quali sono i datasource non recueprati; * nel campo result verrano riportati i dati degli eventuali datasource rimanenti e correttamente trovati.

9.4.8. Tag

9.4.8.1. Elenco dei tagtree

DESCRIZIONE

Per avere l'elenco dei tagtree bisogna utilizzare la seguente URL:

https://<url base>/rest_api/tagtrees

Esempio:

https://<url base>/rest_api/tagtrees?sanet3auth=12345

INPUT

Nessuno.

OUTPUT

Come risposta si riceverà il JSON standard Risposte con successo.

Il campo result della risposta contiene una lista di dizionari (chiave/valore) con gli attributi di tutti i tagtree selezionati.

Esempio:

{'elapsed_time': 0.002173900604248047,
 'operation': u'fetch_all_tagtree',
 'result': [{'name': u'geo2',
             'path': u'geo2:',
             'uuid': u'f364154bab32441094c4208f024f040a'},
            {'name': u'111',
             'path': u'111:',
             'uuid': u'bc54391b09334acea89597d49056ad8a'},
            {'name': u'geo',
             'path': u'geo:',
             'uuid': u'63e7a2b9b243409a97a231b1ae35a73f'},
            {'name': u'prova_tagging',
             'path': u'prova_tagging:',
             'uuid': u'68d3e1a3f2554c02acd2e8247313546f'},
            {'name': u'tagtree1',
             'path': u'tagtree1:',
             'uuid': u'326d13e3c51f41afae2c61f79012e59b'},
            {'name': u'tree1',
             'path': u'tree1:',
             'uuid': u'd201a37ca9db4ca298d3a854f8ca1e78'},
            {'name': u'tree12',
             'path': u'tree12:',
             'uuid': u'865b09a66a804098b003895307a87607'},
            {'name': u'tree13',
             'path': u'tree13:',
             'uuid': u'9c3c3286493643bdb07ae2b1683640d1'},
            {'name': u'tree1b',
             'path': u'tree1b:',
             'uuid': u'7111510021ea46a49823d05e038815c4'},
            {'name': u'tree1c',
             'path': u'tree1c:',
             'uuid': u'0b626627b2744958bea22da7c29bef67'},
            {'name': u'xxx',
             'path': u'xxx:',
             'uuid': u'6ebee2af0d8c4f968fb9f9edd68f76b4'},
            {'name': u'yyy',
             'path': u'yyy:',
             'uuid': u'c4a9ee0c543f4a8894066eb2d61f7ee3'},
            {'name': u'zzz',
             'path': u'zzz:',
             'uuid': u'fc1364a9c73d41059860661f8408f092'},
            {'name': u'tag2',
             'path': u'tag2:',
             'uuid': u'ade885ce11144a419afe6bd1d38cd422'}]}

9.4.8.2. Elenco dei tag

DESCRIZIONE

Per avere l'elenco dei tagtree bisogna utilizzare la seguente URL:

https://<url base>/rest_api/tags

INPUT

Nessuno

OUTPUT

Come risposta si riceverà il JSON standard Risposte con successo.

Il campo result della risposta contiene una lista di dizionari (chiave/valore) con gli attributi di tutti i tag selezionati.

Esempio:

{'elapsed_time': 0.00951695442199707,
 'operation': u'fetch_all_tag',
 'result': [{'icon': None,
             'mtime': 1500153752,
             'name': u'Geografico',
             'parent_id': None,
             'path': u'geo:/Geografico',
             'tree_id': u'63e7a2b9b243409a97a231b1ae35a73f',
             'uuid': u'422ce2179631474eb34a27cff467102a'}]}

9.4.8.3. Ultimo valore dei datasource contenuti in un tag

DESCRIZIONE

Elabora tutti i datasource del tag (e sottotag) e restituisce l'ultimo valore registrato.

http://<hostname>/sanet/rest_api/tag/<uuid or path>/datasources/get_last_value?<params>

Esempio:

http://<hostname>/sanet/rest_api/tag/422ce2179631474eb34a27cff467102a/datasources/get_last_value?sanet3auth=12345&sum_by=name

INPUT

Questi sono i parametri in Get:

• tag (stringa)

  UUID o PATH del tag da elaborare.

• sum_by (stringa)

  Indica se sommare i valori dei datasource elabrorati e in che modo.

  I valori ammessi sono:

  • "by-name" : Somma i valori dei datasource raggruppando per nome del datasource

  • "no" : Restituisce informazioni sull'ultimo valore per tutti i datasource elaborati.

  Facoltativo: Si

OUTPUT

Restituisce un messaggio nel formato:

{
        'elapsed_time': <tempo in secondi>
        ,
        'errors'      : <numero di anomalie in fase di elaborazione>
        ,
        'data'        : <dati della richiesta>
}

Il contentuto/formato del campo data dipende dal valore specificato dai parametri in input.

Quando sum_series valore "no", il campo data contiene un elenco di tuple:

<parent_id, parent_name, element_id, element_name, ds_uuid, ds_name, ds_path, value>

Quando sum_series valore "by-name",il campo data contiene un elenco di tuple:

< datasource name , total >

Esempi

Esempio: Chiamata senza parametro sum_by

{'elapsed_time': 0.022342920303344727,
 'errors': '9 datasources not loaded',
 'operation': 'get_last_value',
 'result': [(u'23ca1860edbd4711822edb319717c616',
             u'localhost',
             u'82fe0ef593ea46d39f912344868613b5',
             u'root',
             u'0a0685b44c154d998d23b4e387f717db',
             u'used',
             u'localhost:root;;storage;used',
             None),
            (u'23ca1860edbd4711822edb319717c616',
             u'localhost',
             u'82fe0ef593ea46d39f912344868613b5',
             u'root',
             u'f4d23572b18a446292eee43e240b69fd',
             u'installed',
             u'localhost:root;;storage;installed',
             None),
            (u'23ca1860edbd4711822edb319717c616',
             u'localhost',
             u'08fec5c2500c47d18e97eee7947a38e7',
             u'eth0',
             u'48d9aec8ec194cec9813e6c4502eda0a',
             u'out',
             u'localhost:eth0;;iface-traffic;out',
             None)]}

Esempio: Chiamata senza parametro sum_by=name

{'elapsed_time': 0.027868032455444336,
 'errors': '9 datasources not loaded',
 'operation': 'get_last_value',
 'result': [
            (u'installed', 122341423131),
            (u'used', 12345345)]}

9.4.8.4. Valori mensili dell'anno precedente dei datasource contenuti in un tag

DESCRIZIONE

Elabora tutti i datasource del tag (e sottotag) e restituisce il valore registrato all'inizio di ogni mese dell'anno.

http://<hostname>/sanet/rest_api/tag/<uuid or path>/datasources/get_last_year_values?<params>

Esempio:

http://<hostname>/sanet/rest_api/tag/geo:/Geografico/datasources/get_last_year_values?sanet3auth=12345
http://<hostname>/sanet/rest_api/tag/422ce2179631474eb34a27cff467102a/datasources/get_last_year_values?sanet3auth=12345

INPUT

Questi sono i parametri all'interno della URL:

• <uuid or path> (stringa)

  UUID o PATH del tag da elaborare.

Questi sono i parametri in GET:

• valid_time_window (intero)

  In presenza di valori nulli registrati, numero di secondi di tolleranza entro il quale cercare il prima volore valido. Se non vengono trovati valori non nulli all'interno del periodo di tolleranza, il valore registrato per quel meso sara' None.

OUTPUT

Restituisce un messaggio nel formato:

{
        'elapsed_time': <tempo in secondi>
        ,
        'errors'      : <numero di anomalie in fase di elaborazione>
        ,
        'result'      : <dati della richiesta>
}

Quando sum_series valore "no", il campo data contiene un elenco di tuple:

<date, parent_id, parent_name, element_id, element_name, ds_uuid, ds_name, value>

Esempi

{'elapsed_time': 0.014796972274780273,
 'errors': '0 datasources not loaded',
 'operation': 'get_last_year_values',
 'result': [('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'ccd306b551a94e9ca67673d7a96f89fb', 'in', 'localhost:eth0;;iface-traffic;in', '2016-01-01', 1451602800.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'ccd306b551a94e9ca67673d7a96f89fb', 'in', 'localhost:eth0;;iface-traffic;in', '2016-02-01', 1454281200.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'ccd306b551a94e9ca67673d7a96f89fb', 'in', 'localhost:eth0;;iface-traffic;in', '2016-03-01', 1456786800.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'ccd306b551a94e9ca67673d7a96f89fb', 'in', 'localhost:eth0;;iface-traffic;in', '2016-04-01', 1459461600.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'ccd306b551a94e9ca67673d7a96f89fb', 'in', 'localhost:eth0;;iface-traffic;in', '2016-05-01', 1462053600.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'ccd306b551a94e9ca67673d7a96f89fb', 'in', 'localhost:eth0;;iface-traffic;in', '2016-06-01', 1464732000.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'ccd306b551a94e9ca67673d7a96f89fb', 'in', 'localhost:eth0;;iface-traffic;in', '2016-07-01', 1467324000.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'ccd306b551a94e9ca67673d7a96f89fb', 'in', 'localhost:eth0;;iface-traffic;in', '2016-08-01', 1470002400.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'ccd306b551a94e9ca67673d7a96f89fb', 'in', 'localhost:eth0;;iface-traffic;in', '2016-09-01', 1472680800.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'ccd306b551a94e9ca67673d7a96f89fb', 'in', 'localhost:eth0;;iface-traffic;in', '2016-10-01', 1475272800.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'ccd306b551a94e9ca67673d7a96f89fb', 'in', 'localhost:eth0;;iface-traffic;in', '2016-11-01', 1477954800.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'ccd306b551a94e9ca67673d7a96f89fb', 'in', 'localhost:eth0;;iface-traffic;in', '2016-12-01', 1480546800.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'a66f9268b838471d98d5b579ad4f9c0c', 'out', 'localhost:eth0;;iface-traffic;out', '2016-01-01', 1451602800.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'a66f9268b838471d98d5b579ad4f9c0c', 'out', 'localhost:eth0;;iface-traffic;out', '2016-02-01', 1454281200.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'a66f9268b838471d98d5b579ad4f9c0c', 'out', 'localhost:eth0;;iface-traffic;out', '2016-03-01', 1456786800.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'a66f9268b838471d98d5b579ad4f9c0c', 'out', 'localhost:eth0;;iface-traffic;out', '2016-04-01', 1459461600.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'a66f9268b838471d98d5b579ad4f9c0c', 'out', 'localhost:eth0;;iface-traffic;out', '2016-05-01', 1462053600.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'a66f9268b838471d98d5b579ad4f9c0c', 'out', 'localhost:eth0;;iface-traffic;out', '2016-06-01', 1464732000.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'a66f9268b838471d98d5b579ad4f9c0c', 'out', 'localhost:eth0;;iface-traffic;out', '2016-07-01', 1467324000.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'a66f9268b838471d98d5b579ad4f9c0c', 'out', 'localhost:eth0;;iface-traffic;out', '2016-08-01', 1470002400.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'a66f9268b838471d98d5b579ad4f9c0c', 'out', 'localhost:eth0;;iface-traffic;out', '2016-09-01', 1472680800.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'a66f9268b838471d98d5b579ad4f9c0c', 'out', 'localhost:eth0;;iface-traffic;out', '2016-10-01', 1475272800.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'a66f9268b838471d98d5b579ad4f9c0c', 'out', 'localhost:eth0;;iface-traffic;out', '2016-11-01', 1477954800.0, None),
            ('79b977c52f6e4c84aa496ba942ba70d8', 'localhost', 'ec6e4cb188b64ebcbce204d14380de4d', 'eth0', 'a66f9268b838471d98d5b579ad4f9c0c', 'out', 'localhost:eth0;;iface-traffic;out', '2016-12-01', 1480546800.0, None)]}

9.4.9. Allarmi

9.4.9.1. Allarmi in corso

DESCRIZIONE

Per avere l'elenco dei allarmi (corrispondenti a condition down) bisogna utilizzare la seguente URL:

https://<url base>/rest_api/alarm/current

INPUT

Sono previsti i seguenti parametri

• priority_level (stringa)

  Se specificato, vengono restituiti solo gli allarmi con priority che ricade nel range del priority_level indicato.

OUTPUT

Come risposta si riceverà il JSON standard Risposte con successo.

Il campo result della risposta contiene una lista di dizionari (chiave/valore) con gli attributi di tutti i allarmi selezionati.

{
        "elapsed_time": <tempo di elaborazione>,
        "operation"   : <nome dell'operazione richiesta sulla risorsa>,
        "result"      : [
            { ... },
            { ... },
            { ... },
            { ... },
            { ... },
        ]
}

La struttura dati per ogni allarme contiene informazioni su:

• elemento associato all'allarme.

• la condition associata all'allarme.

• la variazione di stato che ha generato l'allarme.

• informazioni sui tag associati all'elemento e condition dell'allarme.

Esempo di dati di un singolo allarme:

{
    "uuid"      : "7eb499dd9fb54f0a87afd351d0c4ce56"                                 *identificativo univoco dell'allarme*
    "ts"        : 1511001368,                                                        *timestamp UTC**di generazione dell'allarme*
    "element": {
         "uuid"       : "e173f52135b845a5bf1792e33ad508ac"                            *identificativo univoco dell'elemento associato all'allarme*
         "path"       : "dm10lx03:rootfs",                                            *identificativo univoco mnemonico dell'elemento associato all'allarme*
         "name"       : "rootfs",                                                     *nome dell'elemento*
         "description": "Root FS",                                                    *descrizione**dell'elemento*
         "type"       : 3,                                                            *tipo dell'elemento (1=nodo,2=interfaccia,3=storage,4=service,5=device)*
         "parent_id"  : "a12937d61c874890914182b6d25ebbb8",                           *identificativo dell'elemento padre (l'uuid del nodo)*
         "parent_name": "dm10lx03",                                                   *identificativo univoco dell'elemento padre (il nome del nodo)*
    },
    "condition": {
        "uuid"            : "050db78a671e48358ca266a92e9c9682"                       *identificativo univoco della condition che ha generato l'allarme*
        "path"            : "dm10lx03:rootfs;storage;storage;check-storageperc",     *identificativo mnemonico*
        "name"            : "check-storageperc",                                     *nome della **condition*
        "description"     : "Check occupazione filesystem root",                     *descrizione**della condition*
        "classification"  : "system.storage.usage",                                  *classificazione della **condition*
        "priority"        : 60,                                                      *importanza/priorita' associata alla **condition*
        "priority_level"  : "medium",                                                *classe di importanza/priorita' associata alla **condition*
        "statuslastchange": 1511001368,                                              *timestamp ***UTC**della *variazione di stato precedente della **condition*
    },
    "result": {                                                                      *risultati del check*
        "status"    : 10,                                                            *stato della verifica della condition*
        "laststatus": 20,                                                            *stato precedente*
    },
    "info": {                                                                        *informazioni dell'elemento*
        "ip4s"       : ['10.0.25.201'],
    },
    "mail": {
        "subject": ".....",
        "body": "....."
    }
    "tags": [                                                                        *opt. **classificazioni/tag assegnati alla condizione o all'elemento associati all'allarme*
        "dmh:/DMH/Sistemi Critici/3.Labs"
    ],
    "cluster": {                                                                     ***opt. *cluster al quale l'elemento e' associato*
        "name"       : ['VMWare-Produzione'],
    },
    "meta": {                                                                        ****opt. *informazioni addizionali dell'elemento*
        "referenti" : [                                                              *referenti associati all'elemento*
            'Sergio Rizzi <sergio.rizzi@labs.it>',
            'Tiziano Fogli <tiziano.fogli@labs.it>'
        ]
    },
}

9.4.10. Log

9.4.10.1. Elenco dei log

DESCRIZIONE

Per avere l'elenco dei tagtree bisogna utilizzare la seguente URL:

https://<url base>/rest_api/events

Esempio:

https://<url base>/rest_api/events?sanet3auth=12345

INPUT

Accetta in input un numero arbitrario di filtri. Si rimanda alla sezione: Parametri per filtrare/ordinare/limitare.

OUTPUT

Come risposta si riceverà il JSON standard Risposte con successo.

Il campo result della risposta contiene una lista di dizionari (chiave/valore) con gli attributi di tutti gli eventi selezionati.