INPUT REST API

Operator INPUT REST API umożliwia wywołanie dowolnego serwisu dostępnego w standardzie REST, odebranie zwróconych przez niego danych oraz wprowadzenie ich na magistralę w formie tekstowej lub bitowej. Aby dowiedzieć się więcej o konwersji danych tekstowych na bity magistrali danych zapoznaj się z operatorem CONVERT FORMAT TO BITS.

Operator INPUT REST API wykonywany jest jednorazowo na początku magistrali i inicjuje jej działanie, pobierając dane niezależnie od wcześniejszych rekordów.

Konfiguracja operatora pozwala na:

• wskazanie adresu serwisu REST oraz metody HTTP (GET, POST itd.),
• dynamiczne ustawienie nagłówków i parametrów zapytania
• obsługę różnych mechanizmów autoryzacji
• oraz kontrolę nad formatem odbieranych danych.

Dzięki temu operatorowi możliwe jest automatyczne załadowanie danych z systemów zewnętrznych do środowiska GRAVITY i rozpoczęcie dalszego przetwarzania w projekcie.

PRZYKŁAD PROCESU Z UŻYCIEM OPERATORA

Proces zakłada samodzielne sprawdzenie Status Code zwracanego przez wywołany serwis.

KONFIGURACJA MAGISTRALI WYJŚCIOWEJ

W przypadku użycia operatora INPUT REST API, magistrala wyjściowa operatora będzie zawierać jeden rekord zbudowany z pola danych odebranych z serwisu (zwykle format JSON ale może to być również format XML lub czysty tekst) oraz - w zależności od konfiguracji - pola Error checking ze zwróconym Status Code wykonania serwisu.

Na zakładce Execution należy ustawić sposób działania operatora po otrzymaniu odpowiedzi od wywołanej usługi.

• New column with result → Nazwa kolumny (bitu) magistrali danych wyjściowej gdzie zostaną przekierowane dane odebrane z usługi sieciowej (web service).
• Error checking → określa sposób zachowania operatora po odebraniu Status Code oznaczającego błędne wykonanie serwisu.
• Report an error when Status Code is invalid → w przypadku błędnego Status Code proces zostaje zatrzymany i jako błąd zostanie wyświetlony komunikat z pola Body field with an error message.
• Send Status Code on the busbar → w tym wypadku proces nie zostanie zatrzymany, a Status Code zostanie przekazany na magistralę danych w bicie o nazwie podanym w polu New column with status code i może zostać zweryfikowany w procesie przy użyciu operatora IF. Jeśli usługa zwraca szczegóły błędu są one dostepne w polu New column with result
• Body field with an error message → komunikat błędu w przypadku przerwania działania procesu automatycznie gdy otrzymany jest niepoprawny Status Code.
• New column with status code → kolumna (bit) do którego trafi Status Code wykonania.

Pola Single execution oraz Result target są nieaktywne i używane tylko w operatorze REST API CALL .

KONFIGURACJA ADRESU USŁUGI

Aby skonfigurować połączenie do serwisu, musisz na zakładce Request podać metodę HTTP jakiej używa serwis, adres pod jakim dostępny jest serwis i, jeśli to jest wymagane, metodę autoryzacji.

Operator obsługuje następujące metody HTTP:

• GET
• POST
• PUT
• DELETE
• PUTCH

oraz podstawowe metody autoryzacji:

• Basic Auth
• Api key
• Simple auth
• Bearer token
• Bearer token (system connections)

Ponieważ operator zapewnia pełen dostęp do tworzenia nagłówków żądania HTTP oraz pozwala na ich elastyczną budowę z wykorzystaniem parametrów, możliwe jest użycie praktycznie każdego systemu uwierzytelniania.

Podając adres serwisu w polu Endpoint, możesz użyć parametrów projektu lub parametrów globalnych. Parametry możesz wstawić, korzystając z przycisku obok pola lub wpisując @ dla parametrów lokalnych i {{ dla parametrów globalnych.

Parametry wywołania możemy podać bezpośrednio w polu Endpoint w formacie [endpoint]?parName1=value&parName2=value lub wprowadzić je w formacie nazwa → wartość w zakładce Query parameters.

NAGŁÓWKI ZAPYTANIA HTTP

Zakładka Headers pozwala na podgląd dodawanie i modyfikowanie nagłówków zapytania HTTP. Operator ustawia kilka standardowych nagłówków.

Jeśli chcesz zmodyfikować dowolny nagłówek, kliknij dwukrotnie w jego wartość, aby ją zmienić.

Aby wprowadzić nowy nagłówek, kliknij w ostatni rekord i podaj nazwę i wartość nagłówka.

W polu nagłówka możesz wprowadzić:

• wartość parametru projektu, poprzedzając jego nazwę znakiem @ np. @username
• wartość parametru globalnego, ujmując go w podwójny nawias klamrowy {{[globalVariableName]}}, np. {{userName}}
• wartość z bitu magistrali (tylko w operatorze REST API CALL ) wstawiając ją w procentach. Format %bitName% np. %userName%.

CONTENT ZAPYTANIA

W zakładce Body możesz skonfigurować treść (content) wysyłaną w żądaniu do serwisu REST.

Operator umożliwia wysyłanie danych w różnych formatach, w zależności od wymagań zewnętrznego serwisu:

• none - Nie wysyła żadnej treści w body.
• form-data - Dane są wysyłane jako pary klucz/wartość, bez kodowania. Ten typ pozwala również na przesyłanie danych binarnych.

Po wybraniu tego typu możesz dodawać kolejne pola klikając w pusty rekord i podając nazwę klucza oraz wartość.

• x-www-form-urlencoded - Dane są wysyłane jako pary klucz/wartość, ale są kodowane w taki sam sposób, jak parametry w adresie URL. Nie można w ten sposób przesyłać danych binarnych.

Pola definiuje się analogicznie jak w typie form-data — klikając w pusty rekord.


• raw - W tym trybie można wprowadzić dowolny ciąg znaków jako treść żądania. Dodatkowo należy określić format, co pozwala systemowi ustawić odpowiedni nagłówek Content-Type.


Dostępne formaty:

1. Text – zwykły tekst
2. JavaScript – kod zgodny z językiem JavaScript
3. JSON – dane w formacie JSON (JavaScript Object Notation)
4. HTML – dane w formacie HTML (HyperText Markup Language)
5. XML – dane w formacie XML (Extensible Markup Language)

W zależności od wybranego formatu system automatycznie ustawi odpowiedni nagłówek Content-Type w żądaniu.