Comparteix:

Exemples d'ús de l'API

Obtenir els IDs dels objectes d'EquipsTIC

Tots els IDs de les entitats que formen part d'una infraestructura es poden consultar i recuperar partir d'operacions GET a la API d'EquipsTIC.

La API proporciona operacions GET que permeten recuperar totes les entitats disponibles de cada apartat. En la informació que retorna, consta tant l'ID com el codi.

Exemple

Pel cas del àmbits/propòsits, si executem l'operació

GET https://bus-soades.upc.edu/EquipsTIC/APIv1/ambit

recuperem la llista de tots els àmbits/propòsits del sistema:

{
"status": "success",
"data": [
    {
      "idAmbit": 51,
      "nom": "Sala tècnica",
      "codi": "SALA_TEC",
      "categoriaInfraestructura": {
        "idCategoria": 3,
        "nom": "Equip de treball",
        "codi": "EQUIP_TREBALL"
      }
    },
    {
      "idAmbit": 57,
      "nom": "Sala tècnica",
      "codi": "SALA_TEC",
      "categoriaInfraestructura": {
        "idCategoria": 2,
        "nom": "Equip de comunicació",
        "codi": "EQUIP_COMUNICACIO"
      }
    },
    {
      "idAmbit": 62,
      "nom": "Sala tècnica",
      "codi": "SALA_TEC",
      "categoriaInfraestructura": {
        "idCategoria": 1,
        "nom": "Equip de computació",
        "codi": "EQUIP_COMPUTACIO"
      }
    },

...

A la resposta, al camp 'data' tenim una llista amb tots els objectes 'ambit'

Entre la informació retornada es troba l'id d'aquesta entitat 'idAmbit', aixì com el seu codi, junt amb informació de la categoria associada.

Igualment pels tipus d'infraestructura:

GET  https://bus-soades.upc.edu/EquipsTIC/APIv1/tipusInfraestructura

{
"status": "success",
"data": [
    {
      "idTipus": 6,
      "nom": "Impressora",
      "codi": "IMPRESSORA",
      "requereixCampsExtra": false,
      "categoriaInfraestructura": {
        "idCategoria": 3,
        "nom": "Equip de treball",
        "codi": "EQUIP_TREBALL"
      }
    },
    {
      "idTipus": 23,
      "nom": "Monitor",
      "codi": "MONITOR",
      "requereixCampsExtra": false,
      "categoriaInfraestructura": {
        "idCategoria": 3,
        "nom": "Equip de treball",
        "codi": "EQUIP_TREBALL"
      }
    },
    {
      "idTipus": 24,
      "nom": "Dockstation",
      "codi": "DOCKSTATION",
      "requereixCampsExtra": false,
      "categoriaInfraestructura": {
        "idCategoria": 3,
        "nom": "Equip de treball",
        "codi": "EQUIP_TREBALL"
      }
    },
...

Tota la resta d'entitats complementàries de les infraestructures segueixen un comportament anàlog. Tant els edificis, campus, categories, estats, marques, sistemes operatius, etc, tenen una operació GET genèrica que permet recuperar la llista total d'entitats, amb tota la informació, IDs i codis inclosos.

En el cas de les marques, si us trobeu que una marca que voleu utilitzar no es troba entre les existents a EquipsTIC, tindreu que demanar a un administrador que creï la nova marca, exactament igual que passaria en cas d'estar utilitzant la interfície web d'EquipsTIC.

El mateix aplica per altres entitats, si trobeu a faltar un valor en una entitat s'ha de contactar amb un administrador o un gestor de la unitat, depenent del cas, per demanar que la doni d'alta.

Noteu que amb les operacions exposades per la API es poden recuperar totes les dades necessàries per crear (POST) i modificar (PUT) les infraestructures.

Operacions POST (creació) i PUT (modificació)

Les operacions POST (creació d'infraestructura) i PUT (modificació d'infraestructura) reben com a paràmetre una estructura JSON amb els camps de la infraestructura que es vol crear/modificar.

Aquesta estructura JSON ha de ser un objecte infraestructura válid, amb tots els camps necessaris per validar-la informats. A l'operació PUT no es pot informar únicament els camps que volem modificar.

Per una operació PUT, el més senzill és recuperar les dades de la infraestructura amb una operació GET, que es troben al camp 'data' de la resposta rebuda. Amb aquestes dades ja tindreu la majoria d'IDs que us poden fer falta per l'operació PUT sobre la mateixa infraestructura.

Exemples per modificar infraestructures sense conèixer els IDs dels objectes

Suposem que volem fer una modificació sobre la infraestructura YLAP006669. Coneixent la marca i el número de sèrie podeu recuperar les seves dades.

La marca de l'equip és Fujitsu. A la API, a la secció marca es troba una operació que permet cercar una marca per nom:

GET /marca/cerca/nom/{nom}

Executem GET https://bus-soades.upc.edu/EquipsTIC/APIv1/marca/cerca/nom/fujitsu

Resposta:

{
"status": "success",
"data": [
    {
      "idMarca": 44,
      "nom": "FUJITSU"
    }
]
}

A la resposta podem veure com idMarca és 44 per 'FUJITSU'.

En cas de no estar segurs, sempre es pot emprar l'operació GET /marca per recuperar la llista de totes les marques i triar la que necessitem.

Ara, sabent el número de sèrie de ADRIATICA, YLAP006669, podem recuperar totes les seves dades amb l'operació sobre infraestructures

GET /infraestructura/cerca/marca/{idMarca}/sn/{sn}

Executem GET https://bus-soades.upc.edu/EquipsTIC/APIv1/infraestructura/cerca/marca/44/sn/YLAP006669

Resposta:

{
"status": "success",
"data": {
    "identificador": 6414,
    "capacitatTotalGb": null,
    "dataAltaManteniment": null,
    "dataBaixaManteniment": null,
    "dataCompra": "2014-02-15",
    "dataEntrega": null,
    "dataFinalGarantia": "2017-02-14",
    "dataTramitFactura": null,
    "discs": "2 x 2Tb",
    "edifici": {
      "idEdifici": 68
    },
    "importCompra": 0,
    "localitzacio": " SC2 - Centre de Càlcul",
    "model": "Primergy RX100",
    "modelCpu": "Intel Xeon CPU E31220 @ 3,10 Ghz",
    "nomDns": "YLAP006669",
    "numeroAd": null,
    "numeroCpus": 1,
    "numeroInventariUpc": null,
    "numeroPorts": null,
    "numeroSerie": "YLAP006669",
    "configuracioHardware": null,
    "observacions": null,
    "proveidorCompra": "0",
    "sla": null,
    "proveidorManteniment": "UPCnet",
    "dataCarrega": "2015-11-13 15:42:34",
    "estatValidacio": {
      "idEstat": 7
    },
    "estat": {
      "idEstat": 1
    },
    "marca": {
      "idMarca": 44
    },
    "ambit": null,
    "tipusInfraestructura": {
      "idTipus": 1
    },
    "tipusUs": null,
    "tipusXarxa": null,
    "unitatGestora": null,
    "unitatDestinataria": null,
    "unitat": {
      "idUnitat": 42
    },
    "dataCreacio": "2015-11-13",
    "dataDarreraModificacio": "2016-04-26",
    "usuari": {
      "idUsuari": 17
    },
    "usuariInfraestructura": null,
    "nomUsuariInfraestructura": null,
    "causaCanviWorkflow": null,
    "dataCanviWorkflow": null,
    "estatAnteriorWorkflow": null,
    "sistemaOperatiu": null
}
}

Suposem que volem canviar l'edifici on es troba aquesta infraestructura. El valor actual és idEdifici: 68, que correspon a l'EDIFICI SC2 (ETSAV).

Canviarem aquest edifici, per exemple, per l'edifici SC1. No coneixem encara quin ID correspon a aquest edifici, però sabem el seu codi, que entre altres llocs es troba a la plantilla d'importació d'EquipcTIC. També sabem el codi del Campus, de la mateixa plantilla, que és SC.

A la secció Edifici veiem que hi ha una operació que ens permet cercar per codi d'Edifici i codi de Campus:

GET /edifici/cerca/codi/{codi}/codicampus/{codiCampus}

Executem GET https://bus-soades.upc.edu/EquipsTIC/APIv1/edifici/cerca/codi/SC1/codicampus/SC

Resposta:

{
"success": "success",
"data": {
    "idEdifici": 67,
    "nom": "EDIFICI SC1 (ETSAV)",
    "codi": "SC1",
    "adreca": "C. PERE SERRA, 1-15",
    "ciutat": "SANT CUGAT DEL VALLÈS",
    "codi_postal": "08190",
    "campus": {
      "idCampus": 6,
      "nom": "CAMPUS SANT CUGAT DEL VALLÈS",
      "codi": "SC"
    }
}
}

De la resposta podem veure que el ID de l'edifici SC1 és el 67.

Podem aprofitar les dades de la comanda GET de la infraestructura per construir la comanda PUT. La part que ens interesa es troba

Executem PUT https://bus-soades.upc.edu/EquipsTIC/APIv1/infraestructura/6414

Amb aquest Body:

{
    "identificador": 6414,
    "capacitatTotalGb": null,
    "dataAltaManteniment": null,
    "dataBaixaManteniment": null,
    "dataCompra": "2014-02-15",
    "dataEntrega": null,
    "dataFinalGarantia": "2017-02-14",
    "dataTramitFactura": null,
    "discs": "2 x 2Tb",
    "edifici": {
      "idEdifici": 67
    },
    "importCompra": 0,
    "localitzacio": " SC2 - Centre de Càlcul",
    "model": "Primergy RX100",
    "modelCpu": "Intel Xeon CPU E31220 @ 3,10 Ghz",
    "nomDns": "YLAP006669",
    "numeroAd": null,
    "numeroCpus": 1,
    "numeroInventariUpc": null,
    "numeroPorts": null,
    "numeroSerie": "YLAP006669",
    "configuracioHardware": null,
    "observacions": null,
    "proveidorCompra": "0",
    "sla": null,
    "proveidorManteniment": "UPCnet",
    "dataCarrega": "2015-11-13 15:42:34",
    "estatValidacio": {
      "idEstat": 7
    },
    "estat": {
      "idEstat": 1
    },
    "marca": {
      "idMarca": 44
    },
    "ambit": null,
    "tipusInfraestructura": {
      "idTipus": 1
    },
    "tipusUs": null,
    "tipusXarxa": null,
    "unitatGestora": null,
    "unitatDestinataria": null,
    "unitat": {
      "idUnitat": 42
    },
    "dataCreacio": "2015-11-13",
    "dataDarreraModificacio": "2016-04-26",
    "usuari": {
      "idUsuari": 17
    },
    "usuariInfraestructura": null,
    "nomUsuariInfraestructura": null,
    "causaCanviWorkflow": null,
    "dataCanviWorkflow": null,
    "estatAnteriorWorkflow": null,
    "sistemaOperatiu": null
}

Resposta:

{
"status": "fail",
"message": "Ha d'informar un valor vàlid per al camp Propósit/Àmbit"
}

Sembla que aquesta infraestructura és antiga i no té informat el camp Propósit, que ara és un camp obligatori.

Suposem que volem informar el propòsit (abans àmbit) amb 'Lloc de treball compartit'. Segons la plantilla d'importació té el codi 'LT_COMP'

Podem veure a la pàgina de la API REST que hi ha una operació per cercar l'àmbit per codi:

GET /ambit/cerca/codi/{codi}

Executem GET https://bus-soades.upc.edu/EquipsTIC/APIv1/ambit/cerca/codi/SALA_TEC

Resposta:
{
"status": "success",
"data": [
    {
      "idAmbit": 51,
      "nom": "Sala tècnica",
      "codi": "SALA_TEC",
      "categoriaInfraestructura": {
        "idCategoria": 3,
        "nom": "Equip de treball",
        "codi": "EQUIP_TREBALL"
      }
    },
    {
      "idAmbit": 57,
      "nom": "Sala tècnica",
      "codi": "SALA_TEC",
      "categoriaInfraestructura": {
        "idCategoria": 2,
        "nom": "Equip de comunicació",
        "codi": "EQUIP_COMUNICACIO"
      }
    },
    {
      "idAmbit": 62,
      "nom": "Sala tècnica",
      "codi": "SALA_TEC",
      "categoriaInfraestructura": {
        "idCategoria": 1,
        "nom": "Equip de computació",
        "codi": "EQUIP_COMPUTACIO"
      }
    },
    {
      "idAmbit": 67,
      "nom": "Sala tècnica",
      "codi": "SALA_TEC",
      "categoriaInfraestructura": {
        "idCategoria": 4,
        "nom": "Dispositiu d'emmagatzemament",
        "codi": "DISPOSITIU_EMMAGATZEMAMENT"
      }
    }
]
}

Podem veure que hi ha vàries respostes, però per la categoria del nostre equip (EQUIP_COMPUTACIO) només hi ha 1 coincidència amb idAmbit: 62

Tornem a fer l'operació PUT, ara ja amb el camp obligatori 'àmbit' informat.

A efectes de simplificar d'aquest exemple, s'ha informat els camps 'Sistema operatiu' i 'Capacitat total GB', que també són obligatoris per aquest tipus de categoria.

Executem PUT https://bus-soades.upc.edu/EquipsTIC/APIv1/infraestructura/6414

{
    "identificador": 6414,
    "capacitatTotalGb": "2 Discs 1TB",
    "dataAltaManteniment": null,
    "dataBaixaManteniment": null,
    "dataCompra": "2014-02-15",
    "dataEntrega": null,
    "dataFinalGarantia": "2017-02-14",
    "dataTramitFactura": null,
    "discs": "2 x 2Tb",
    "edifici": {
      "idEdifici": 67
    },
    "importCompra": 0,
    "localitzacio": " SC2 - Centre de Càlcul",
    "model": "Primergy RX100",
    "modelCpu": "Intel Xeon CPU E31220 @ 3,10 Ghz",
    "nomDns": "YLAP006669",
    "numeroAd": null,
    "numeroCpus": 1,
    "numeroInventariUpc": null,
    "numeroPorts": null,
    "numeroSerie": "YLAP006669",
    "configuracioHardware": null,
    "observacions": null,
    "proveidorCompra": "0",
    "sla": null,
    "proveidorManteniment": "UPCnet",
    "dataCarrega": "2015-11-13 15:42:34",
    "estatValidacio": {
      "idEstat": 7
    },
    "estat": {
      "idEstat": 1
    },
    "marca": {
      "idMarca": 44
    },
    "ambit": {
        "idAmbit": 62
    },
    "tipusInfraestructura": {
      "idTipus": 1
    },
    "tipusUs": null,
    "tipusXarxa": null,
    "unitatGestora": null,
    "unitatDestinataria": null,
    "unitat": {
      "idUnitat": 42
    },
    "dataCreacio": "2015-11-13",
    "dataDarreraModificacio": "2016-04-26",
    "usuari": {
      "idUsuari": 17
    },
    "usuariInfraestructura": null,
    "nomUsuariInfraestructura": null,
    "causaCanviWorkflow": null,
    "dataCanviWorkflow": null,
    "estatAnteriorWorkflow": null,
    "sistemaOperatiu": {
        "idSistemaOperatiu": 2
    }
}

Resposta:

200 - OK

{
"status": "success",
"data": {
    "identificador": 6414,
    "capacitatTotalGb": "2 Discs 1TB",
    "dataAltaManteniment": null,
    "dataBaixaManteniment": null,
    "dataCompra": "2014-02-15",
    "dataEntrega": null,
    "dataFinalGarantia": "2017-02-14",
    "dataTramitFactura": null,
    "discs": "2 x 2Tb",
    "edifici": {
      "idEdifici": 67
    },
    "importCompra": 0,
    "localitzacio": " SC2 - Centre de Càlcul",
    "model": "Primergy RX100",
    "modelCpu": "Intel Xeon CPU E31220 @ 3,10 Ghz",
      "nomDns": "YLAP006669",
    "numeroAd": null,
    "numeroCpus": 1,
    "numeroInventariUpc": null,
    "numeroPorts": null,
    "numeroSerie": "YLAP006669",
    "configuracioHardware": null,
    "observacions": null,
    "proveidorCompra": "0",
    "sla": null,
    "proveidorManteniment": "UPCnet",
    "dataCarrega": "2015-11-13 15:42:34",
    "estatValidacio": {
      "idEstat": 7
    },
    "estat": {
      "idEstat": 1
    },
    "marca": {
      "idMarca": 44
    },
    "ambit": {
      "idAmbit": 62
    },
    "tipusInfraestructura": {
      "idTipus": 1
    },
    "tipusUs": null,
    "tipusXarxa": null,
    "unitatGestora": null,
    "unitatDestinataria": null,
    "unitat": {
      "idUnitat": 42
    },
        "dataCreacio": "2015-11-13",
    "dataDarreraModificacio": "2017-03-23",
    "usuari": {
      "idUsuari": 802
    },
    "usuariInfraestructura": null,
    "nomUsuariInfraestructura": null,
    "causaCanviWorkflow": null,
    "dataCanviWorkflow": null,
    "estatAnteriorWorkflow": null,
    "sistemaOperatiu": {
      "idSistemaOperatiu": 2
    }
}
}

A les dades de la resposta es poden veure com els valors ja estan canviats.

Per tant, si coneixeu els codis de les entitats que voleu modificar, mitjançant operacions a la API, es poden conèixer els seus IDs per tal de poder-los informar a les operacions POST o PUT.

equips tic infraestructures infraestructures tic servidors pc pcs equips