In diesem Artikel möchte ich dir kurz und knapp die Verwendung der REST-API der Enterprise Service Management (ESM) Lösung von Matrix42 vorstellen. Hierbei geht es darum, Informationen zu einem Asset anhand der Seriennummer über die Public API abzufragen.
Die Abfrage erfolgt in zwei Stufen: Als Erstes müssen wir uns gegenüber der API authentifizieren. Zur Authentifizierung nutzen wir in diesem Beispiel einen Bearer-Token, welchen du dir über das Webinterface generieren kannst.
Nachdem wir uns authentifiziert haben, bekommen wir einen RawToken, welchen wir für weitere API Aufrufe verwenden können. Dabei ist jedoch zu berücksichtigen, dass jeder RawToken auch einen Gültigkeits-Timeout besitzt.
1. Das PowerShell-Skript – Authentifizierung
Als Erstes werden wir uns nun im PowerShell-Skript um die Authentifizierung gegenüber der API kümmern. Wir haben übrigens auch einen interessanten Artikel, wie du PS-Arrays in Matrix42 Workflows verwenden kannst.
Du kannst an dieser Stelle einfach das folgende Skript verwenden und die beiden Variablen $apiToken und $baseUrl mit deinen Daten befüllen. Um die Erstellung des Web Service Tokens zur Befüllung der Variable $apiToken kümmern wir uns im nächsten Abschnitt.
$apiToken = "<Web Service Token>"
$baseUrl = "https://<server>"
### Get Token
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Authorization", "Bearer $apiToken")
$tokenResponse = Invoke-RestMethod "$baseUrl/M42Services/api/ApiToken/GenerateAccessTokenFromApiToken/" -Method 'POST' -Headers $headers -Body $body
Code-Sprache: PHP (php)2. Web Service Token erstellen
Hierbei ist zunächst wichtig zu verstehen, dass der Token für eine bestimmte Person im ESM erstellt wird. Der Token besitzt damit die Berechtigungen, welche für die Person über Mitgliedschaften in Benutzerrollen vergeben wurden. Es ist an dieser Stelle empfehlenswert spezielle API-User mit minimalen Berechtigungen im System je Anwendungsfall zu erstellen.
Den Token kannst du in der Navigation unter “Integration/Web Service Tokens” (App Administration) erstellen:
Im Dialog musst du schließlich noch einen Namen, eine Gültigkeit und die Person angeben:
Nun kannst du den Token kopieren:
3. Das Powershell-Skript – Authentifizierung prüfen
Da wir nun den Token erstellt haben, kannst du diesen ins Skript einfügen und das Ganze ausführen.
Die Variable $tokenResponse.RawToken beinhaltet nun den RawToken, welchen wir für die späteren Aufrufe benötigen. Die Variable $tokenResponse.LifeTime beinhaltet zusätzlich die Gültigkeit des RawTokens. Nach Ablauf dieser Zeit muss ein neuer RawToken über den gezeigten API Aufruf gezogen werden.
4. Das PowerShell-Skript – Abfrage der Assetdaten
Bei Problemen mit doppelten Assets im Asset-Management schau mal hier.
Die Voraussetzungen sind nun geschaffen. Damit können wir uns nun der Abfrage der Assetdaten zuwenden. Hierzu musst du dein Skript um folgenden Code erweitern:
### Get AssetData
$serial = "<Serial des Assets>"
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Authorization", "Bearer "+$tokenResponse.RawToken)
$headers.Add("Content-Type", "application/json")
$response = Invoke-WebRequest "$baseUrl/m42Services/api/data/fragments/SPSAssetClassBase/schema-info?where=SerialNumber='$serial'&columns=ID,Name,SerialNumber,InventoryNumber,sku.T(SPSStockKeepingUnitClassBase).Model AS Model" -Method 'GET' -Headers $headers
$assetObj = ($response.Content | ConvertFrom-Json).Result
$assetObj.ModelCode-Sprache: PHP (php)Vergiss nicht, deine gesuchte Seriennummer in der Variable $serial zu hinterlegen. Zusätzlich siehst du im Header “Authorization”, dass hier die Variable $tokenResponse.RawToken verwendet wird, um den Aufruf zu authentifizieren.
Sobald du das Skript ausgeführt hast, findest du in der Variablen $assetObj die Informationen zu deinem Asset. In diesem Fall haben wir in der Request-URL über das Attribut “columns”, eine kommaseparierte Liste der zu liefernden Attribute angegeben. Dabei musst du beachten, dass bei Verwendung des T-Operators ein Alias mit dem Stichwortes “AS” angegeben werden muss. In unserem Beispiel haben wir so das Modell des Assets abgefragt.
Er stellt die Grundlage bereit, um eine Kommunikation zwischen verschiedenen Drittsystemen und der Matrix42 ESM-Plattform zu ermöglichen.
