NETWAYS Blog

Wie in meinem letzten Blogpost angekündigt, werde ich anhand eines Beispiels zeigen, wie man mittels der i-doit-API Daten erstellen, aktualisieren und löschen kann.
Ein großer Vorteil den man durch das Benutzen der i-doit-API hat, ist der, dass man nicht “wie üblich” mit SQL-Statements interne Verarbeitungsschritte innerhalb der Datenbank umgeht. Dadurch kann es nicht passieren, dass man durch z.B. einem UPDATE-Statement einen Datensatz so verändert, dass dieser fehlerhaft wird. Somit ist die Datenintegrität mit der API gewährleistet.
Zunächst sucht man sich das Objekt aus der CMDB heraus welches man verändern will (im folgenden Beispiel das Modell eines bestehenden Servers):

curl -s --data '{ "jsonrpc":"2.0","id":"1","method":"cmdb.category.read", \
"params":{ "apikey":"random_key","objID":"random_objectid","category":"C__CATG__MODEL"}}' \
--header "Content-Type: application/json"  \
| python -m json.tool

Man erhält durch diese Anfrage folgende Antwort:

{
    "id": "1",
    "jsonrpc": "2.0",
    "result": []
}

Wie man sieht ist das result null. D.h. dieser Server/Objekt besitzt keinen Eintrag zu einem Modell bzw. Hersteller. Somit kann man nun ein neues Modell hinzufügen.
Zu beachten ist, dass im Voraus schon Modelle bzw. Hersteller in der CMDB angelegt wurden!

Die zu benutzende Methode ist cmdb.category.create:

curl -s --data '{ "jsonrpc":"2.0","id":"1","method":"cmdb.category.create", \
"params":{ "apikey":"random_key","objID":"random_objectid","category":"C__CATG__MODEL",\
"data":{ "manufacturer": "random_manufacturer","title":"random_modelname","serial":"1234"}}}' \
--header "Content-Type: application/json"  \
| python -m json.tool

Sollte alles funktioniert haben, bekommt man folgenden Response zurück:

{
  "jsonrpc": "2.0",
  "result": {
    "id": "855",
    "message": "Category entry successfully created.",
    "success": true
  },
  "id": "1"
}

Hat man z.B. die Seriennummer falsch eingetragen und möchte diese verändern, kann man dies mit der Methode update durchführen.
cmdb.category.update

curl -s --data '{ "jsonrpc":"2.0","id":"1","method":"cmdb.category.update", \
"params":{ "apikey":"random_key","objID":"random_objectid","category":"C__CATG__MODEL",\
"data":{ "serial":"4321"}}' --header "Content-Type: application/json"  \
| python -m json.tool

Im Anschluss kann man überprüfen ob alle eingetragenen Daten stimmen, indem man wieder den Server ausliest (oberes Beispiel cmdb.category.read):

{
  "jsonrpc": "2.0",
  "result": [{
    "id": "855",
    "objID": "random_objectid",
    "manufacturer": {
      "id": "13",
      "title": "random_manufacturer",
      "const": null,
      "title_lang": "random_manufacturer"
    },
    "title": {
      "id": "3",
      "title": "random_modelname",
      "const": null,
      "title_lang": "random_modelname"
    },
    "productid": "",
    "service_tag": "",
    "serial": "4321",
    "firmware": "",
    "description": ""
  }],
  "id": "1"
}

Zum Schluss löschen wir den Server komplett mittels der Methode quickpurge (quickpurge muss in i-doit aktiviert sein!)
cmdb.category.quickpurge:

curl -s --data '{ "jsonrpc":"2.0","id":"1","method":"cmdb.category.quickpurge", \
"params":{ "apikey":"random_key","id":"random_objectid","\
--header "Content-Type: application/json"  \
| python -m json.tool

{
  "jsonrpc": "2.0",
  "result": {
    "message": "Object(s) successfully purged",
    "success": true
  },
  "id": "1"
}

Quickpurge ist eine Methode bei denen die drei Löschschritte (archivieren, löschen, purge) automatisch hintereinander ausgeführt werden. Ansonsten müsste man der Methode cmdb.object.delete die verschiedenen Status in folgender Reihenfolge mitschicken:

{
  ...
  "status": "C__RECORD_STATUS__ARCHIVED"
  ...
}
{
  ...
  "status": "C__RECORD_STATUS__DELETED"
  ...
}
{
  ...
  "status": "C__RECORD_STATUS__PURGE"
  ...
}

Im nächsten Teil der Serien zeige ich wie man mit einem Ruby-Script all diese Schritte automatisiert durchführen kann.

Als IT-Dienstleister bieten wir nicht nur Web Services oder Schulungen, sondern unter anderem auch Hosting an. Im Hosting-Bereich ist eine umfassende und geordnete IT-Dokumentation zwingend erforderlich um ein reibungsloses Arbeiten zu ermöglichen.  Als Lösung wird eine sog. CMDB (Configuration Management Database) eingesetzt, welche nicht nur als eine Inventarisierungs-Datenbank dient, sondern auch die gegenseitigen Abhängigkeiten der Objekte verwaltet. I-doit ist eine solche CMDB.
Seit der i-doit Version 1.8 ist die API kein Bestandteil der Pro-Version mehr und wird als separates Modul ausgeliefert welches frei verfügbar ist. Infolge dessen hab ich ein Azubiprojekt bekommen bei dem man die Funktionsweise einer API kennenlernen kann. Ich zeige im ersten Teil der i-doit API Serie wie man einen Request  über den curl – Befehl versendet.

Hat man die API über die Web GUI von i-doit konfiguriert kann man über folgende URL, welche an die Basis-URL angehängt wird, zugreifen:

/src/jsonrpc.php

Die Programmierschnittstelle kann auf Daten der CMDB über das JSON-Format zugreifen, d.h. es werden JSON-RPC Requests per HTTP-Post an i-doit geschickt und als JSON-RPC Response (mit HTTP-Header application/json) zurückgegeben. Somit kann man entweder über den curl – Befehl oder über einen RESTClient (z.B. als Firefox-Addon) die API ansprechen.
Ein beispielhafter Aufbau eines Request könnte folgendermaßen aussehen :

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "cmdb.objects.read",
  "params": {
    "apikey": "random_key",
    "filter": {
      "type": "4"
    }
  }
}

• jsonrpc – version: Da i-doit ausschließlich die Version 2.0 des RPC-Request untersützt
• id: Ein optionaler skalarer Wert (True, False, String, Numer) welcher aber nicht Null sein darf. Lässt man diesen Parameter aus, so wird lediglich eine Mitteilung verschickt, sodass der Server keine Rückmeldung generiert
• method: Die zu aufrufende Methode
• params: Parameter welche an die Methode übergeben werden

curl -s --data '{"jsonrpc":"2.0","id":"1","method":"cmdb.objects.read","params": \
{"apikey":"random_key","filter":{"type":"4"}}}' \
--header "Content-Type: application/json" \
 | python -m json.tool

Mit diesem Request lesen wir alle Objekte in der CMDB aus welche dem Typ 4 (Rack) entsprechen:

{
  "id": "1",
  "jsonrpc": "2.0",
  "result": [{
    "cmdb_status": "6",
    "cmdb_status_title": "in operation",
    "created": "2018-01-05 11:32:13",
    "id": "33",
    "image": "https://example-idoit-web-gui.de/images/objecttypes/something.png",
    "status": "2",
    "sysid": "SYSID_[RANDOMNUMBER_3849274329]",
    "title": "RacknameXYZ",
    "type": "4",
    "type_group_title": "Infrastructure",
    "type_title": "Rack",
    "updated": "2018-01-11 13:38:09"
  },
  {
    ...
    ...
  }]
}

Um z.B. alle Informationen einer Kategorie eines Objektes auslesen zu können, benutzt man die Methode cmdb.category.read:

curl -s --data '{"jsonrpc":"2.0","id":"1","method":"cmdb.category.read","params": \
{"apikey":"random_key","objID":"1234","category":"C__CATG__MODEL"}' \
--header "Content-Type: application/json" \
 | python -m json.tool

Response:

{
  "id": "1",
  "jsonrpc": "2.0",
  "result": [{
    "description": "",
    "firmware": "",
    "id": "307",
    "manufacturer": {
      "const": null,
      "id": "5",
      "title": "Random_Manufacturer_Name",
      "title_lang": "Random_Manufacturer_Name"
    },
  "objID": "Uniqe-Object-ID",
  "productid": "",
  "serial": "1235265477457",
  "service_tag": "",
  "title": {
    "const": null,
    "id": "71",
    "title": "XYZ1234",
    "title_lang": "XYZ1234"
  }
  }]
}

Eine ausführliche Liste aller in i-doit benutzten Kategorien kann man unter folgendem URL-Anhang aufrufen:

Darüber hinaus kann man über die i-doit API nicht nur Daten aus einer CMDB herauslesen, sondern auch erstellen, aktualisieren oder löschen. Diese Methoden werde ich im Teil 2 dieser Serie abhandeln.
 
Quellen: i-doit Knowledge Base