Przegląd

Interfejs REST API udostępniany przez narzędzie Matrix42 Service Management (ESM) umożliwia integrację dowolnej aplikacji zewnętrznej z rozwiązaniem Matrix42 . Interfejs REST API spełnia ograniczenia i zasady REST , aby umożliwić dostęp do danych w ESM. Wszystkie funkcje administracyjne systemu i modelu danych są wyłączone z interfejsu REST API .

Jak zacząć

REST API można włączyć w dowolnym środowisku Matrix42 za pomocą narzędzia Matrix42 Service Management (ESM) zaktualizowanego do wersji 2021.4 lub nowszej. Włączenie odbywa się poprzez złożenie wniosku o licencję REST API dla danego środowiska w Matrix42 . Licencja umożliwia włączenie modułu Matrix42 External API w systemie. System musi również posiadać użytkownika technicznego (lokalnego) oraz zdefiniowaną rolę do celów zarządzania dostępem.

Dostęp do środowiska

Do wszystkich punktów końcowych powiązanych z REST API można uzyskać dostęp z adresu [base_url]/rest-api/itsm/:versionCode (np. https://your Matrix42 environment.m42cloud.com/rest-api/itsm/v1/) w środowiskach chmurowych oraz [base_url]/itsm/api/:versionCode
Należy pamiętać, że REST API nie jest obsługiwany we wdrożeniach lokalnych (instalacja systemu Windows + baza danych MS SQL ). Dostęp do dokumentacji interfejsu REST API Swagger można łatwo przetestować w przeglądarce: dostęp do interfejsu użytkownika Swagger można uzyskać pod adresem [base_url]/rest-api/itsm/v1/docs/swagger/index.html (np. https://your Matrix42 environment.m42cloud.com/rest-api/itsm/v1/docs/swagger/index.html).

Licencja

Środowisko musi posiadać licencję REST API . Po zainstalowaniu licencji i ponownym uruchomieniu ESM, administrator może sprawdzić, czy w widoku administratora w sekcji „Status systemu – Informacje o statusie systemu i środowisku wykonawczym ” znajduje się Matrix42 External API jako jeden z włączonych modułów.

Wycięcie lasu

Wywołania interfejsu REST API będą rejestrowane w pliku o nazwie „integration.log”, dostępnym w widoku administracyjnym ESM. Dziennik zawiera wszystkie operacje wykonane w interfejsie REST API .
ESM rejestruje również statystyki w oddzielnym pliku dziennika o nazwie „ Matrix42 _rest_rest_api_usage.log”, dostępnym również w widoku administratora ESM.

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

Powyższy fragment kodu to przykład pliku „rest_api_usage.log”. Dziennik zawiera tygodniowe statystyki udanych i nieudanych wywołań REST API wraz z podsumowaniem na koniec każdego tygodnia. Te udane wywołania nazywane są również transakcjami REST API .

Użytkownicy

Aby uwierzytelnić żądania za pośrednictwem REST API , narzędzie Matrix42 Service Management wymaga lokalnego konta użytkownika (tj. nie konta EIM używanego w środowisku chmurowym do logowania). Dobrą praktyką jest tworzenie nowego użytkownika dla każdej integracji za pomocą REST API . Należy również utworzyć rolę z uprawnieniami do korzystania z zewnętrznego API i nadać ją użytkownikowi lokalnemu.
Aby utworzyć prawidłowe konto, należy wykonać następujące kroki:

1. Utwórz rolę i wybierz uprawnienie Matrix42 External API -module.
2. Dodaj uprawnienia folderu do roli.
3. Dodaj uprawnienia szablonu do roli.
4. Utwórz użytkownika REST - API .
5. Dodaj użytkownika do wcześniej utworzonej roli.
6. Przetestuj, czy możesz uzyskać token JWT z punktu końcowego logowania.

Uwierzytelnianie

REST – API wykorzystuje tokeny JWT Bearer do uwierzytelniania, które można uzyskać z dedykowanego punktu logowania. Po utworzeniu token jest ważny przez predefiniowany okres, który można skonfigurować w ustawieniach platformy ESM: security.external.api.token.expiration.time – domyślny czas wygaśnięcia to 15 minut. Tokeny te nie są blokowane, co oznacza, że jedno konto może wygenerować dowolną liczbę tokenów.

Do pozyskania tokena JWT można użyć żądania POST :

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

Login i hasło muszą być zawarte w treści żądania. Jeśli nazwa użytkownika i hasło są prawidłowe, serwer odpowiada tokenem JWT w nagłówkach.

Od wersji ESM 2022.3.0.2 token jest zwracany również w treści:
{
"code": 200,
"message": "Token issued.",
"timestamp": "2022-10-13T10:14:15Z",
"token": "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJURVNUX1JFU1RBUEkiLCJpc3MiOiJodHRwczovL2VzbXBvci5lZmVjdGVjbG91ZC1kZXYuY29tL2l0c20vYXBpL3YxL3VzZXJzL2xvZ2luIiwiaWF0IjoxNjY1NjU2MDU1LCJleHAiOjE2NjU2NTY5NTV9.aO2Td-62f2QYNszZhc9rbM-MOs_zhZvnRuJXK28CLIApmj_p6O0oL7Dy623QsRZwR3AWrajzQ96uKYgFxzxvwg"
}

W kolejnych żądaniach do innych punktów końcowych token musi zostać dołączony do nagłówka Authorization-header (w formacie podobnym do zwracanego) w celu autoryzacji. Na przykład, pobranie wszystkich incydentów mogłoby wyglądać następująco (przy użyciu 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

Narzędzia

Swagger

Swagger , narzędzie do interakcji z API i przeglądania dokumentacji, jest zawarte w każdym środowisku z ważną licencją REST API . Dostęp do interfejsu użytkownika Swagger można uzyskać pod adresem base_url/rest-api/itsm/v1/docs/swagger/index.html (np. https:// Matrix42 cloud.com/rest-api/itsm/v1/docs/swagger/index.html).
Swagger generuje dokumentację opartą na specyfikacji Open API 3.0, którą można również pobrać z interfejsu użytkownika (base_url/rest-api/itsm/v1/docs/openapi.json) i zaimportować do różnych narzędzi integracyjnych i testowych.

Ustawienia

Poniższe ustawienia związane z REST API można dostosować w narzędziu Matrix42 Service Management Tool. Należy pamiętać, że ustawienia te mają na celu zapewnienie, że integracje nie będą negatywnie wpływać na wydajność systemu. Nie zaleca się zwiększania wartości ustawień, ponieważ może to spowodować niepotrzebne obciążenie integracji.