Specyfikacja API Runtime BAS 3.0 Spis treści Wstęp... 4 Informacja o dokumencie... 4 Opis usługi... 4 Typowy sposób wywołania usługi... 5 Udostępniane funkcje... 6 Funkcje liczące... 6 Execute... 6 SafeExecute... 6 MultiExecute... 7 ExecuteDataStructure... 7 Funkcje informacyjne... 8 GetModelList... 8 GetVersionList... 8 GetVersionInfo... 9 GetVersionFromDate... 9 Funkcje zwracające schemę algorytmu... 9 GetInputSchema... 9 GetOutputSchema... 10 GetExtendedInputSchema... 10 GetExtendedOutputSchema... 10 Funkcje zwracające schemę globalną... 11 GetGlobalInputSchema... 11 GetGlobalOutputSchema... 11 GetExtendedGlobalInputSchema... 12
GetExtendedGlobalOutputSchema... 12 Funkcje zwracające kod algorytmów/tabel... 13 GetModelVersion... 13 GetTableVersion... 13
Wstęp Informacja o dokumencie Niniejszy dokument dotyczy usługi Runtime aplikacji BAS w wersji 3.0. Przedstawiono ogólny opis usługi oraz udostępniane funkcje. Jest on przeznaczony dla programistów chcących wykorzystać stworzone algorytmy bezpośrednio z kodu swoich aplikacji. Cała dokumentacja została podzielona na pięć rozdziałów: Funkcje liczące - funkcje służące do wykonywania wszelkich obliczeń, Funkcje informacyjne dzięki którym można uzyskać informację o zawartości środowiska, Funkcje zwracające schemę algorytmu dzięki którym możemy uzyskać informację w jakiej postaci należy wysłać wyniki by były one przetworzone przez algorytm i w jakiej postaci otrzymamy, Funkcje zwracające schemę globalną funkcje pełniące role podobną do tych w poprzednim rozdziale, ale dotyczące zbioru wszystkich algorytmów, Funkcje zwracające kod algorytmów/tabel funkcje które zwracają biblioteki algorytmów i tabel na żądanie. Jest to funkcja stosowana w dodatkowo rozszerzonym pakiecie enterprise. W sytuacji, kiedy istnieje potrzeba wykonania obliczeń nie po stronie usługi, ale aplikacji końcowej (Ich zastosowanie wymaga informacji z poza ten zakres tego dokumentu.). Opis usługi Jest to usługa sieciowa zrealizowana w technologii WCF, która ma za zadanie zarządzać uruchamianie i wykonaniem algorytmów stworzonych za pomocą aplikacji BAS. Przez tę usługę można przekazać dane do wersji algorytmu i przeprowadzić zamodelowany proces przetwarzania danych oraz uzyskać obliczoną odpowiedź. Runtime posiada własną bazę danych i opiera się na algorytmach w postaci plików *.dll oraz informacjach pomocniczych w bazie danych zbudowanych. Za pomocą tego serwisu można również uzyskać informacje o algorytmach dostępnych na danym środowisku.
Typowy sposób wywołania usługi Najczęściej spotykany sposób wywołania przeliczenia usługi BAS odbywa się kolejno w krokach: 1. Uzyskanie informacji o dostępnych algorytmach (wywołanie funkcji GetModelList) 2. Wybranie konkretnej wersji po dacie, najczęściej bieżącej (wywołanie funkcji GetVersionFromDate) 3. Informacja o formacie danych wejściowych (wywołanie funkcji GetInputSchema) 4. Wywołanie przeliczenia (wywołanie funkcji Execute lub SafeExecute) W środowiskach gdzie konkretne miejsca aplikacji wywołują konkretne algorytmy często pomija się krok pierwszy. W przypadkach gdy istnieje pewność, że struktura danych się nie zmienia można również pominąć krok 3.
Udostępniane funkcje Funkcje liczące Execute Opis: Wykonuje obliczenia na danej wersji algorytmu. Sygnatura: string Execute(string a_oinputdata, Guid a_oversionid) string a_oinputdata dane wejściowe do algorytmów w postaci xml Guid a_oversionid identyfikator wersji algorytmu Wynik: Wynik obliczeń w postaci xml SafeExecute Opis: Wykonuje obliczenia na danej wersji algorytmu, w razie niepowodzenia wynik zawiera informacje o błędach. Sygnatura: ExecuteResponse SafeExecute(string a_oinputdata, Guid a_oversionid) string a_oinputdata dane wejściowe do algorytmu w postaci xml Guid a_oversionid identyfikator wersji algorytmu Wynik: ExecuteResponse udostępnia następujące właściwości: string Result wynik obliczeń w postaci xml string Error opis błędu
string FaultModel nazwa algorytmu string FaultElement nazwa elementu, w którym wystąpił błąd string FaultValuePath ścieżka do zmiennej, która spowodowała wystąpienie błędu MultiExecute Opis: Wykonanie obliczeń dla wielu wersji algorytmów. Sygnatura: ICollection<MultiExecutorResult> MultiExecute(ICollection<KeyValuePair<Guid, string>> a_oinputpair) ICollection<KeyValuePair<Guid, string>> a_oinputpair kolekcja par: identyfikator algorytmu, dane wejściowe w postaci xml Wynik: ICollection<MultiExecutorResult> - kolekcja struktur MultiExecutorResult zawierającą właściwości: bool Success Informacja czy przetwarzanie powiodło się Guid Version Identyfikator wersji string Error Informacje o ewentualnym błędzie string Result wynik obliczeń ExecuteDataStructure Opis: Wykonuje obliczenia na algorytmu, z którym skojarzone są dane wejściowe ze struktury danych. Sygnatura: IMdDataStructure ExecuteDataStructure(IMdDataStructure a_omddatastructure)
IMdDataStructure a_omddatastructure dane wejściowe do algorytmu w postaci wypełnionej struktury danych Wynik: Wycinek struktury danych uzupełniony wynikiem obliczeń Funkcje informacyjne GetModelList Opis: Pobiera listę algorytmów znajdujących się na serwerze. Sygnatura: ICollection<ElementInfo> GetModelList() brak Wynik: Kolekcja elementów ElementInfo zawierających właściwości: String Name nazwa algorytmu Guid ElementId identyfikator algorytmu GetVersionList Opis: Pobiera listę wersji dla danego algorytmu. Sygnatura: ICollection<VersionInfo> GetVersionList(Guid a_omodelid) Guid a_omodelid identyfikator algorytmu Wynik: Kolekcja elementów VersionInfo zawierających właściwości: Guid ElementId identyfikator algorytmu String ElementName nazwa algorytmu Guid VersionId identyfikator wersji DateTime ValidFrom początkowa data obowiązywania
DateTime ValidTo końcowa data obowiązywania DateTime LastCheckedIn data ostatniego zapisu na serwerze GetVersionInfo Opis: Pobiera informacje o konkretnej wersji algorytmu. Sygnatura: VersionInfo GetVersionInfo(Guid a_gversionid) Guid a_gversionid identyfikator wersji Wynik: Wynikiem jest obiekt VersionInfo, którego właściwości zostały opisane w punkcie 0 GetVersionFromDate Opis: Pobiera informacje o wersji algorytmu, obowiązującej w określonym czasie. Sygnatura: VersionInfo GetVersionFromDate(DateTime a_dtdate, Guid a_omodelid) DateTime a_dtdate data, z której chcemy pobrać informacje o obowiązującej wersji algorytmu Guid a_omodelid identyfikator algorytmu Wynik: Wynikiem jest obiekt VersionInfo, którego właściwości zostały opisane w punkcie 0 Funkcje zwracające schemę algorytmu GetInputSchema Opis: Pobiera schemat struktury wejściowej algorytmu. Sygnatura: string GetInputSchema(Guid a_oversionid)
Guid a_oversionid identyfikator wersji Wynik: Wynikiem jest string zawierający schemę wejściową do algorytmu. GetOutputSchema Opis: Pobiera schemat struktury wyjściowej algorytmu. Sygnatura: string GetOutputSchema(Guid a_oversionid) Guid a_oversionid identyfikator wersji Wynik: Wynikiem jest string zawierający schemę wyjściową z algorytmu. GetExtendedInputSchema Opis: Pobiera rozszerzoną schemę struktury wejściowej algorytmu o opisy oraz definicje słowników. Służy do dynamicznego budowania kontrolek do wprowadzania danych na podstawie informacji o algorytmie. Sygnatura: string GetExtendedInputSchema(Guid a_oversionid) Guid a_oversionid identyfikator wersji Wynik: Wynikiem jest string zawierający rozszerzoną schemę wejściową do algorytmu. GetExtendedOutputSchema Opis: Pobiera rozszerzoną schemę struktury wyjściowej algorytmu o opisy oraz definicje słowników. Służy do dynamicznego budowania kontrolek do wyświetlania danych otrzymanych w wyniku działania algorytmu. Sygnatura: string GetExtendedOutputSchema(Guid a_oversionid)
Guid a_oversionid identyfikator wersji Wynik: Wynikiem jest string zawierający rozszerzoną schemę wyjściową z algorytmu. Funkcje zwracające schemę globalną Z tego zestawy funkcji korzysta się przy założeniu, kiedy wszystkie algorytmy są stworzone na jednej i tej samej wersji struktury danych. Dzięki nim można stworzyć jeden centralny obiekt odpowiedzialny za tworzenie (mapowanie) zestawów danych na potrzeby różnych algorytmów. GetGlobalInputSchema Opis: Pobiera ogólną scheme wejściową - złożenie schem podanych algorytmów obowiązujących w danym dniu Sygnatura: String GetGlobalInputSchema(DateTime a_dtday, IEnumerable<Guid> a_colmodelids) DateTime a_dtday data, z której chcemy pobrać informacje o schemach wejściowych algorytmów obowiązujących w danym dniu IEnumerable<Guid> a_colmodelids kolekcja identyfikatorów algorytmów Wynik: Wynikiem jest string zawierający schemę wejściową algorytmów obowiązujących w danym dniu. GetGlobalOutputSchema Opis: Pobiera ogólną scheme wyjściową - złożenie schem podanych algorytmów obowiązujących w danym dniu Sygnatura: String GetGlobalOutputSchema(DateTime a_dtday, IEnumerable<Guid> a_colmodelids)
DateTime a_dtday data, z której chcemy pobrać informacje o schemach wyjściowych algorytmów obowiązujących w danym dniu IEnumerable<Guid> a_colmodelids kolekcja identyfikatorów algorytmów Wynik: Wynikiem jest string zawierający schemę wyjściową algorytmów obowiązujących w danym dniu. GetExtendedGlobalInputSchema Opis: Pobiera rozszerzoną scheme wejściową - złożenie schem podanych algorytmów obowiązujących w danym dniu Sygnatura: String GetExtendedGlobalInputSchema(DateTime a_dtday, IEnumerable<Guid> a_colmodelids) DateTime a_dtday data, z której chcemy pobrać informacje o schemach wejściowych algorytmów obowiązujących w danym dniu IEnumerable<Guid> a_colmodelids kolekcja identyfikatorów algorytmów Wynik: Wynikiem jest string zawierający rozszerzoną schemę wejściową algorytmów obowiązujących w danym dniu. GetExtendedGlobalOutputSchema Opis: Pobiera rozszerzoną scheme wyjściową - złożenie schem podanych algorytmów obowiązujących w danym dniu Sygnatura: String GetExtendedGlobalOutputSchema(DateTime a_dtday, IEnumerable<Guid> a_colmodelids) DateTime a_dtday data, z której chcemy pobrać informacje o schemach wyjściowych algorytmów obowiązujących w danym dniu IEnumerable<Guid> a_colmodelids kolekcja identyfikatorów algorytmów
Wynik: Wynikiem jest string zawierający rozszerzoną schemę wyjściową algorytmów obowiązujących w danym dniu. Funkcje zwracające kod algorytmów/tabel Wywołując poniżej opisane metody zostanie zwrócona tablica bajtów zawierająca pliki dll z kodem algorytmu bądź tabeli. Dzięki nim można przeprowadzić obliczenia na maszynie, na której pliki te się znajdują. Niezbędne jednak do przeprowadzenia tego procesu są również niektóre biblioteki BAS. GetModelVersion Opis: Zwraca plik dll algorytmu. Sygnatura: byte[] GetModelVersion(string a_strmodelassemblyname) string a_strmodelassemblyname nazwa pliku dll na serwerze, bez rozszerzenia Wynik: Wynikiem jest tablica bajtów zawierająca plik dll odczytany z serwera. GetTableVersion Opis: Zwraca plik dll tabeli. Sygnatura: byte[] GetTableVersion(string a_strtableassemblyname) string a_strtableassemblyname nazwa pliku dll na serwerze, bez rozszerzenia Wynik: Wynikiem jest tablica bajtów zawierająca plik dll odczytany z serwera.