Web API

Über die LOGINventory Web API lassen sich mittels HTTP Requests Daten aus der LOGINventory-Datenbank abfragen und in die Datenbank schreiben. Diese Art der Schnittstelle ist für verschiedene Anwendungsszenarien geeignet, z.B. um einzelne Live-Daten mit einem anderen System direkt aus LOGINventory zu holen, um Massen-Exporte in Drittsysteme vorzunehmen, oder Daten aus anderen Systemen direkt in LOGINventory zu schreiben. Mögliche Szenarien werden unten genauer beschrieben.

Von der Web API gibt es dabei zwei verschiedene Varianten:

• die Allgemeine REST API (Allgemeine Web API) ermöglicht den Voll-Zugriff auf alle Daten aus LOGINventory. Wenn diese API aktiviert wurde, kann von einem Nutzer, der über die LOGINventory-Berechtigungsstufe Administrator verfügt, auf alle Daten zugegriffen werden, ohne dass dafür Endpunkte definiert werden müssen.
• über explizit anzulegende Web API Endpunkte kann genau definiert werden, welche Nutzer auf welche Daten lesend über den jeweiligen Endpunkt zugreifen dürfen. Damit kann der Zugriff z.B. auf bestimmte Geräte oder bestimmte Eigenschaften dieser Geräte beschränkt werden.

Voraussetzungen

Damit der Zugriff auf die Web API möglich ist, muss zunächst der Web Viewer veröffentlicht sein. Falls der Web Viewer bereits in einer Version veröffentlicht war, in der die Web API Funktionalität noch nicht enthalten war, kann ein erneutes Veröffentlichen des Web Viewers notwendig sein. Dies wird jedoch auch beim Aktivieren eines Web API Endpunkts geprüft.

Aktivieren der Allgemeinen Web API

Nur, wenn in den Anwendungsspezifischen Einstellungen der Haken zum Aktivieren der Allgemeinen Web API gesetzt wurde, ist ein Zugriff auf diese möglich. Der Haken ist standardmäßig nicht gesetzt.

Einrichtung von Web API Endpunkten

Nur Nutzer, die über die LOGINventory-Berechtigungsstufe Administrator verfügen, können Endpunkte anlegen oder bearbeiten.

Um den Zugriff über die Web API zu ermöglichen, muss ein Web API Endpunkt veröffentlicht werden.

Aktivieren eines Web API Endpunkts

Web API Endpunkte können auf allen Abfragen in der Baumstruktur positioniert werden. Die Ergebnismenge der Abfrage bestimmt dabei, welche Daten über den Endpunkt erreichbar sind.

Um den Endpunkt auf einer Abfrage einzurichten, kann über das Ribbon-Menü Knoten-Eigenschaften zum Reiter Web API navigiert werden.

In diesem Menü stehen dann die Optionen zur Verfügung, den Endpunkt zu aktivieren, einen eindeutigen Namen zu vergeben und optional einen Filter-Pfad zu spezifizieren.

Der vergebene Name findet sich dann auch in der Web API URL wieder, unter welcher die Daten abgerufen werden können. Die URL kann über einen entsprechenden Button in die Zwischenablage kopiert werden.

Definition der Datenstruktur

Wie bereits eingangs erwähnt, stehen über den Web API Endpunkt die Daten zur Verfügung, die in der Ergebnismenge der Abfrage enthalten sind. Das bedeutet, dass sowohl die Spalten-Auswahl der Abfrage, als auch im Abfrage-Editor definierte Filterbedingungen beachtet werden.

Wenn unterhalb der Abfrage, auf der der Endpunkt eingerichtet wurde, sich andere Abfragen befinden, dann sind die Ergebnismengen dieser Abfragen ebenso über den Endpunkt abrufbar. Auf diese Weise können also auch mehrere 1:n-Beziehungen zur Basistabelle der Abfrage über den Endpunkt abgerufen werden, also z.B. zu einem Gerät sowohl Geräte-Detail (1:1-Beziehung) als auch Informationen zu den dort vorhandenen Softwarepaketen (1:n-Beziehung) und den verbauten Arbeitsspeicher-Riegeln (1:n-Beziehung).

Übersicht der aktivierten Endpunkte

Alle aktivierten Endpunkte werden unterhalb des Knotens Web API Endpunkte aufgelistet. Von hier aus ist es auch möglich, die Endpunkte zu bearbeiten oder wieder zu deaktivieren, wenn kein Zugriff darüber mehr möglich sein soll.

Zugriff auf die Web API

Mittels HTTP Requests können von der allgemeinen Web API oder einem aktivierten Web API Endpunkt (nur GET-Requests) Daten abgerufen werden. Die Antwort im JSON-Format sieht z.B. wie folgt aus:

[
    {
        "DeviceInfo": {
            "ChassisType": "Rack Mount Chassis"
        },
        "LastInventory": {
            "Ip": "192.168.200.26",
            "Timestamp": "2022-06-02T10:56:28.763"
        },
        "Name": "DEKAN",
        "Software-Pakete": [
            {
                "Name": "HP Officejet Pro 8620 Basic Device Software",
                "Version": "32.3.198.49673"
            },
            {
                "Name": "HP Officejet Pro 8620 Help",
                "Version": "32.0.0"
            }
        ],
        "RAM-Module": [
            {
                "Name": "PROC 1 DIMM 2A",
                "SerialNumber": "61FF05E6",
                "Size": 16384,
                "Speed": "1333"
            },
            {
                "Name": "PROC 1 DIMM 1D",
                "SerialNumber": "CC176230",
                "Size": 2048,
                "Speed": "1333"
            }
        ]
    },
...

Test der Verbindung mittels Web Browser

Mittels eines Web-Browsers kann die entsprechende Endpunkt-URL auch aufgerufen werden, falls der verwendete Nutzer (bzw. der im Falle von Windows-Authentifizierung eingeloggte Nutzer) dazu autorisiert ist.

Authentifizierung

Mittels Standardauthentifizierung (Basic Authentication) - also Benutzername und Passwort - (Achtung: nur wenn vorher aktiviert!) oder integrierter Windows-Authentifizierung kann der Zugriff auf die Web API autorisiert werden. Der verwendete User muss auf der Abfrage in LOGINventory selbst berechtigt sein (= die Abfrage muss für den Nutzer freigegeben sein), damit die Daten abgerufen werden können.

Ein Nutzer, der nicht für einen Zugriff auf die entsprechende Abfrage berechtigt ist, kann keine Daten über den Endpunkt abrufen und erhält eine Fehlermeldung.

Um die Verbindung auch ohne Benutzername und Passwort zu erlauben, kann in den IIS-Einstellungen (Ausführen von inetmgr) die Anonyme Authentifizierung aktiviert werden.

Allgemeine Web API: Syntax und Beispiele

Um auf die Allgemeine Web API zuzugreifen wird eine URL wie http://my-loginventory-server/LOGINventory9/api/v1/ verwendet, wohingegen der Zugriff auf Endpunkte immer noch zusätzlich die Strings data/endpoint-name enthält, also z.B. http://my-loginventory-server/LOGINventory9/api/data/endpoint1.

Wie bei Abfragen, muss ein Request zur Allgemeinen Web API auch eine Basistabelle beinhalten. Häufig verwendete Basistabellen sind

• Device zur Abfrage von gescannten Geräten
• PeripheralDevice zur Abfragen von Peripherie-Geräten
• HardwareAsset zur Abfrage von sowohl Devices als auch PeripheralDevices (siehe Klassenhierarchie "HardwareAsset")
• User zur Abfrage von Daten zu Nutzern
• SoftwarePackage zur Abfragen von Daten zu Software-Paketen
• UserAccount zur Abfragen von Daten zu Nutzer-Konten laut Active Directory

Die Basistabelle wird an die URL angefügt.

Zusätzlich können

• nur bestimmte Einträge gewählt werden, indem deren ID mit einem / angefügt wird.
• Filterbedingungen hinzugefügt werden, indem als Parameter filter={BEDINGUNG} angefügt wird.
• nur bestimmte Eigenschaften gewählt werden, indem als Parameter select=EIGENSCHAFT(EN) angefügt wird.
• Pfade angegeben werden, falls es zwischen zwei Entitäten mehrere Pfade gibt, indem an die Navigation (Path=PFADNAME) angefügt wird.

Anwendungsszenarien

Massen-Export in andere Systeme

Um in einem Drittsystem (z.B. einer CMDB zur Modellierung von Abhängigkeiten zwischen den System) die Daten aus LOGINventory zu nutzen, stehen verschiedene Export-Mechanismen zur Verfügung. Gegenüber dem csv-Export bietet der Export via Web API Endpunkt die Möglichkeit auch mehrere 1:n-Beziehungen in einem Datensatz zu exportieren, sodass also zu einem Gerät z.B. auch die Daten zu allen installierten Software-Pakten, angeschlossenen Monitoren und Partitionsbelegungen abgefragt werden können. Weiterhin ist somit nicht nur ein Zeitplan-gesteuerter Push der Daten, sondern ein Pull der Daten möglich. Um einen solchen Export vorzubereiten kann z.B. wie folgt vorgegangen werden:

1. In LOGINventory wird eine neue Abfrage-Struktur definiert, die genau die Spalten enthält, die ins Drittsystem exportiert werden sollen. Wenn mehrere 1:n-Beziehungen zu einem Gerät exportiert werden sollen, werden entsprechende Abfragen unterhalb der ersten Abfrage erstellt (siehe Definition der Datenstruktur).
2. Auf der neuen Abfrage wird über die Knoten-Eigenschaften ein neuer Web API Endpunkt eingerichtet.
3. Das Drittsystem importiert die Daten regelmäßig mittels HTTP GET Request und aktualisiert so bei Bedarf den internen Datenbestand.

Live-Anbindung einzelner Datensätze

Um in einem Drittsystem (z.B. einem Helpdesk), das ebenfalls wie LOGINventory, Daten zu Computern anzeigt, weitere Informationen aus der Inventarisierung abzurufen eignet sich die Anbindung mittels HTTP Requests. Dazu bieten sich beide Varianten der Web API an:

Verwendung der Allgemeinen Web API

Über die Allgemeine Web API kann auf alle Datensätze zugegriffen werden, ohne dass vorher ein Endpunkt in LOGINventory definiert werden muss. So könnten z.B. zu einem Geräte-Namen weitere Eigenschaften, wie Modell, Seriennummer, Betriebssystem-Name, etc. abgerufen und in einem Drittsystem weiterverarbeitet werden.

Ebenso können Daten aus Drittsystem direkt nach LOGINventory geschrieben werden, z.B.

• wenn ein neues Gerät bestellt wurde, kann dieses direkt in LOGINventory angelegt und die Rechnung hinterlegt werden.
• wenn in einem Ticket-System ein Ticket erstellt / bearbeitet wird, können relevante Informationen zum Ticket in einem Lifecycle-Eintrag in LOGINventory hinterlegt werden.
• wenn der Status eines Geräts in einem anderen System aktualisiert wird, kann dieser direkt in eine Eigene Eigenschaft geschrieben werden.
• wenn ein Gerät in einem anderen System gelöscht oder archiviert wird, kann dies ebenso automatisch in LOGINventory geschehen.

Verwendung eines Web API Endpunkts

1. In LOGINventory wird eine neue Abfrage definiert, die genau die Spalten enthält, die im Drittsystem angezeigt werden sollen, z.B. Name des Geräts (Device.Name), Betriebssystem (OperatingSystem.Name), IP-Adresse (LastInventory.IP), Standort (Eigene Eigenschaft Custom.Standort) und Datum des letzten Boots (OperatingSystem.LastBoot). Eine Filterung in der Abfrage selbst ist nicht nötig.
2. Auf dieser Abfrage wird über die Knoten-Eigenschaften ein neuer Web API Endpunkt eingerichtet.
3. Im Helpdesk ist bereits der Name des betroffenen Geräts bekannt; die anderen Werte sollen dynamisch "live" aus LOGINventory abgefragt werden. Es sollen also nicht die Ergebnisse aller Geräte abgefragt werden, sondern nur jeweils die eines bestimmten Geräts. Dazu kann über den Filter Pattern Generator eine URL generiert werden, die exemplarisch auf ein bestimmtest Gerät filter (z.B. Device.Name = PC123). Die entstandene URL kann vom Drittsystem verwendet werden, um die Daten des Geräts "PC123" abzurufen.
4. Um die Daten eines anderen Geräts abzurufen muss in der URL der Text "PC123" durch den Namen des jeweiligen Geräts ersetzt werden.

Direkte Anbindung an andere Systeme

In Ihrem Unternehmen wird eine Software eingesetzt, die auf ähnliche Weise wir hier beschrieben angebunden werden soll? Kontaktieren Sie gerne die Hersteller der Software und stellen den Kontakt zu uns her. Wir sind gerne bereit, bei der Anbindung unterstützend zur Seite zu stehen.