Überblick

Die von Matrix42 Service Management (ESM) bereitgestellte REST API ermöglicht die Integration beliebiger externer Anwendungen in die Matrix42 Lösung. Die REST API folgt REST Prinzipien und -Bestimmungen, um den Zugriff auf die Daten in ESM zu gewährleisten. Sämtliche System- und Datenmodell-Verwaltungsfunktionen sind von der REST API -Schnittstelle ausgeschlossen.

So starten Sie

REST API kann in jeder Matrix42 Umgebung aktiviert werden, sofern das Matrix42 Service Management Tool (ESM) auf Version 2021.4 oder höher aktualisiert ist. Die Aktivierung erfolgt durch Anforderung einer REST API Lizenz für die jeweilige Umgebung bei Matrix42 . Die Lizenz aktiviert das externe API Modul von Matrix42 im System. Zusätzlich benötigt das System einen technischen (lokalen) Benutzer und eine definierte Rolle für die Zugriffsverwaltung.

Zugang zur Umwelt

Alle Endpunkte der REST API sind in Cloud-Umgebungen über [base_url]/rest-api/itsm/:versionCode (z. B. https://your Matrix42 environment.m42cloud.com/rest-api/itsm/v1/) und [base_url]/itsm/api/:versionCode erreichbar.
Bitte beachten Sie, dass die REST API in lokalen Installationen (Windows-Installation + MS SQL -Datenbank) nicht unterstützt wird. Sie können den Zugriff auf die Swagger Dokumentation der REST API ganz einfach mit Ihrem Browser testen: Swagger UI erreichen Sie unter [base_url]/rest-api/itsm/v1/docs/swagger/index.html (z. B. https://your Matrix42 environment.m42cloud.com/rest-api/itsm/v1/docs/swagger/index.html).

Lizenz

Die Umgebung benötigt eine REST API Lizenz. Sobald die Lizenz vorhanden ist und ESM neu gestartet wurde, kann der Administrator in der Administratoransicht unter „Systemstatus – Systemstatus und Laufzeitinformationen“ überprüfen, ob die externe Matrix42 API als eines der aktivierten Module aufgeführt ist.

Protokollierung

Die REST API Aufrufe werden in einer Datei namens „integration.log“ protokolliert, die über die ESM-Administrationsansicht zugänglich ist. Das Protokoll enthält alle Operationen, die an der REST API durchgeführt wurden.
ESM protokolliert die Statistiken außerdem in einer separaten Protokolldatei namens „ Matrix42 “, die auch über die ESM-Admin-Ansicht verfügbar ist.

2023-04-11 20:34:00,635|Usage,consumed,1000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-12 04:54:00,643|Usage,consumed,2000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-12 13:30:00,743|Usage,consumed,3000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-12 21:50:00,573|Usage,consumed,4000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-13 06:10:00,548|Usage,consumed,5000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-13 14:30:00,606|Usage,consumed,6000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-13 22:50:00,882|Usage,consumed,7000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-14 07:10:00,737|Usage,consumed,8000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-14 15:30:01,055|Usage,consumed,9000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-14 23:50:00,690|Usage,consumed,10000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-17 00:00:00,144|Usage,consumed,15779,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-17 00:00:00,145|Statistics reset

Der obige Ausschnitt ist ein Beispiel für die Datei „rest_api_usage.log“. Das Protokoll enthält wöchentliche Statistiken zu erfolgreichen und fehlgeschlagenen REST API Aufrufen mit einer Zusammenfassung am Ende der Woche. Diese erfolgreichen Aufrufe werden auch als REST API Transaktionen bezeichnet.

Benutzer

Zur Authentifizierung von Anfragen über die REST API benötigt Matrix42 Service Management Tool ein lokales Benutzerkonto (d. h. kein EIM-Konto, das in der Cloud-Umgebung für Anmeldungen verwendet wird). Es empfiehlt sich, für jede Integration über die REST API einen neuen Benutzer anzulegen. Zusätzlich muss eine Rolle mit Berechtigungen zur Nutzung der externen API erstellt und dem lokalen Benutzer zugewiesen werden.
Die Erstellung eines gültigen Kontos kann mit folgenden Schritten erfolgen:

1. Rolle erstellen und Berechtigung Matrix42 External API -Modul auswählen.
2. Füge der Rolle Ordnerberechtigungen hinzu.
3. Fügen Sie der Rolle Vorlagenberechtigungen hinzu.
4. REST - API Benutzer erstellen.
5. Füge den Benutzer einer zuvor erstellten Rolle hinzu.
6. Testen Sie, ob Sie ein JWT-Token vom Login-Endpunkt erhalten können.

Authentifizierung

REST - API verwendet JWT-Bearer-Token zur Authentifizierung, die über einen dedizierten Anmelde-Endpunkt bezogen werden können. Nach der Erstellung ist das Token für einen vordefinierten Zeitraum gültig, der in der ESM-Plattformeinstellung `security.external.api.token.expiration.time` konfiguriert werden kann – die Standardgültigkeitsdauer beträgt 15 Minuten. Diese Token sind nicht blockierend, d. h. ein Konto kann beliebig viele Token generieren.

Zum Abrufen des JWT-Tokens kann eine POST- Anfrage verwendet werden:

https://instance. Matrix42 cloud.com/rest-api/itsm/v1/users/login

Benutzername und Passwort müssen im Anfragetext enthalten sein. Sind Benutzername und Passwort gültig, antwortet der Server mit einem JWT-Token in den Headern.

Seit ESM Version 2022.3.0.2 wird das Token auch im Nachrichtentext zurückgegeben:
{
"code": 200,
"message": "Token issued.",
"timestamp": "2022-10-13T10:14:15Z",
"token": "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJURVNUX1JFU1RBUEkiLCJpc3MiOiJodHRwczovL2VzbXBvci5lZmVjdGVjbG91ZC1kZXYuY29tL2l0c20vYXBpL3YxL3VzZXJzL2xvZ2luIiwiaWF0IjoxNjY1NjU2MDU1LCJleHAiOjE2NjU2NTY5NTV9.aO2Td-62f2QYNszZhc9rbM-MOs_zhZvnRuJXK28CLIApmj_p6O0oL7Dy623QsRZwR3AWrajzQ96uKYgFxzxvwg"
}

Bei nachfolgenden Anfragen an andere Endpunkte muss das Token im Authorization-Header (im ähnlichen Format wie das zurückgegebene Token) zur Autorisierung angegeben werden. Beispielsweise könnte das Abrufen aller Vorfälle (bei Verwendung von curl) wie folgt aussehen:

GET "https:// Matrix42 cloud.com/rest-api/itsm/v1/dc/incident/data" -H "accept: application/json" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUcnlpbmcgdG8gZGVjb2RlIG91ciB0b2tlbnM_IiwiaWF0IjoxNjM4MzcyODM1LCJleHAiOjE2Njk5MDg4MzUsImF1ZCI6Ind3dy5leGFtcGxlLmNvbSIsInN1YiI6IlRoYXQncyBnb29kLCB5b3Ugc2hvdWxkIGFsd2F5cyB0aGluayBhYm91dCBzZWN1cml0eS4ifQ.zzdHvo6VvqN08-YCtylWQCQjcKI7L9TCgHWplOgnNXY

Werkzeuge

Swagger

Swagger , ein Tool zur Interaktion mit der API und zum Anzeigen der Dokumentation, ist in jeder Umgebung mit einer gültigen REST - API Lizenz enthalten. Swagger Benutzeroberfläche kann über base_url/rest-api/itsm/v1/docs/swagger/index.html aufgerufen werden (z. B. Matrix42 ).
Swagger generiert eine Dokumentation auf Basis der Open API 3.0-Spezifikation, die auch über die Benutzeroberfläche (base_url/rest-api/itsm/v1/docs/openapi.json) heruntergeladen und in verschiedene Integrations- und Testwerkzeuge importiert werden kann.

Einstellungen

Die folgenden Einstellungen der REST API können im Matrix42 Service Management Tool angepasst werden. Bitte beachten Sie, dass diese Einstellungen sicherstellen, dass Integrationen die Systemleistung nicht beeinträchtigen. Es wird nicht empfohlen, die Werte zu erhöhen, da dies zu unnötiger Systemlast führen kann.