Yleiskatsaus

Matrix42 Service Management -työkalun (ESM) tarjoama REST API mahdollistaa minkä tahansa ulkoisen sovelluksen integroinnin Matrix42 ratkaisuun. REST API noudattaa REST täydellisiä rajoituksia ja periaatteita mahdollistaakseen pääsyn ESM:ssä oleviin tietoihin. Kaikki järjestelmän ja tietomallin hallintatoiminnot on suljettu pois REST API rajapinnasta.

Aloittaminen

REST API voidaan ottaa käyttöön missä tahansa Matrix42 ympäristössä, jossa on Matrix42 Service Management -työkalu (ESM) päivitettynä versioon 2021.4 tai uudempaan. Käyttöönotto tehdään pyytämällä Matrix42 lta REST API -lisenssi kyseiseen ympäristöön. Lisenssi ottaa käyttöön Matrix42 External API -moduulin järjestelmässä. Järjestelmässä on myös oltava tekninen (paikallinen) käyttäjä ja rooli määriteltynä käyttöoikeuksien hallintaa varten.

Ympäristön käyttö

Kaikkiin REST API liittyviin päätepisteisiin pääsee pilviympäristöissä osoitteesta [base_url]/rest-api/itsm/:versionCode (esim. https:// Matrix42 environment.m42cloud.com/rest-api/itsm/v1/) ja [base_url]/itsm/api/:versionCode.
Huomaa, että REST API ei tueta paikallisissa asennuksissa (Windows-asennus + MS SQL -tietokanta). Voit helposti testata REST API Swagger -dokumentaation käyttöä selaimellasi: Swagger -käyttöliittymään pääsee osoitteesta [base_url]/rest-api/itsm/v1/docs/swagger/index.html (esim. https:// Matrix42 environment.m42cloud.com/rest-api/itsm/v1/docs/swagger/index.html).

Lisenssi

Ympäristöllä on oltava REST API -lisenssi. Kun lisenssi on asennettu ja ESM on käynnistetty uudelleen, ylläpitäjä voi tarkistaa, että Järjestelmän tila – Järjestelmän tila ja suorituksenaikaiset tiedot -kohdassa ylläpitäjän näkymässä Matrix42 External API on listattu yhtenä käytössä olevista moduuleista.

Lokitiedostot

REST API -kutsujen lokitiedostoon nimeltä ”integration.log” on saatavilla ESM:n hallintanäkymässä. Loki sisältää kaikki REST API vastaan tehdyt toiminnot.
ESM kirjaa tilastot myös erilliseen lokitiedostoon nimeltä ” Matrix42 _rest_rest_api_usage.log”, joka on myös saatavilla ESM:n hallintanä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 koodinpätkä on esimerkki tiedostosta ”rest_api_usage.log”. Loki antaa viikoittaiset tilastot onnistuneista ja epäonnistuneista REST API -kutsuista sekä yhteenvedon viikoittaisen jakson lopussa. Näitä onnistuneita kutsuja kutsutaan myös REST API -tapahtumiksi .

Käyttäjät

Jotta Matrix42 Service Management -työkalu voi todentaa pyyntöjä REST API kautta, sillä on oltava paikallinen käyttäjätili (eli ei EIM-tili, jota käytetään pilviympäristössä kirjautumiseen). Hyvä käytäntö on luoda uusi käyttäjä jokaiselle REST API avulla tapahtuvalle integraatiolle. Sinun on myös luotava rooli, jolla on oikeudet käyttää ulkoista API , ja annettava tämä rooli paikalliselle käyttäjälle.
Kelvollisen tilin luominen onnistuu seuraavilla vaiheilla:

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

Todennus

REST - API käyttää todennukseen JWT Bearer -tokeneja, jotka voidaan hankkia erillisestä kirjautumispisteestä. Kun token on luotu, se on voimassa ennalta määritetyn ajan, joka voidaan konfiguroida ESM-alustan asetuksissa security.external.api.token.expiration.time – oletusarvoinen vanhenemisaika on 15 minuuttia. Nämä tokenit ovat ei-estäviä, eli yksi tili voi luoda niin monta tokenia kuin on tarpeen.

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

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

Käyttäjätunnuksen ja salasanan on oltava pyynnön rungossa. Jos käyttäjätunnus ja salasana ovat kelvollisia, palvelin vastaa lisäämällä JWT-tokenin otsikoihin.

ESM-versiosta 2022.3.0.2 lähtien 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"
}

Seuraavissa pyynnöissä muihin päätepisteisiin token on sisällytettävä Authorization-header-kenttään (samanlaisessa muodossa kuin se palautetaan) valtuutusta varten. Esimerkiksi kaikkien tapausten hakeminen voisi näyttää tältä (jos käytetään curlia):

GET "https:// Matrix42 cloud.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 kanssa vuorovaikutukseen ja dokumentaation tarkasteluun, sisältyy kaikkiin ympäristöihin, joilla on voimassa oleva REST - API lisenssi. Swagger käyttöliittymään pääsee osoitteesta base_url/rest-api/itsm/v1/docs/swagger/index.html (esim. Matrix42 ).
Swagger luo dokumentaatiota Open API 3.0 -spesifikaation pohjalta. Dokumentaation voi 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 in liittyviä asetuksia voidaan muuttaa Matrix42 Service Management Toolissa. Huomaa, että asetuksia käytetään varmistamaan, etteivät integraatiot vaikuta negatiivisesti järjestelmän suorituskykyyn. Asetusten arvojen nostamista ei suositella, koska se voi aiheuttaa integraatioiden tarpeetonta kuormitusta.