Yleiskatsaus

Matrix42 Service Management -työkalun (ESM) tarjoama REST API mahdollistaa minkä tahansa ulkoisen sovelluksen integroinnin Matrix42-ratkaisuun. REST API noudattaa RESTful-rajoitteita ja -periaatteita, jotta pääsy ESM:n dataan on mahdollista. Kaikki järjestelmän ja tietomallin ylläpitotoiminnot on jätetty REST API -rajapinnan ulkopuolelle.

Näin pääset alkuun

REST API voidaan ottaa käyttöön missä tahansa Matrix42-ympäristössä, jossa Matrix42 Service Management -työkalu (ESM) on päivitetty versioon 2021.4 tai uudempaan. Käyttöönotto tapahtuu pyytämällä Matrix42:lta REST API -lisenssi ympäristöä varten. Lisenssi ottaa järjestelmässä käyttöön Matrix42 External API -moduulin. Järjestelmässä tulee lisäksi olla tekninen (paikallinen) käyttäjä ja käyttöoikeuksien hallintaa varten määritetty rooli.

Ympäristöön pääseminen

Kaikkiin REST API:iin liittyviin päätepisteisiin pääsee osoitteesta [base_url]/rest-api/itsm/:versionCode (esim. https://yourMatrix42environment.m42cloud.com/rest-api/itsm/v1/) pilviympäristöissä ja [base_url]/itsm/api/:versionCode
Huomaa, ettei REST API:a tueta on-prem-käyttöönotoissa (Windows-asennus + MSSQL-tietokanta). Voit helposti testata pääsyä REST API:n Swagger-dokumentaatioon selaimella: Swagger UI löytyy osoitteesta [base_url]/rest-api/itsm/v1/docs/swagger/index.html (esim. https://yourMatrix42environment.m42cloud.com/rest-api/itsm/v1/docs/swagger/index.html).

Lisenssi

Ympäristöllä täytyy olla REST API -lisenssi. Kun lisenssi on käytössä ja ESM on käynnistetty uudelleen, ylläpitäjä voi tarkistaa, että Admin-näkymän System status – System status and runtime information -kohdassa listataan Matrix42 External API yhtenä käytössä olevista moduuleista.

Lokitus

REST API -kutsut kirjataan tiedostoon nimeltä ”integration.log”, joka on saatavilla ESM:n admin-näkymän kautta. Loki sisältää kaikki REST API:a vastaan tehdyt toiminnot.
ESM kirjaa myös tilastot erilliseen lokitiedostoon nimeltä ”Matrix42_rest_rest_api_usage.log”, joka on niin ikään saatavilla ESM:n admin-näkymän kautta.

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

Yllä oleva ote on esimerkki ”rest_api_usage.log”-tiedostosta. Loki antaa viikoittaisia tilastoja onnistuneista ja epäonnistuneista REST API -kutsuista, ja jakson lopussa on yhteenveto. Näitä onnistuneita kutsuja kutsutaan myös nimellä REST API -transaktiot.

Käyttäjät

Jotta REST API:n kautta tehtävät pyynnöt voidaan todentaa, Matrix42 Service Management -työkalussa tulee olla paikallinen käyttäjätili (eli ei EIM-tili, jota käytetään pilviympäristön kirjautumisiin). Hyvä käytäntö on luoda uusi käyttäjä jokaiselle REST API:a käyttävälle integraatiolle. Sinun tulee myös luoda rooli, jolla on oikeudet käyttää External API:a, ja liittää tämä rooli paikalliselle käyttäjälle.
Toimivan tilin luominen onnistuu seuraavilla vaiheilla:

1. Luo rooli ja valitse Matrix42 External API -moduulin käyttöoikeus.
2. Lisää roolille kansio-oikeudet.
3. Lisää roolille mallioikeudet.
4. Luo REST-API-käyttäjä.
5. Lisää käyttäjä aiemmin luotuun rooliin.
6. Testaa, että saat JWT-tokenin login-päätepisteestä.

Todennus

REST-API käyttää todennukseen JWT Bearer -tokeneita, jotka saadaan erillisestä login-päätepisteestä. Kun token on luotu, se on voimassa ennalta määritetyn ajan, jota voidaan säätää ESM:n alustan asetuksessa security.external.api.token.expiration.time – oletusarvoinen voimassaoloaika on 15 minuuttia. Nämä tokenit eivät ole rajoittavia (non-blocking), eli yksi tili voi luoda niin monta tokenia kuin tarvitaan.

POST-pyyntöä voidaan käyttää JWT-tokenin hakemiseen:

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

Käyttäjätunnus ja salasana täytyy sisällyttää pyynnön runkoon. Jos käyttäjätunnus ja salasana ovat oikein, palvelin vastaa JWT-tokenilla otsikoissa (headers).

ESM-versiosta 2022.3.0.2 alkaen token palautetaan myös rungossa:
{
"code": 200,
"message": "Token issued.",
"timestamp": "2022-10-13T10:14:15Z",
"token": "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJURVNUX1JFU1RBUEkiLCJpc3MiOiJodHRwczovL2VzbXBvci5lZmVjdGVjbG91ZC1kZXYuY29tL2l0c20vYXBpL3YxL3VzZXJzL2xvZ2luIiwiaWF0IjoxNjY1NjU2MDU1LCJleHAiOjE2NjU2NTY5NTV9.aO2Td-62f2QYNszZhc9rbM-MOs_zhZvnRuJXK28CLIApmj_p6O0oL7Dy623QsRZwR3AWrajzQ96uKYgFxzxvwg"
}

Myöhemmissä pyynnöissä muihin päätepisteisiin token täytyy sisällyttää Authorization-otsikkoon (samassa muodossa kuin se palautettiin) valtuutusta varten. Esimerkiksi kaikkien incidenttien hakeminen voisi näyttää tältä (curl-komennolla):

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

Työkalut

Swagger

Swagger, työkalu API:n kanssa toimimiseen ja dokumentaation tarkasteluun, sisältyy jokaiseen ympäristöön, jolla on voimassa oleva REST-API-lisenssi. Swagger UI löytyy osoitteesta base_url/rest-api/itsm/v1/docs/swagger/index.html (esim. https://Matrix42cloud.com/rest-api/itsm/v1/docs/swagger/index.html).
Swagger luo dokumentaation OpenAPI 3.0 -spesifikaation pohjalta, ja sen voi myös ladata käyttöliittymästä (base_url/rest-api/itsm/v1/docs/openapi.json) ja tuoda erilaisiin integraatio- ja testaustyökaluihin.

Asetukset

Seuraavia REST API:iin liittyviä asetuksia voidaan säätää Matrix42 Service Management -työkalussa. Huomaa, että asetuksilla varmistetaan, etteivät integraatiot vaikuta negatiivisesti järjestelmän suorituskykyyn. Asetusten arvojen kasvattamista ei suositella, sillä se saattaa antaa integraatioille mahdollisuuden aiheuttaa tarpeetonta kuormaa.