Seite wählen

NETWAYS Blog

Ansible can talk to your favorite API

Ansible is a powerful opensource config management and deployment tool, which can manage nearly any situtation. In many „DevOp“ scenarios we come across multiple platforms, which we need to combine. Mostly applications provide an REST Api or web connectors to manage resources, jobs and deployments within the product.
Ansible provides various modules which can execute commands at specific APIs, such as the vmware-guest-module to create virtual machines or the jenkins-job-module to manage jobs over the Jenkins API.
In cases where no module is available, we can use the module „uri“.

The module takes several parameters, of which the „url“ is the only required one. For this example I picked an example online API „http://dummy.restapiexample.com/“.
To get a list of all employees we use the method GET on , the header Accept: application/json and register the content.


- name: Make requests to example api
  hosts: localhost
  connection: local
  tasks:
    - name: list employees
      uri:
        method: GET
        url: "http://dummy.restapiexample.com/api/v1/employees"
        return_content: yes
        headers:
          Accept: application/json
      register: response

    - debug:
        msg: "{{ response.content }}"

# Result
TASK [list employees] *************************************************************************
ok: [localhost]

TASK [debug] **********************************************************************************
ok: [localhost] => {
    "msg": [
        {
            "employee_age": "23",
            "employee_name": "test",
            "employee_salary": "46000",
            "id": "12008",
            "profile_image": ""
        }
    ]
}

Now we create a new user in our application, for this we talk to a different url and send a body with our user to create.
When the api accepts JSON I use a little trick to generate a valid json body out of yaml variables with the Ansible filter to_json

For this we create a variable with the same key value structure as the API expects it, in this case the structure looks like this {„name“:“test“,“salary“:“123″,“age“:“23″}.


- name: Make requests to example api
  hosts: localhost
  connection: local
  vars:
    data:
      chris:
        name: chris
        salary: 46000
        age: 27
      jessy:
        name: jessy
        salary: 70000
        age: 30
  tasks:
    - name: create employee
      uri:
        method: POST
        url: "http://dummy.restapiexample.com/api/v1/create"
        return_content: yes
        headers:
          Accept: application/json
        body_format: json
        body: "{{ item.value | to_json }}" //Render valid json from each dictionary in the variable data.
      with_dict: "{{ data }}"
      register: post_content

    - debug:
        msg: "{{ item.content }}"
      with_items: "{{ post_content.results }}"

# Result
ansible-playbook create_user.yaml

PLAY [Make requests to example api] ********************************************************************

TASK [Gathering Facts] *********************************************************************************
ok: [localhost]

TASK [create employee] *********************************************************************************
ok: [localhost] => (item={'value': {u'salary': 46000, u'age': 27, u'name': u'chris'}, 'key': u'chris'})
ok: [localhost] => (item={'value': {u'salary': 70000, u'age': 30, u'name': u'jessy'}, 'key': u'jessy'})

With this information given, you can now explore your own favorite API and hopefully reduce your daily tasks as simple Ansible playbooks.

Check out our Blog for more awesome posts and if you need help with Ansible send us a message!

Thilo Wening
Thilo Wening
Manager Consulting

Thilo hat bei NETWAYS mit der Ausbildung zum Fachinformatiker, Schwerpunkt Systemadministration begonnen und unterstützt nun nach erfolgreich bestandener Prüfung tatkräftig die Kollegen im Consulting. In seiner Freizeit ist er athletisch in der Senkrechten unterwegs und stählt seine Muskeln beim Bouldern. Als richtiger Profi macht er das natürlich am liebsten in der Natur und geht nur noch in Ausnahmefällen in die Kletterhalle.

i-doit API create, update, delete

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.

i-doit API

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


GUI REST clients

Mittlerweile sind HTTP REST APIs aus der täglichen Arbeit in der IT nicht mehr wegzudenken. Noch vor Jahren durchaus als exotisch zu bezeichnen, ohne Dokumentation und chaotisch verwoben, entstehen immer mehr gute APIs die sich an entsprechende Standards halten und sinnvolle Funktion bieten. Angefangen von atmosphärischen Zufallszahlen, randomisierten Bildern  oder Kartendecks ist mittlerweile alles aus Microservices zu holen – man denke nur an die 125726 Google APIs. Übrigens bieten wir mit Icinga 2 oder Icinga Web 2 standardisierte APIs für die Monitoring-Umgebung an und ein nicht geringer Anteil unserer Routine besteht mit der Arbeit dieser APIs.
Um effektiv mit den Schnittstellen arbeiten zu können muss man sich diese etwas genauer anschauen. Am besten geht das mit entsprechenden Tools und einer Handvoll guter Features, z.B.:

  • Repetitive Anfragen
  • Absteigende URLs
  • Header, Parameter, Request Body, Cookies
  • Authentifizierung
  • Organisation (Sammlungen, Request-Historie)
  • Binary Daten
  • Pretty Print der Rückgaben

Ich bin mittlerweile unter macOS bei zwei Tools hängengeblieben die gerne einmal zeigen möchte: CocoaRestClient und Postman. Beide Tools besitzen oben genannte Features. Postman gibt es sogar als Chrome App. Bei Verwendung von Chrome und debugging von JavaScript kommt also gleich alles aus einem Guss ;-). Postman ist insgesamt mehr Feature-Complete und die native Cocoa macOS App unglaublich fix. Und natürlich hat auch Curl seine Berechtigung – wenn auch kein GUI!
Es folgt noch eine kleine Photostrecke. Dann ist die eigene Meinung gefragt…


 

Marius Hein
Marius Hein
Head of IT Service Management

Marius Hein ist schon seit 2003 bei NETWAYS. Er hat hier seine Ausbildung zum Fachinformatiker absolviert und viele Jahre in der Softwareentwicklung gearbeitet. Mittlerweile ist er Herr über die interne IT und als Leiter von ITSM zuständig für die technische Schnittmenge der Abteilungen der NETWAYS Gruppe. Wenn er nicht gerade IPv6 IPSec Tunnel bohrt, sitzt er daheim am Schlagzeug und treibt seine Nachbarn in den Wahnsinn.

Einführung zu CouchDB

Bei CouchDB handelt es sich um ein in Erlang geschriebenes dokumentenbasiertes DBMS, das durch sein Design einige interessante Features anbietet.
Die meisten Linux-Distributionen bieten bereits vorgefertigte Pakete an. Unter Ubuntu kann CouchDB z.B. wie folgt installiert werden:
$ sudo apt-get install couchdb
Für den Zugriff auf CouchDB-Datenbanken sind keine speziellen Client-Anwendungen notwendig. Da CouchDB eine HTTP-basierte REST-Schnittstelle anbietet, kann nahezu jeder beliebige HTTP-Client (z.B. curl) verwendet werden, um auf die Daten zuzugreifen.
CouchDB bietet dennoch von Haus aus eine einfache Oberfläche zum Administrieren und Bearbeiten von Datenbanken an. Standardmäßig ist dieses unter http://localhost:5984/_utils/ erreichbar.
Im Gegensatz zu relationalen Datenbanksystemen ist es bei CouchDB nach dem Anlegen einer Datenbank nicht notwendig, ein Datenbankschema in Form von Tabellen zu definieren.
Stattdessen werden JSON-formatierte Dokumente direkt in der Datenbank abgelegt. Jedes Dokument verfügt dabei zunächst nur über zwei Felder:

  • _id: ein eindeutiger Bezeichner für das jeweilige Dokument; wird er vom Benutzer nicht mit angegeben, vergibt CouchDB automatisch eine einzigartige ID
  • _rev: die Revisionsnummer des Dokuments; sie wird bei jedem Update hochgezählt und intern von CouchDB zur Lösung von Konflikten verwendet

Weitere Felder können nach Bedarf beliebig hinzugefügt werden. Dabei ist es möglich, dass mehrere Dokumente unterschiedliche Felder enthalten.
Ein Zugriff auf die Dokumente ist über das _id-Feld möglich. Um über andere Felder nach Dokumenten zu suchen, müssen Views definiert werden. Diese bestehen aus JavaScript-Funktionen, die Dokumente bestimmten Schlüsseln zuordnet.
Um beispielsweise bei einem Blog alle Posts finden zu können, die an einem Donnerstag veröffentlicht wurden, könnte man eine View definieren, die den einzelnen Wochentagen jeweils die entsprechenden Blog-Posts zuordnet. Über die optionale Integration von Apache Lucene ist es auch möglich, Volltextsuchen durchzuführen.
Views werden beim Bearbeiten von Dokumenten aktualisiert und verwenden intern einen binären Baum, um eine ähnliche Performance anzubieten wie Indizes bei relationalen Datenbanksystemen.
Mehr Informationen zu CouchDB-Features wie z.B. Replikation, Dokumenten-Validierung und etlichen weiteren gibt es auf der offiziellen Webseite unter http://couchdb.apache.org/ und im online verfügbaren Buch „CouchDB: The Definitive Guide
“ unter http://guide.couchdb.org/.