Kuba1: Porovnání verzí

Z Prirucky
Řádek 314: Řádek 314:
===Správa uživatelů===
===Správa uživatelů===


V ASSM se provádí nastavení uživatelských účtů pro autentizaci. V sekci ''''Nastavení webové služby'''' se po stisku tlačítka 'Správa uživatelů' otevře příslušné okno .
V AS SeanceManager se provádí nastavení uživatelských účtů pro autentizaci. V sekci ''''Nastavení webové služby'''' se po stisku tlačítka 'Správa uživatelů' otevře příslušné okno .


[[Soubor:Sprava-uzivatelu-KS-WEBAPI.jpg]]
[[Soubor:Sprava-uzivatelu-KS-WEBAPI.jpg]]


[[Soubor:Pristupova-prava-polozky-ks-webapi.jpg]]
[[Soubor:Pristupova-prava-polozky-ks-webapi.jpg|150px]]

Verze z 21. 4. 2021, 10:24

KS WebAPI je webová služba postavená na technologii Windows Communication Foundation. Umožňuje předávat údaje z databáze KS mzdy klientské aplikaci nebo ukládat údaje do databáze KS mzdy zaslané klientskou aplikací.

Komunikační protokol

Pro hostování webové služby se využívá KS aplikační server. Komunikačním protokolem je http, případně ve spojení se SSL (HTTPS). Pro výměnu zpráv se používá protokol SOAP. Ve výchozím nastavení je připraven typ endpointu wsHttpBinding.

Zpřístupnění KS WebAPI

KS WebAPI je potřeba aktivovat přes Rozšíření aplikace v aplikaci KS mzdy (menu: Nápověda > Rozšíření aplikace). Jsou dostupné 3 varianty, které se liší množinou zpracovávaných dat a povolením pro čtení a zápis údajů:

  • KS WebAPI Free
Bezplatná verze obecného rozhraní pro čtení dat zaměstnanců ze systému KS mzdy. Umožňuje čtení omezené množiny položek ze skupiny údajů 'KmenoveUdaje'.
  • KS WebAPI Reader
Obecné rozhraní pro čtení dat zaměstnanců ze systému KS mzdy.
  • KS WebAPI Writer
Obecné rozhraní pro čtení a zápis dat zaměstnanců do/ze systému KS mzdy.

Pro zpřístupnění je potřeba provést tyto kroky:

  1. V aplikaci KS mzdy, v okně 'Rozšíření aplikace' (menu: Nápověda > Rozšíření aplikace), aktivovat požadované rozšíření.
  2. Provést úpravu databáze.
  3. V aplikaci KS mzdy spustit úlohu WebAPI (menu: Systém > Web API). Potvrzením volby 'Ano' dojde k vygenerování dokumentace k přenášeným údajům (ve formě HTML). Generování dokumentace je potom potřeba provádět vždy, pokud bude vydaná nová verze KS WebAPI.

Metody webové služby

KS WebAPI nabízí metody: GetData, InsertData, UpdateData.

Všechny metody přebírají v parametru strukturu KSWebAPI_Parameters a vrací návratovou strukturu KSWebAPI_Response.

GetData

Metoda GetData vrací data z databáze KS mzdy dle zadaných kritérií.

Nastavení parametrů struktury KSWebAPI_Parameters

  • ItemGroup
Povinný údaj. Předá se název skupiny údajů (entity) v KS mzdy (např. 'KmenoveUdaje').
  • Items
Předá se seznam položek, které budou v návratové datové struktuře. Jednotlivé položky se oddělí čárkou (Příklad: OsCislo, Jmeno, Prijmeni).
  • JsonSearchCriteria
Předá se vyhledávací podmínka v JSON formátu.


Popis údajů v návratové struktuře KSWebAPI_Response

  • Data
Očekávané data vyhovující podmínce v JsonSearchCriteria ve formátu JSON.

InsertData

Metoda InsertData zapisuje data do databáze KS mzdy.

Nastavení parametrů struktury KSWebAPI_Parameters

  • ItemGroup
Povinný údaj. Předá se název skupiny údajů (entity) v KS mzdy (např. 'KmenoveUdaje').
  • JsonChangeData
Povinný údaj. V JSON struktuře se předají data, která mají být zapsána do databáze KS mzdy. Vždy se jedná o pole, kde v jednotlivých objektech pole jsou data pro insert.


Příklad dat pro vložení jednoho záznamu 

[
    [{ "IdPodniku": "1", "Jmeno": "Karel", "Prijmeni": "Nový", "RodneCislo": "800101111", "MistoNarozeni": "Vsetín", "StatNar": "CZ", "StPrisl": "203", "RodinStav": "2", "TrCislo": "100", "PscTrv": "75501", "MistoTrv": "Vsetín", "KmenStr": "1", "DatumNastupu": "2019-01-01"}]
]

Příklad dat pro vložení více záznamů 

[
 [ { "IdPodniku": "1", "Jmeno": "Karel", "Prijmeni": "Nový", "RodneCislo": "800101111", "MistoNarozeni": "Vsetín", "StatNar": "CZ", "StPrisl": "203", "RodinStav": "2", "TrCislo": "100", "PscTrv": "75501", "MistoTrv": "Vsetín", 
   "KmenStr": "1", "DatumNastupu": "2019-01-01"},
   { "IdPodniku": "1", "Jmeno": "Petr", "Prijmeni": "Test", "RodneCislo": "81101111", "MistoNarozeni": "Vsetín", "StatNar": "CZ", "StPrisl": "203", "RodinStav": "2", "TrCislo": "101", "PscTrv": "75501", "MistoTrv": "Vsetín", 
   "KmenStr": "1", "DatumNastupu": "2019-02-01"},
   { "IdPodniku": "1", "Jmeno": "Marie", "Prijmeni": "Nová", "RodneCislo": "820101111", "MistoNarozeni": "Vsetín", "StatNar": "CZ", "StPrisl": "203", "RodinStav": "2", "TrCislo": "102", "PscTrv": "75501", "MistoTrv": "Vsetín", 
   "KmenStr": "1", "DatumNastupu": "2019-03-01"}
 ]
]


Popis údajů v návratové struktuře KSWebAPI_Response

  • Data
V JSON formátu jsou předána data, která byla vložena do databáze.

UpdateData

Metoda UpdateData provádí změnu dat v databázi KS mzdy.

Nastavení parametrů struktury KSWebAPI_Parameters

  • ItemGroup
Povinný údaj. Předá se název skupiny údajů (entity) v KS mzdy (např. 'KmenoveUdaje').
  • JsonChangeData
Povinný údaj. V JSON struktuře se předají data, která mají být změněna v databázi KS mzdy. Vždy se jedná o pole. V poli by měl být pouze jeden objekt s měněnými položkami.

Příklad dat pro změnu údajů 

[{ "KmenStr": "100", "DatumVystupu": "2019-12-31" }]
  • JsonSearchCriteria
Předá se vyhledávací podmínka v JSON formátu, pro omezení množiny dat, které mají být změněny.


KSWebAPI_Parameters

Struktura obsahuje parametry:

  • ItemGroup
Povinný údaj. Předává se název skupiny údajů (entity) v KS mzdy (např. 'KmenoveUdaje').
  • Items
Vyplňuje se v případe volání metody GetData. Předává se seznam položek, které budou v návratové datové struktuře, na které má uživatel oprávnění. Jednotlivé položky se oddělují čárkou (Příklad: OsCislo, Jmeno, Prijmeni).
  • JsonChangeData
Vyplňuje se v případe volání metody InsertData nebo UpdateData. V JSON struktuře se předávají data, která mají být zapsána do databáze KS mzdy. Vždy se jedná o JSON pole.
  • JsonSearchCriteria
Slouží k předání vyhledávacích kritérií pro omezení množiny zpracovávaných údajů. Podmínka se zapisuje v JSON formátu. Vyhledávací kritérium se skládá z výrazů (výraz obsahuje atributy 'Item', 'Operator', 'Value'), přičemž může být zadán buď jediný výraz nebo složený, oddělený logickými operátory.

Přípustné logické operátory: OR, AND

Přípustné operátory porovnání: =, <=, >=, >, <, LIKE, NOT LIKE, IN, NOT IN

Příklady

1 (jednoduchý výraz) 

[
    { "Item": "OsCislo", "Operator": "<=", "Value": 100 }
]

1 AND 2 

[
    { "Item": "OsCislo", "Operator": "<=", "Value": 100 },
    "AND",
    { "Item": "DatumNastupu", "Operator": ">=", "Value": "2000-01-01" }
]

1 OR 2 

[
    { "Item": "Jmeno", "Operator": "=", "Value": "Karel" },
    "OR",
    { "Item": "Jmeno", "Operator": "=", "Value": "Marie" }
]

(1 OR 2) AND (3 OR 4) 

[
    [
        { "Item": "DatumNastupu", "Operator": "=", "Value": "2000-01-01" },
        "OR",
        { "Item": "DatumNastupu", "Operator": "=", "Value": "2010-01-01" }
    ],
    "AND",
    [
        { "Item": "Jmeno", "Operator": "=", "Value": "Karel" },
        "OR",
        { "Item": "Jmeno", "Operator": "=", "Value": "Marie" }
    ]
]

1 OR (2 AND (3 OR 4)) 

[
    { "Item": "DatumNastupu", "Operator": "=", "Value": "2000-01-01" },
    "OR",
    [
        { "Item": "DatumNastupu", "Operator": "=", "Value": "2010-01-01" },
        "AND",
        [
            { "Item": "Jmeno", "Operator": "=", "Value": "Karel" },
            "OR",
            { "Item": "Jmeno", "Operator": "=", "Value": "Marie" }
        ]
    ]
]

KSWebAPI_Response

Struktura obsahuje parametry:

  • ResponseDatetime
Datum a čas odpovědi.
  • StatusCode
Stav odpovědi. 200 – OK, 500 – chyba.
  • Message
Zpráva odpovědi.
  • IsError
Indikace zda nastala chyba.
  • ErrorMessage
Chybová zpráva o chybovém stavu při zpracování metody.
  • Data
Data ve formátu JSON.

Autentizace

Pro ověření uživatele se používá UserName autentizace, kdy se předává jméno a heslo uživatele při volání metody webové služby v části ClientCredentials. Tato metoda musí být nastavena v konfiguračním souboru klienta.

Příklady

<security>
  <message clientCredentialType="UserName" />
</security>

Uživatelé se evidují v okně 'Správa uživatelů'

Sprava-uzivatelu-KS-WEBAPI.jpg

Aplikační server

Aplikační server (dále AS) je samostatný program, který běží jako Windows služba a mimo jiné zajišťuje hostování webové služby KS WebAPI.

Instalace

Z uložiště KS - program je potřeba stáhnout poslední verzi aplikace MaPSetup, která slouží k instalaci AS: http://download.ksprogram.cz/download/MaPSetup.zip.

V instalaci pokračujte podle příručky: Aplikační_server_KS


Konfigurace KS WebAPI

Konfigurace KS WebAPI se provádí převážně v konfiguračním souboru AS. Některá nastavení (např. Správa uživatelů KS WebAPI) se provádí v aplikaci AS SeanceMAnager.

Konfigurační soubor

Konfigurace KS WebAPI se provádí v konfiguračním souboru AS 'ASServer.exe.config'. Soubor je uložen v adresáři 'ASServer', v umístění instance AS, které bylo vybráno pro instalaci AS.

V konfiguračním souboru se nastaví Endpoint, Binding, Behavior, případně jiná nastavení.

Níže je uvedena vzorová konfigurace, která využívá zabezpečení s ověřením uživatelského jména na straně klienta a proto je potřeba nastavit certifikát v části <serviceCertificate>


Vzorová konfigurace 

<system.serviceModel>
  <services>  
    <service name="KSProgram.AS.WCF.KSWebAPI" behaviorConfiguration="KSWebAPIBehavior">
      <host>
        <baseAddresses>
          <add baseAddress="http://localhost:9001/KSAsServer/WebService/WebAPI"/>
        </baseAddresses>
      </host>

      <endpoint address=""
                binding="wsHttpBinding"
                bindingConfiguration="KSWebAPIBinding"
                contract="KSProgram.AS.WCF.IKSWebAPI" />
    </service>
  </services>
  <bindings>
      <wsHttpBinding>
        <binding name="KSWebAPIBinding">
      <security mode="Message">
   <message clientCredentialType="UserName" />
 </security>
 <readerQuotas maxDepth="2147483647" maxStringContentLength="2147483647"
        maxArrayLength="2147483647"   
        maxBytesPerRead="2147483647" maxNameTableCharCount="2147483647" />
</binding>
      </wsHttpBinding>
    </bindings>

    <behaviors>
      <serviceBehaviors>
        <behavior name="KSWebAPIBehavior">
  <serviceMetadata httpGetEnabled="true"/>
  <serviceDebug includeExceptionDetailInFaults="true"/>
  <serviceCredentials>
      <userNameAuthentication userNamePasswordValidationMode="Custom"  
             customUserNamePasswordValidatorType="KSProgram.AS.WCF.PasswordValidator, WCFLib"/>
   <serviceCertificate findValue="WebAPI_cert" storeLocation="LocalMachine"  
             storeName="My" x509FindType="FindBySubjectName"/>
  </serviceCredentials>
</behavior>
      </serviceBehaviors>
    </behaviors>
</system.serviceModel>


AS SeanceManager

AS SeanceManager (dále ASSM) je aplikace, která byla nainstalována společně s AS a slouží ke správě AS (spouštění instancí AS, konfigurace úloh, kontrola stavu úloh, atd.), viz obr. 1. ASSM je umístěn v adresáři, který byl vybrán pro instalaci AS (…\KS-AS\ASSeanceManager\ASSeanceManager.exe).

V případě KS WebAPI je zde typ úlohy 'Webová služba KSWebAPI' (Kód = 73) v seznamu Typy úlohy. V části 'Nastavení webové služby' se provádí nastavení uživatelských účtů pro autentizaci.

ASSM (soubor ASSeanceManager.exe) je nutné spouštět jako správce.

Nastaveni-as-seancemanager-webapi.jpg

Správa uživatelů

V AS SeanceManager se provádí nastavení uživatelských účtů pro autentizaci. V sekci 'Nastavení webové služby' se po stisku tlačítka 'Správa uživatelů' otevře příslušné okno .

Sprava-uzivatelu-KS-WEBAPI.jpg

Pristupova-prava-polozky-ks-webapi.jpg

Citováno z „http://prirucky.ksprogram.cz/index.php?title=Kuba1&oldid=41441“