Printer icon

Korzystanie z interfejsu nAxiom PublicAPI

(Wersja nAxiom 1.15.2.0*)

Przeczytasz w 17 min.

Spis treści

  1. Wprowadzenie
  2. Dokumentacja PublicAPI
  3. Konfiguracja klienta auth
  4. Konfiguracja profilu użytkownika
  5. Uzyskiwanie tokenu
  6. Przykłady żądań do PublicAPI
    1. [POST]/Document/CreateWithAttachments
    2. [GET]/PermissionDelegation/Get
    3. [GET]/Document/Get
    4. [POST]/Document/Save
    5. [POST]/Attachment/UploadAttachment
  7. Błędy braku uprawnień
  8. Znane problemy

Wprowadzenie

Na potrzeby integracji z systemami zewnętrznymi platforma nAxiom udostępnia interfejs PublicAPI z kilkudziesięcioma endpointami obsługującymi szereg operacji w zakresie pobierania, dodawania i aktualizowania danych przetwarzanych w witrynie nAxiom. Opis tych endpointów zawiera dokumentacja generowana automatycznie przez program Swagger, dostępna pod adresem witryny naxiom w katalogu publicapi ({adres_URL_witryny_naxiom}/publicapi/).
W tym artykule podano podstawowe informacje dotyczące korzystania z interfejsu PublicAPI za pomocą programu Postman i polecenia curl.

Serwis Public API można także wykorzystać do komunikacji między tenantami w środowisku multi tenant. W tym celu definiuje się akcje zapytań do webservice oparte na specjalnym typie źródła danych: Tenant w środowisku nAxiom . Takie źródło danych wykorzystuje mechanizm automatycznego uwierzytelniania oparty na tokenach TOTP. Przykład takiej akcji opisano w Leksykonie nAxiom

Dokumentacja PublicAPI

Dokumentacja interfejsu PublicAPI witryny nAxiom jest dostępna pod adresem witryny w katalogu publicapi. Na przykład:

https://naxiom.mysite.com/publicapi/

Bez końcowego ukośnika w adresie zostanie wyświetlona strona błędu 404.

Dokumentacja PublicApi wygenerowana przez narzędzie Swagger
Dokumentacja PublicApi wygenerowana przez narzędzie Swagger

Konfiguracja klienta auth

Do uzyskania tokenu z serwisu auth można także użyć predefiniowanego klienta openjs, jednak nie można wprowadzać żadnych zmian w jego konfiguracji, ponieważ jest on używany m.in. przez wtyczki nAxiom do programów Outlook i Word.

Aby użytkownik mógł uzyskać token potrzebny do uwierzytelniania żądań do PublicAPI, wymagane jest skonfigurowanie klienta w pliku appsettings.json serwisu auth. W tym celu, w sekcji Clients tego pliku należy dodać wpis:

{
  "ClientId": "publicApiClient",
  "ClientName": "PublicAPI Client",
  "AllowedGrantTypes": "ResourceOwnerPassword",
  "SecretKeySha256": "secret",
  "AllowAccessTokensViaBrowser": true,
  "RequireConsent": false,
  "AlwaysIncludeUserClaimsInIdToken": true,
  "AllowedScopes": [
    "public-api"
  ]
}

Jeśli żądanie /connect/token będzie wysyłane bez pośrednictwa przeglądarki (Postman, curl), parametr AllowAccessTokensViaBrowser może mieć wartość false.

Jeśli zachodzi konieczność dodatkowego zabezpieczenia klienta używanego do uzyskania tokenu, można użyć parametru RequireClientSecret z wartością true. W takim przypadku w pliku appsettings-protected.json należy dodać wpis z zaszyfrowanym hasłem klienta:

  "AppConfiguration": {
    "Secrets": {
      ...,
      "Client-publicApiClient": "DVqipgOwCBz9D3JSi9nd9qJGiWzuhI1VZ6+wPH5Hn6sT+lCGONMismjywy/sHWxI"
    }
  }

Informacje dotyczące szyfrowania hasła można uzyskać u producenta nAxiom.

Taka konfiguracja spowoduje, że w żądaniu tokenu konieczne będzie podanie hasła klienta jako wartości klucza client_secret.

Po zmianie pliku appsettings.json konieczne jest ponowne uruchomienie witryny w programie Menedżer IIS lub w oprogramowaniu do zarządzania implementacją kontenerową (Kubernetes, OpenShift, Docker Desktop).

Konfiguracja profilu użytkownika

Użytkownik, który będzie zdalnie logował się do witryny nAxiom i następnie wysyłał żądania API musi mieć w swoim profilu w nAxiom włączony przełącznik Dostęp do Public API.

Profil użytkownika w nAxiom
Profil użytkownika w nAxiom

Dodatkowo, korzystanie z endpointów /User/Save, /User/AddNewUser oraz endpointów w węzłach /PermissionDelegation i /Permission wymaga, aby użytkownik miał przypisaną predefiniowaną rolę biznesową Administrator użytkowników PublicAPI.

Rola administratora użytkowników PublicAPI
Rola administratora użytkowników PublicAPI

nAxiom zezwoli na administrowanie profilami użytkowników pod warunkiem, że dany użytkownik będzie miał przypisaną rolę biznesową o kodzie USER_ADMIN_PUBLICAPI. To oznacza, że nazwę predefiniowanej roli i jej przypisanie do aplikacji można zmienić.

Edycja roli administratora użytkowników PublicAPI
Edycja roli administratora użytkowników PublicAPI

Podczas wykonywania żądań do PublicAPI sprawdzane są także odpowiednie uprawnienia użytkowników w nAxiom: uprawnienia ACL w przypadku operacji na dokumentach oraz uprawnienia PBA, np. do edycji profili użytkowników. Brak odpowiednich uprawnień będzie skutkował odmową wykonania żądania z błędem HTTP 403.

Uzyskiwanie tokenu

Do autoryzowania żądań wysyłanych do PublicAPI konieczny jest token przypisywany podczas logowania użytkownika. Aby go uzyskać, należy wysłać do serwisu auth danej witryny nAxiom żądanie {url}/connect/token. Konfiguracja żądania jest następująca:

  • Typ żądania: POST
  • Sekcja Body, parametry typu x-www-from-urlencoded:
    • grant_type: password
    • username: nazwa użytkownika
    • password: hasło użytkownika
    • scope: public-api
    • client_secret: hasło klienta używanego do wysłania żądania; hasło jest wymagane tylko wtedy, gdy w konfiguracji klienta włączono atrybut RequireClientSecret.
    • client_id: identyfikator klienta zgodny z deklaracją w pliku appsettings.json serwisu auth; w tym przypadku publicApiClient

W programie Postman żądanie i odpowiedź mogą wyglądać jak na ilustracji poniżej.

Uzyskiwanie tokena w programie Postman
Uzyskiwanie tokena w programie Postman

Żądanie można także wysłać, korzystając z polecenia curl.

W przypadku witryny nAxiom na hoście z certyfikatem samopodpisanym polecenie curl wymaga użycia parametru -k w celu wyłączenia sprawdzania certyfikatu.

curl -k --location 'https://localhost:1414/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=admin' \
--data-urlencode 'password=password' \
--data-urlencode 'scope=public-api' \
--data-urlencode 'client_secret=secret' \
--data-urlencode 'client_id=publicApiClient'

Uzyskaną w odpowiedzi wartość parametru access_token należy używać w żądaniach wysyłanych do PublicAPI.

Postman:

  • W definicji żądania na karcie Authorization rozwiń listę Type i wybierz wartość Bearer Token.
  • Wklej wartość tokena w polu Token

curl:

  • Użyj wartości tokenu w parametrze --header jak w przykładzie poniżej: 
    curl -k --location 'https://localhost:1414/publicapi/...' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjUyMkM2MzE2REU5...'

    Czas ważności tokenu wynosi 3600 s.

Przykłady żądań do PublicAPI

[POST]/Document/CreateWithAttachments

Pozwala utworzyć dokument i zapisać załączniki do tego dokumentu. W przypadku błędu podczas przetwarzania jednego z załączników, cała operacja zostanie wycofana i dokument nie zostanie utworzony.

Parametry żądania:

  • documentDefinitionId (GUID): identyfikator (RowGuid) definicji dokumentu; parametr wymagany,
  • batchId (GUID): opcjonalny identyfikator operacji wsadowej na potrzeby audytu; jeśli nie zostanie podany, zostanie wygenerowany nowy identyfikator GUID,
  • skipWorkflowActions (boolean): flaga określająca, czy podczas tworzenia dokumentu mają być wykonywane akcje workflow; wartość domyślna false.

W sekcji body (obowiązkowej) należy podać dane dokumentu oraz załączników. Załączniki są przesyłane w formacie Base64 i zapisywane w podanej kategorii, lub w kategorii domyślnej, gdy nie zostanie podana. Rozmiar pliku i dozwolone rozszerzenia są sprawdzane zgodnie z ustawieniami kategorii.

Przykład żądania:

 curl --location 'https://localhost:1150/publicapi/Document/CreateWithAttachments?documentDefinitionId=631...&skipWorkflowActions=true' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSU...' \
--data-raw '{ "Model": { "Id": 0, "EmailKlienta": "user@example.com", "TekstReklamacji": "nic nie działa" }, "Attachments": [ { "Base64Content": "iVBORw0KGgoAAAANSUhEU...", "FileName": "screenshot.png", "Description": "Zrzut ekranu", "AttachmentCategoryId": "8347fb47-fabe-49a7-9c24-c185a7fe0dff" } ] }'

[GET]/PermissionDelegation/Get

Ten endpoint zwraca dane zastępstwa o podanym identyfikatorze. Odpowiedź zawiera pełne dane z profili użytkowników zastępowanego i zastępującego. Żądanie i fragment odpowiedzi przedstawiono na ilustracji.

Endpoint /PermisionDelegation/Get
Endpoint /PermisionDelegation/Get

curl:

curl -k --location 'https://localhost:1414/publicapi/PermissionDelegation/Get?id=10' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI...'

[GET]/Document/Get

Endpoint zwraca dane instancji dokumentu dla podanej definicji dokumentu. Wymaga podania identyfikatorów definicji dokumentu i instancji dokumentu.

Endpoint /Document/Get
Endpoint /Document/Get

curl:

curl - k --location \
--request GET 'https://localhost:1414/publicapi/Document/Get?documentDefinitionId=26&recordId=37' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6...' \
--data '"string"'

[POST]/Document/Save

Endpoint dodaje nowy dokument lub aktualizuje istniejący. Wymaga podania następujących parametrów:

  • documentDefinitionId: identyfikator definicji dokumentu.
  • recordId: identyfikator zmienianej instancji dokumentu lub 0 w przypadku dodawania nowego dokumentu.

  • skipWorkflowActionsForNewRecord: flaga pomijania akcji wykonywanych podczas tworzenia nowego dokumentu; domyślnie false.

    Endpoint /Document/Save - parametry
    Endpoint /Document/Save - parametry

W żądaniu należy określić nagłówki jak na ilustracji poniżej.

Endpoint /Document/Save - nagłówki
Endpoint /Document/Save - nagłówki

W sekcji body żądania można określić wartości pól dokumentu w formacie JSON jak na ilustracji poniżej.

Endpoint /Document/Save - body
Endpoint /Document/Save - body

W przypadku pomyślnego dodania nowego dokumentu w odpowiedzi zwracany jest jego identyfikator.

curl:

curl -k --location 'https://localhost:1414/publicapi/Document/Save?documentDefinitionId=19&
recordId=0&skipWorkflowActionsForNewRecord=false' \
--header 'Accept: text/plain' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImt...' \
--data '{
    "Marka": "Syrena",
    "Model": "105 de Luxe",
    "RokProdukcji": "1964"
}'

[POST]/Attachment/UploadAttachment

Dodaje załącznik do wskazanej kategorii załączników określonego dokumentu. W zależności od wartości parametru overwrite nadpisuje istniejący plik lub dodaje nową wersję. Wymaga podania następujących parametrów:

  • recordId: identyfikator zmienianej instancji dokumentu lub 0 w przypadku dodawania nowego dokumentu.
  • businessDocumentId: identyfikator definicji dokumentu.
  • attachmentCategoryId: identyfkator kategorii załączników; jeśli zostanie pominięty, załącznik zostanie dodany do kategorii domyślnej.

  • overwrite: decyduje, czy istniejący plik załącznika o takiej samej nazwie ma zostać nadpisany (true), czy załącznik ma zostać dodany jako nowa wersja (false).

    Endpoint /Attachment/UploadAttachment - parametry
    Endpoint /Attachment/UploadAttachment - parametry

W sekcji nagłówków należy ustawić parametry jak na ilustracji poniżej.

Endpoint /Attachment/UploadAttachment - nagłówki
Endpoint /Attachment/UploadAttachment - nagłówki

Plik załącznika należy załączyć w sekcji body, wybierając typ form-data i dodając parametry file i type. Dla pierwszego należy wybrać z listy rozwijanej rodzaj File, co umożliwi wybranie pliku załącznika z dysku w kolumnie wartości. W programie Postman plik musi znajdować się w katalogu roboczym definiowanym w ustawieniach. W przypadku polecenia curl plik musi znajdować się w bieżącym katalogu, w którym jest uruchamiane polecenie.

Endpoint /Attachment/UploadAttachment - body
Endpoint /Attachment/UploadAttachment - body

curl:

curl -k --location 'https://localhost:1414/publicapi/Attachment/UploadAttachment?
recordId=30&businessDocumentId=1&attachmentCategoryId=1023&overwrite=false' \
--header 'Accept: text/html' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6...' \
--form 'file=@"cc1ea18c-5295-4b33-88d0-f248c23356fa.jpg"' \
--form 'type="image/jpg"'

Odpowiedź zwracana przez endpoint po pomyślnym wykonaniu przedstawiono na ilustracji poniżej.

Endpoint /Attachment/UploadAttachment - response
Endpoint /Attachment/UploadAttachment - response

Błędy braku uprawnień

Kiedy użytkownik wysyłający żądanie nie ma odpowiednich uprawnień, w odpowiedzi zostanie zwrócony błąd z komunikatem lub bez dodatkowego komunikatu. Poniżej przedstawiono kilka podstawowych przypadków.

  1. Użytkownik nie ma włączonego dostępu do PublicAPI w profilu użytkownika.

    Brak dostępu do PublicAPI
    Brak dostępu do PublicAPI

  2. Użytkownik nie ma roli Administrator użytkowników PublicAPI.

    Brak roli administratora PublicAPI
    Brak roli administratora PublicAPI

  3. Użytkownik nie ma uprawnień ACL do modyfikowania dokumentu.

    Brak uprawnień ACL do dokumentu
    Brak uprawnień ACL do dokumentu

  4. Użytkownik nie ma uprawnień PBA do wykonania danej czynności.

    Brak uprawnień PBA
    Brak uprawnień PBA

Znane problemy

Obecnie (wersja nAxiom 1.15.2.0*) znane są następujące problemy dotyczące endpointów PublicAPI.

  1. /Attachment/RemoveAttachment: usunięcie wersji załącznika powoduje całkowite usunięcie załącznika z dokumentu.
  2. /Attachment/UploadAttachment: nie jest walidowany identyfikator dokumentu, do którego ma zostać dodany załącznik; w przypadku podania id dokumentu, który nie istnieje, wykonanie żądania powiedzie się i informacje o załączniku trafią do tabeli core.Attachments, a sam załącznik do repozytorium danej kategorii. Jednak wobec braku dokumentu, zarządzanie załącznikiem i wyświetlanie jego podglądu na formularzu nie będzie możliwe.
  3. /Document/CreateNewSchema: endpoint działa nieprawidłowo, jest przeznaczony do wycofania.
  4. /Document/GetFormTransitions: endpoint za każdym razem zwraca status 400.
  5. /Document/GetTransitions: endpoint za każdym razem zwraca status 400.
  6. /Permission/GetAll: w zwracanej odpowiedzi brakuje niektórych atrybutów (nazwy modułu, id aplikacji, nazwy aplikacji, ról z dostępem do danej pozycji menu).
  7. /OrganizationStructure/GetOrganizationById: nie zwraca ról użytkownika w jednostce organizacyjnej.
  8. /OrganizationStructure/SaveOrganization: umożliwia zapisanie kodu jednostki organizacyjnej, który zawiera nieprawidłowe znaki; taki kod powoduje błędy w działaniu aplikacji nAxiom.
  9. /User/GetById: zwraca status 200 OK także wtedy, gdy użytkownik o podanym id nie istnieje.
  10. /User/Save: jeśli nie zostanie podana rola systemowa, żądanie zwraca status 400, ale użytkownik jest dodawany do tabeli auth.AspNetUSers.
  11. /User/Save: jeśli parametr recordId zostanie podany także w sekcji body żądania, wartość z body przesłania wartość podaną w parametrze.

Ponadto, ustawienia systemu są wczytywane do PublicAPI w momencie uruchamiania, dlatego ich zmiana wymaga restartowania puli publicapi

Copyright © 2025 OPTEAM SA. Theme Copyright © 2017-2020 Patrick Marsceill. Distributed by an MIT license.