Översikt

REST API som tillhandahålls av Matrix42 Service Management Tool (ESM) möjliggör integration av alla externa applikationer med Matrix42 -lösningen. REST API följer REST fulla begränsningar och principer för att möjliggöra åtkomst till data i ESM. Alla administrativa funktioner för system och datamodeller är exkluderade från REST API gränssnittet.

Hur man kommer igång

REST API kan aktiveras i vilken Matrix42 miljö som helst med Matrix42 Service Management Tool (ESM) uppdaterat till version 2021.4 eller senare. Aktiveringen görs genom att begära en REST API licens för miljön från Matrix42 . Licensen aktiverar Matrix42 External API modulen i systemet. Systemet måste också ha en teknisk (lokal) användare och en roll definierad för åtkomsthantering.

Åtkomst till miljön

Alla slutpunkter relaterade till REST API kan nås från [base_url]/rest-api/itsm/:versionCode (t.ex. https://your Matrix42 environment.m42cloud.com/rest-api/itsm/v1/) i molnmiljöer och [base_url]/itsm/api/:versionCode
Observera att REST API inte stöds i lokala distributioner (Windows-installation + MS SQL databas). Du kan enkelt testa åtkomst till REST API Swagger -dokumentationen med din webbläsare: Swagger UI kan nås från [base_url]/rest-api/itsm/v1/docs/swagger/index.html (t.ex. https://your Matrix42 environment.m42cloud.com/rest-api/itsm/v1/docs/swagger/index.html).

Licens

Miljön behöver en REST API licens. När licensen är på plats och ESM har startats om kan administratören kontrollera att Systemstatus – Systemstatus och körtidsinformation i administratörsvyn listar Matrix42 External API som en av de aktiverade modulerna.

Skogsavverkning

REST API anropen loggas till en fil som heter "integration.log" och är tillgänglig via ESM-administratörsvyn. Loggen innehåller alla åtgärder som utförts mot REST API .
ESM loggar även statistiken i en separat loggfil som heter " Matrix42 _rest_rest_api_usage.log", som också är tillgänglig via ESM-administratörsvyn.

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

Ovanstående utdrag är ett exempel på filen "rest_api_usage.log". Loggen ger statistik på veckobasis för lyckade och misslyckade REST API anrop med en sammanfattning i slutet av veckoperioden. Dessa lyckade anrop kallas även REST API -transaktioner .

Användare

För att autentisera förfrågningar via REST API :et behöver Matrix42 Service Management-verktyget ha ett lokalt användarkonto (dvs. inte ett EIM-konto som används i molnmiljön för inloggningar). En bra idé är att skapa en ny användare för varje integration med hjälp av REST API . Du måste också skapa en roll som har behörighet att använda externt API och ge denna roll till den lokala användaren.
Att skapa ett giltigt konto kan göras med följande steg:

1. Skapa roll och välj Matrix42 External API -modulbehörighet.
2. Lägg till mappbehörigheter till rollen.
3. Lägg till mallbehörigheter till rollen.
4. Skapa REST - API användare.
5. Lägg till användare till en tidigare skapad roll.
6. Testa att du kan hämta JWT-token från inloggningsslutpunkten.

Autentisering

REST - API använder JWT Bearer-tokens för autentisering, vilka kan hämtas från en dedikerad inloggningsslutpunkt. När token har skapats är den giltig under en fördefinierad tidsperiod som kan konfigureras i ESM-plattformsinställningen security.external.api.token.expiration.time – standardutgångstiden är 15 minuter. Dessa tokens är icke-blockerande, vilket innebär att ett konto kan generera så många tokens som behövs.

En POST- förfrågan kan användas för att hämta JWT-token:

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

Inloggningsnamn och lösenord måste inkluderas i begäran. Om användarnamn och lösenord är giltiga svarar servern med en JWT-token i rubrikerna.

Sedan ESM version 2022.3.0.2 returneras token även i brödtexten:
{
"code": 200,
"message": "Token issued.",
"timestamp": "2022-10-13T10:14:15Z",
"token": "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJURVNUX1JFU1RBUEkiLCJpc3MiOiJodHRwczovL2VzbXBvci5lZmVjdGVjbG91ZC1kZXYuY29tL2l0c20vYXBpL3YxL3VzZXJzL2xvZ2luIiwiaWF0IjoxNjY1NjU2MDU1LCJleHAiOjE2NjU2NTY5NTV9.aO2Td-62f2QYNszZhc9rbM-MOs_zhZvnRuJXK28CLIApmj_p6O0oL7Dy623QsRZwR3AWrajzQ96uKYgFxzxvwg"
}

I efterföljande förfrågningar till andra slutpunkter måste token inkluderas i Authorization-header (liknande format som den returneras) för auktorisering. Till exempel kan det se ut så här att hämta alla incidenter (om man använder curl):

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

Verktyg

Swagger

Swagger , ett verktyg för att interagera med API och visa dokumentationen, ingår i alla miljöer som har en giltig REST - API licens. Swagger UI kan nås från base_url/rest-api/itsm/v1/docs/swagger/index.html (t.ex. https:// Matrix42 cloud.com/rest-api/itsm/v1/docs/swagger/index.html).
Swagger genererar dokumentation baserad på Open API 3.0-specifikationen, vilken också kan laddas ner från användargränssnittet (base_url/rest-api/itsm/v1/docs/openapi.json) och importeras till olika integrations- och testverktyg.

Inställningar

Följande inställningar relaterade till REST API kan justeras i Matrix42 Service Management Tool. Observera att inställningarna används för att säkerställa att integrationer inte påverkar systemets prestanda negativt. Det rekommenderas inte att öka inställningsvärdena, eftersom det kan leda till onödig belastning på integrationer.