EI_Script_OD – szczegóły skryptu OData
Arkusz EI_Script_OD zawiera szczegóły skryptów wykorzystujących serwisy Open Data Protocol (w sktrócie OData, patrz https://www.odata.org/). Arkusz jest widoczny, tylko jeśli wybrany jest skrypt typu OData (patrz arkusz EI_Script_Name) i nie jest ukryta konfiguracja. Skrypt OData może odczytywać i zapisywać dane w SAP poprzez odwołania do serwisu sieciowego zgodnego z protokołem OData. SAP w wersji S4HANA udostępnia setki użytecznych serwisów OData (dla przykładu transakcje nowego interfejsu SAP Fiori, wykorzystują serwisy OData). Opórcz danych skryptu OData (kolumny F-J) arkusz EI_Script_OD zawiera dodatkowe dane sterujące wykonaniem skryptu.
Przygotowanie skryptu OData
Przygotowanie skryptu OData zaczyna się zazwyczaj od zapoznania się z właściwościami serwisu OData. W celu zebrania informacji o usłudze OData z systemu SAP, warto zapoznać się z jej możliwościami w transakcji testowej serwisów OData /n/IWFND/GW_CLIENT.
Kiedy serwis OData zostanie rozpoznany i parametry jego wywołania zostaną ustalone, można przejść do zdefiniowania skryptu OData w narzędziu EasyInput. Definiowanie skryptu OData można wykonać ręcznie w arkuszu EI_Script_OD, ale dużo łatwiej rozpocząć definicję wykorzystując automat, który uruchamia się przyciskiem menu wstążki „Dodaj serwis OData”.
EI_Script_OD – Przycisk wstążki: Znajdź serwis OData
Przycisk „Znajdź serwis ODATA” wywołuje okienko pomocy wskazujące jak można wyszukać i uruchomić usługę OData w systemie SAP.
EI_Script_OD – Przycisk wstążki: Dodaj serwis OData
Serwis OData systemu SAP lub dowolny serwis OData można dodać do EasyInput poprzez wybranie przycisku menu wstążki „Dodaj serwis OData”. Na wyskakującym okienku „Wybór serwisu OData” trzeba będzie podać najważniejsze dane usługi OData. Po zaakceptowaniu podanych danych klawiszem OK, EasyInput spróbuje połączyć się z wybraną usługą, wywołać ją testowo i na tej podstawie wygeneruje skrypt EasyInput OData. Wygenerowany skrypt może być dalej ręcznie dostosowywany w narzędziu EasyInput. W szczególności mogą być dodawane paramerty przekazywane do skryptu (WriteData w kolumnie L, dla części URL i części importowej skryptu IDATA, oraz ReadData dla części eksporotowej EDATA). Specjalny znacznik && jest wykorzystywany do przekazywania parametru w odpowiednie miejsce skryptu.
Przykład gotowego skryptu OData listującego dane MPK systemu:
|
Użycie parametru |
Nazwa parametru |
Nazwa pola |
Typ danych |
Wartość pola |
Opis pola |
Typ transferu |
Kolumna odczytu/ zapisu |
|
|
|
OD |
CCR |
|
|
|
|
|
|
|
|
TYPE |
OD_SAP_V2 |
|
|
|
|
|
|
|
|
METHOD |
GET |
|
|
|
|
|
|
|
|
URI_PART0 |
&cprotocol&://&chost&:&cport&/ |
|
|
|
|
|
|
|
|
URI_PART1 |
sap/opu/odata/ |
|
|
|
|
|
|
|
|
URI_PART2 |
sap/FCOM_COSTCENTER_SRV/CostCenterSet? |
|
|
|
|
AssignData |
AA |
|
|
URI_PARTX |
|
|
|
|
|
|
|
|
|
FORMAT |
$format=json |
|
|
|
|
|
|
|
X |
EDATA |
|
BUKRS_TEXT |
CHAR-25!-- |
|
Company Name |
|
|
|
|
EDATA |
|
Kokrs |
CHAR-4!-- |
|
Controlling Area |
ReadData |
AB |
|
|
EDATA |
|
Kostl |
CHAR-10!-- |
|
Cost Center |
ReadData |
AC |
|
|
ERC |
error |
code |
|
|
|
|
|
|
|
ERM |
error |
message |
|
|
|
|
|
|
|
ERM |
error-message |
value |
|
|
|
|
|
|
|
ERT |
error |
severity |
|
|
|
|
|
Kolumna Użycie parametru (Param use) definiuje co oznacza dany wiersz skryptu OData:
|
Użycie parametru |
Opis znaczenia parametru |
|
OD |
Oznacza początek skryptu OData |
|
TYPE |
Oznacza typ skryptu (OD_SAP_V2, OD_SAP_V4, OD_NOT_SAP) |
|
METHOD |
Metoda wywołania HTTP. GET dla odczytu danych, PUT, POST, PATCH, DELETE dla zmiany danych (możliwość wykorzystania metod zależy od implementacji serwisu OData). |
|
PREGETQUERY |
Parametr wykorzystywany tylko dla metod innych niż GET. X jeśli przed wywołaniem metody innej niż GET, najpierw ma być wykonana metoda GET, by pobrać X-CSRF-Token umożliwiający poprawne wyłołanie metody innej niż GET. Dodatkowo EasyInput może odczytać wartość pola ETAG z wywołania GET i wstawić odpowiednią wartość w nagłówek wywołania If-Match dla metody innej niż GET (patrz dokumentacja SAP) |
|
URI_PART0 |
Określa URL usługi - protokół, host i port, np.: https://services.odata.org:443 Zazwyczaj dla serwisów SAP dane te nie są podawane bezpośrednio, ale za pomocą znaczników specjalnych (&cprotocol&://&chost&:&cport&/ patrz opis poniżej), co ułatwia użycie tego samego skryptu EasyInput w różnych systemach SAP. Jeśli użyto znaczników specjalnych w URI_PART0, to przed rzeczywistym wywołaniem serwisu, zastąpione one zostaną właściwym protokołem (http(s), nazwą hosta, portem odczytanym z systemu SAP). |
|
URI_PART1 |
Określa scieżkę do serwisu w ramach url. Np. dla serwisów OData SAP w wersji V2, scieżka domyślna to „sap/opu/odata/”. |
|
URI_PART2 |
Określa usługę (łącznie z obszarem nazw) i zasób w ramach usługi, np: sap/FCOM_COSTCENTER_SRV/CostCenterSet? |
|
URI_PARTX |
Określa ew. dodatkowe parametry usługi. Uwaga! Można dodać więcej niż jedną linię z użyciem parametru URI_PARTX ! Uwaga! W momencie przetwarzania skryptu, system dokonuje połączenia ciągów z URI_PART0/PART1/PART2/PARTX, dlatego ciągi zawarte w tych wierszach muszą stanowić po złożeniu poprawny URI wywołania usługi (np. muszą kończyć się znakami /,? &, etc.). Możliwe jest użycie znacznika specjalnego && w URI_PART2 lub URI_PARTX, dzieki czemu można uczynić wywołanie bardziej elastycznym (np. przekazać parametry filtra do wywołania). Uwaga! Dla metody GET, jeśli nie przewidziano przekazywania danych do skryptu (typ transferu WriteData), należy do jednego z wierszy URI przypisać typ transferu AssignData i podać kolumnę odczytu/zapisu. Wynika to z faktu, że skrypt EasyInput musi być inicjowany przez jakąś kolumnę danych na arkuszu danych. Dlatego przypisanie kolumny do skryptu poprzez AssignData i wprowadzenie dowolnej wartości w tę kolumnę (np. START), rozwiązuje ten problem. |
|
FORMAT |
Określa format w jakim zostanie wykonany serwis. Zalecanym jest $format=json. Wartością niezalecaną, ale w wyjątkowych przypadkach możliwą do użycia jest $format=xml. Dla otrzymania włąściwych rezultatów z formatem xml należy ustawić w konfiguracji na zakładce EI_Config, EI_C_OD_MATCHING_LEVEL Poziom dopasowania rezultatu na wartość 1. |
|
IHEADER |
Parametr wykorzystywany tylko dla metod innych niż GET. Zazwyczaj ma wartość application/json;charset=utf-8 ale jeśli IDATA podany jest w postaci XML (nie rekomendowane) powinien mieć wartość application/xml;charset=utf-8 |
|
IDATA |
Parametr wykorzystywany tylko dla metod innych niż GET. Ciąg znaków w formacie JSON (zalecany) lub XML, który zostanie przekazany do serwisu. Zazwyczaj w skrypcie występuje wiele linii IDATA (zwiększa to czytelnośc skryptu), które przed wywołaniem zostaną połączone w jeden ciąg. Podobnie jak w URI, w wierszach IDATA można korzystać ze znacznika specjalnego &&. Dodanie takiego znacznika do wiersza, umożliwia przypisanie typu transferu WriteData i kolumny odczytu. |
|
EDATA |
Lista parametrów, które może zwrócić serwis OData. Przypisanie do danego wiersza Typu Transferu ReadData pozwala na odczytanie zawartości danego parametru i wprowadzenie go na arkusz danych/ rezultatu do kolumny zdefiniowanej jako kolumna zapisu. Uwaga domyślnie wszystkie parametry EData są nieaktywne. W celu odczytu parametru należy skasować w skrypcie „X” deaktywujący dany wiersz, przypisać rodzaj transferu ReadData i kolumnę zapisu. W kolumnach nazwa pola/ typ danych umieszcza się ciąg nazw wskazujący właściwą daną w rezultacie query w postaci JSON. Z ciągu tego wycięte są elementy „d” (początkowy) i „results” (oznaczający tabelę danych). Dzięki temu skrypt jest bardziej czytelny. |
|
ERC, ERCD, ERM, ERMD, ERT, ERTD, ERX, ERXD |
Wiersze definiujące sposób odczytu danych o błędach ze zwracanego ciągu JSON/ XML lub w SAP także z ciągu umieszczanego w zwracanym nagłówku w sap-message. Wiersze te są wypełniane automatycznie, ale jeśli serwis zwraca informacje o błędzie w jakiś niestandardowy sposób, można poprawić te wpisy ręcznie. Trzecia litera użycia parametru oznacza, w tym przypadku, czy odczytywany jest kod komunikatu (C), tekst komunikatu(M), czy typ komunikatu (T). Specjalny znacznik X jest zarezerwowany dla odczytu parametrów V1, V2,V3,V4 komunikatów SAP z nagłówka z sap-message. |
|
HTTPUSER |
Parametr opcjonalny, wykorzystywany czasem dla serwisów ODATA nie SAP. Pozwala przekazać nazwę użytkownika do wywołania http. Parametr ten powinien być wykorzystywany łącznie z parametrem HTTPPASS. |
|
HTTPPASS |
Parametr opcjonalny, wykorzystywany czasem dla serwisów ODATA nie SAP. Pozwala przekazać hasło użytkownika do wywołania http. Parametr ten powinien być wykorzystywany łącznie z parametrem HTTPUSER. |
Znaczniki specjalne (zamieniane w momencie wykonania skryptu):
|
Znacznik |
Znaczenie |
|
&& |
Pozwala na przekazywanie dynamicznych parametrów do skryptu OData (do użycia w parametrach URI_PART_X). Oznacza w które miejsce w skrypcie przetransferowany zostanie element zdefiniowany przez komórkę w kolumnie J (wartość stała lub formuła) lub poprzez komórki z kolumn L(WriteData) i M(odwołanie do kolumny). Przy czym jeśli wprowadzono dane w kolumnach L(typ transferu) i M(kolumna odczytu/zapisu), wartość z komórki w kolumnie J(wartość pola) jest ignorowana! Uwaga! W rzadkim przypadku, kiedy trzeba przesłać ciąg "&&" bez podmiany, należy wprowadzić go w postaci "&&". |
|
&cprotocol& |
Oznacza protokół http lub https dla połączenia z serwerem SAP Gateway. Protokół można podać na stałe lub za pomocą tego znacznika. Jeśli podany znacznik, wtedy system sprawdza dostępność połączenia szyfrowanego (https). Jeśli jest dostępne wybiera https, jeśli nie http. |
|
&cserver& |
Oznacza serwer Gateway SAP. Serwer można podać na stałe, lub może być podany za pomocą znacznika. W przypadku gdy jest podany za pomocą znacznika, serwer jest ustalany na podstawie informacji z systemu SAP podanych na zakładce EI_Logon (rekomendowana opcja). |
|
&cport& |
Oznacza port Gateway SAP. Port usługi można podobnie jak serwer usługi podać na stałe, lub może być podany za pomocą znacznika. |
Uwaga! Jeśli chcemy, by dana część skryptu mogła być wykonywana wielokrotnie, zależnie od ilości wierszy danych (np. pozycje dokumentu), wtedy dla tych wierszy skryptu, w kolumnie poziom, wprowadzamy wartość 1 (patrz informacje o arkuszu skryptu). Jeśli na końcu bloku JSON, w części powtarzalnej, powinien być wstawiony przecinek, to należy go umieścić w skrypcie. EasyInput automatycznie usunie go z ostatniego powtórzenia części powtarzanej wielokrotnie, by zachować poprawność wyrażenia JSON.
EI_Script_OD – Przycisk wstążki: Uzupełnij kolumny odczytu/zapisu
Aby ułatwić przypisywanie wierszy skryptu do kolumn arkusza danych, możliwe jest wprowadzanie ręcznie w skrypcie tylko powiązania z arkuszem danych w kolumnie L (np. WriteData/ ReadData) i automatyczne uzupełnienie identyfikatorów kolumn w kolumnie M skryptu. Uruchomienie automatycznego przypisywania identyfikatorów kolumn danych („np. AA, AB, AC, …) uruchamia się przyciskiem „Uzupełnij kolumny odczytu/zapisu”. Później ręcznie można skorygować takie automatyczne przypisania.
EI_Script_OD – Przycisk wstążki: Utworzenie referencji kolumny danych ze skryptu w arkuszu danych
Po zdefiniowaniu skryptu i jego wstępnym sprawdzeniu za pomocą menu wstążki „Sprawdź skrypt”, należy utworzyć referencje kolumn odczytu/zapisu (L) z arkusza skryptu w arkuszu danych. Jest to czynność uruchamiana przyciskiem „Utwórz referencje w kolumnach arkusza danych” na wstążce EasyInput.