K2 API - webové služby K2
Úvod
K2 API je webová aplikace běžící na webovém serveru Microsoft Internet Information Services (IIS). Prostřednictvím aplikačního serveru K2 zpřístupňuje data informačního systému K2 a umožňuje spouštění skriptů a sestav.
Webové služby jsou založeny na technice REST, tzn. komunikace probíhá pomocí protokolu HTTP a standardních metod GET (čtení dat), POST (vytváření dat), PUT (modifikace existujících dat).
Data je možné číst a posílat buď ve formátu XML nebo JSON.
Po zadání kořenové URL adresy K2 API do prohlížeče je možné procházet základní popis služeb a prostředků/operací pomocí dynamické nápovědy.
Obr.: Dynamická nápověda K2 API
Poznámka: Pokud se objeví tato stránka, znamená to, že již proběhla prvotní komunikace K2 API s aplikačním serverem. Pokud se místo ni objeví chybová stránka IIS, znamená to, že se komunikace nezdařila a s největší pravděpodobností je chyba v konfiguraci K2 API nebo aplikační server K2 neběží.
Instalace a základní nastavení
Prerekvizity
- V licenci K2 musí být dostupné alespoň jedno vlákno K2 API (položka Počet sdílených uživatelů) a v K2 založen odpovídající počet tzv. anonymních uživatelů s loginem složeným se shodného prefixu a na konci doplněným o pořadové číslo (např. „AN1“ – „AN5“). Tito uživatelé musí mít shodně nastavená práva i shodné heslo.
- Nainstalovaný a spuštěný aplikační server se zatržením „Konfigurovat aplikační server pro server webových služeb“ při instalaci. Pokud tato volba při instalaci nebyla zatržena, je možné u existující instalace AS doplnit v konfiguračním souboru K2.INI tyto parametry (příklad pro 5 vláken a uživatele pojmenované AN1 – AN5) :
AS3USER='AN'
AS3PASSWORD='ANPassword'
AS3USERS=5
AS3IO=2000034152
- Server, na kterém bude K2 API instalován, musí být k dispozici IIS s nainstalovanou podporou ASP.NET a WCF. Při instalaci IIS je nutné zvolit zejména tyto součásti:
- Role: Výchozí + Vývoj aplikací (.NET 4.5, ASP.NET 4.5), Nástroje pro správu (včetně kompatibility IIS 6); Nezatrhávat: Publikování WebDAV
- Funkce: Aktivační služba (Model procesu), Služby WCF (aktivace HTTP), .NET 4.5, ASP.NET 4.5
- V případě HTTPS instalace korektně nastavený certifikát v IIS
- V případě publikace K2 API pro přístup přes internet, povolené použité HTTP/HTTPS porty (standardně 80/443)
Doporučené nasazení pro přístup ke K2 API z internetu
K2 aplikační server by měl být vždy instalován na serveru dostupném pouze ve vnitřní síti. K2 API a případné další webové aplikace je doporučeno instalovat na samostatný server, který je dostupný z internetu a má omezený přístup do interní sítě povolující pouze komunikace s K2 AS.
Instalace K2 API
Provádí se pomocí K2 instalátoru. Instalační program K2 API před začátkem instalace kontroluje dostupnost základních vyžadovaných součástí, případně upozorní na chybějící součásti a instalace je zastavena.
Během instalace je potřeba zadat několik údajů:
- Cílový adresář – je možno zvolit libovolný adresář, nemusí být v root adresáři IIS
- Název IIS serveru – zadat název, pomocí kterého se bude k serveru s K2 API přistupovat. Pro testovací instalace je možno zadat i „localhost“ – pod tímto názvem ale bude K2 API dostupný pouze na daném serveru.
- Webová stránka na IIS (Web Site) – zvolte, do které Web Site chcete K2 API nainstalovat. Standardně je na IIS k dispozici pouze „Default Web Site“
- Název aplikace na IIS – část URL adresy ke K2 API za názvem serveru. Pokud bude název serveru „mujserver.cz“ a jako název aplikace uvedete „restservice“, pak základní URL pro přístup k K2 API bude http://mujserver.cz/restservice
- Název nebo IP adresa počítače, kde běží K2 AS
- Název instance K2 AS – zadáváno při instalaci K2 AS
Nejčastější problémy při instalaci a konfiguraci K2 API
- Chybný název nebo IP adresa serveru s AS nebo chybný název instance AS – zkontrolovat a případně upravit ručně v konfiguračním souboru K2 API – soubor web.config v instalačním adresáři K2 API. Zkontrolovat, zda nic neblokuje síťovou komunikaci mezi server s K2 API a serverem s AS
- AS není nakonfigurován pro K2 API – doplnit konfiguraci viz. část Prerekvizity výše
- Chybí anonymní uživatelé nebo jsou zakázáni - viz. část Prerekvizity výše
- V licenci K2 není uveden počet sdílených uživatelů nebo je tento počet překročen – aktualizovat licenci K2
- Chybějící součásti IIS – zkontrolovat součásti IIS, viz. část Prerekvizity výše
Ve většině případů pomůže logování K2 API případně AS. Zapnutí logování K2 API se provádí v konfiguračním souboru web.config, parametry LogPath (cesta k log souboru), LogLevel (typy zpráv, které mají být zaznamenávány, pro ladění doporučeno alespoň Info), LogRequests (umožňuje sledovat zpracovávání jednotlivých požadavků na K2 API i v případě souběhu více požadavků najednou).
Struktura URL adresy
Pomocí URL adresy určujeme prostředek (nejčastěji data, určitý záznam), se kterým chceme pracovat, nebo operaci, kterou chceme spustit.
Základní formát URL:
<adresa serveru>/{xml/}<název služby>/<prostředek nebo operace>{?volitelné parametry}
- <adresa serveru> je kořenová adresa K2 API. Například http://mujserver.cz/restservice
- {xml/} – volitelný přepínač. Pokud je v URL uveden, požadujeme výstup ve formátu XML, pokud není uveden, požadujeme formát JSON
- <název služby> - určení konkrétní služby K2 API, kterou chceme používat
- <prostředek nebo operace> - určení konkrétního požadavku
- {?volitelné parametry} – případné parametry specifické pro daný požadavek
Webové služby
Data - Služba sloužící pro práci s datovými objekty (datovými moduly).
Meta – Služba umožňující získání popisu struktury datových objektů.
Formation – Umožňuje spouštět skripty a sestavy.
FormationDefinition – Umožňuje získat definice skriptů a sestav.
Eshop – Sdružuje speciální prostředky a operace pro K2 eshop.
Notification – Podpora pro notifikace.
Služba Data
Slouží pro práci s daty (datovými objekty) uloženými v K2.
Seznam záznamů datového objektu
GET /Data/{classname}?<volitelné parametry>
Požadavek slouží k přečtení seznamu datových objektů typu {classname}. Seznam je stránkovaný, najednou se nečtou všechny záznamy. Pokud není volitelnými parametry určeno jinak, vrátí se prvních 30 záznamů s hodnotami implicitních sloupců a všech složek primárního klíče.
Parametry:
- {classname} – název třídy datového objektu (např. TD_Part), nebo alias (tedy alternativní název, např. Part)
- fields – čárkou oddělený seznam názvů datových polí, jejichž hodnotu požadujeme vrátit. Lze zadávat i cestu k polím přes vazbu nebo název položkového modulu následovaný názvem pole z položkového data objektu (jednotlivé názvy polí cesty se oddělují tečkou).
- orderBy – čárkou oddělený seznam názvů datových polí, podle kterých chceme data setřídit. Pro sestupné řazení je nutné před název pole uvést znak - (mínus).
- pageSize – požadovaný počet záznamů na jednu stránku (kolik záznamů se maximálně vrátí v jedné odpovědi). Při uvedení hodnoty -1 bude stránkování zakázáno a vrátí se všechny záznamy najednou.
- page - proměnná ovládá posun na jiné stránky - možné hodnoty jsou last, prev, next, first
- pageState – interní proměnná identifikující aktuální stránku. Hodnota této proměnné (resp. celá URL adresa) se vždy vrací v odpovědi serveru.
- orOperator – určuje logickou spojku mezi jednotlivými podmínkami v conditions
- conditions – slouží pro filtrování dat (tedy sestavování výběrů nad datovým modulem).
- Jednotlivé podmínky mají tento tvar:
- field;[!]LT|LE|GT|GE|EQ|NE[@];"value"|value
- field;[!]EMPTY
- field;[!]LIKE[*][^][#];"value"|value
- field;[!]IN;"value1"|value1[;"value2"|value2]...
- field;[!]BETWEEN;"valueFrom"|valueFrom;"valueTo"|valueTo
- field – název nebo cesta k datovému poli
- ! – negace podmínky
- @ - místo konstanty v parametru je očekáván název nebo cesta k jinému datovému poli, jehož hodnota se má pro porovnání použít
- value – hodnota operandu
- "value" – hodnota operandu, pokud je v ní potřeba použít znak oddělovače (čárka nebo středník)
- Možné operátory:
- LT – menší
- LE – menší nebo rovno
- GT – větší
- GE – větší nebo rovno
- EQ – rovno
- NE – nerovno
- EMPTY – hodnota pole je prázdná (nezadaná)
- IN – v množině
- BETWEEN – mezi
- LIKE – Porovnávání textových řetězců (podmínka „obsahuje“, „začíná“, apod.)
- • znak * za operátorem LIKE znamená povolení zástupných znaků v hodnotě. V hodnotě se pak na místě znaku * může vyskytovat libovolný znak(y). Pokud není uvedeno LIKE*, znak * v hodnotě se bere opravdu jako součást hodnoty.
- • znak ^ za operátorem LIKE zapíná rozlišování malých a velkých písmen.
- • znak # za operátorem LIKE znamená přepnutí podmínky do režimu „začíná“. Při vyhodnocení podmínky je před zadanou hodnotu automaticky doplněn zástupný znak.
Poznámka: Jako název pole lze ve všech parametrech používat jak ProgName, tak AliasName (zpravidla ProgName přeložený do angličtiny). V odpovědi K2 API se vždy vrací AliasName.
Struktura opdovědi:
<PagedList>
<Items> // Seznam datových objektů třídy {classname}
</Items>
<FirstPageURL /> // URL adresa první strany
<NextPageURL /> // URL adresa následující strany
<PrevPageURL /> // URL adresa předchozí strany
<LastPageURL /> // URL adresa poslední strany
<RequestedFields /> // názvy vrácených datových polí (např. implicitní sloupce)
</PagedList>
Příklady:
http://localhost/WS136/xml/Data/Part - vrátí prvních 30 partnerů s implicitními sloupci, seřazené podle primárního klíče.
http://localhost/WS136/xml/Data/Part?fields=Name,ID_NO,Group.Abbr,EAddress.FullEAddress&orderBy=Name&pageSize=10 – vrátí prvních 10 partnerů seřazených podle názvu s těmito poli: název, IČO, zkratka skupiny, ke každému všechny položky elektronických adres (hodnotu pole FullEAddress).
http://localhost/WS136/xml/Data/Part?conditions=PartnerId;GT;10,Abbr1;LIKE*;Shell* - vrátí prvních maximálně 30 partnerů, pro které platí, že číslo partnera je větší než 10 a zároveň zkratka začíná na „Shell“.
POST /Data/GetList/{classname}
Jde o alternativu předchozího volání. V těle POST požadavku je očekáván objekt DataParameterFields se stejnými parametry, jako je možné zadat v URL adrese GET požadavku. Toto volání řeší omezení maximální délky URL adresy v případě složitých dotazů.
Struktura těla požadavku:
<DataParameterFields xmlns="K2.Data">
<Conditions></Conditions>
<Fields></Fields>
<OrderBy></OrderBy>
<Page></Page>
<PageSize></PageSize>
<PageState></PageState>
<orOperator></orOperator>
</DataParameterFields>
Detail konkrétního datového objektu
GET /Data/{classname}/{*PrimaryKeys}/?<volitelné parametry>
Slouží k přečtení detailu jednoho konkrétního záznamu určeného pomocí primárního klíče.
Parametry:
- {classname} – název třídy datového objektu (např. TD_Part), nebo zkrácený název (Part)
- {*PrimaryKeys} – složky primárního klíče oddělené znakem /. Pro dvousložkový například /Data/{classname}/první složka/druhá složka
- fields - čárkou oddělený seznam názvů datových polí, jejichž hodnotu požadujeme vrátit. Lze zadávat i cestu k polím přes vazbu nebo název položkového modulu následovaný názvem pole z položkového data objektu (jednotlivé názvy polí cesty se oddělují tečkou).
Struktura odpovědi:
<DataObjectWrapper>
<DOClassName /> // classname vráceného datového objektu
<FieldValues> // kolekce s hodnotami datových polí
<NameValue> // jedno datové pole
<Name></Name> // název datového pole (alias)
<Value></Value> // hodnota datového pole nebo odkazovaný datový objekt <NoPermission /> // příznak, že uživatel nemá právo na hodnotu pole
</NameValue>
...
</FieldValues>
<ItemURL /> // URL adresa detailu tohoto datového objektu
</DataObjectWrapper>
Poznámka: Příznak NoPermission se objeví nastavený na hodnotu true pouze v případě, že hodnotu pole nelze získat z důvodu vyhodnocení práv na čtení daného pole. V tomto případě se neposílá žádná hodnota pole – vlastnost Value.
Příklad:
http://localhost/WS136/xml/Data/Part/15 - vrátí detail záznamu partnera s číslem 15 s datovými poli podle implicitních sloupců.
Vytvoření nového záznamu
POST /Data/{classname}?<volitelné parametry>
Odeslání datového objektu, který má být vytvořen a uložen do databáze K2. V odpovědi se vrací detail uloženého záznamu.
Parametry:
- {classname} – název třídy datového objektu (např. TD_Part), nebo zkrácený název (Part)
- fields - čárkou oddělený seznam názvů datových polí, jejichž hodnotu požadujeme vrátit. Lze zadávat i cestu k polím přes vazbu nebo název položkového modulu následovaný názvem pole z položkového data objektu (jednotlivé názvy polí cesty se oddělují tečkou).
Struktura těla požadavku:
- objekt DataObjectWrapper se zadanými hodnotami datových polí
Struktura odpovědi:
- Shodná jako u čtení detailu konkrétního záznamu pomocí metody GET
Změna existujícího záznamu
PUT /Data/{classname}/{*PrimaryKeys}/?<volitelné parametry>
Odeslání modifikovaného datového objektu zpět do databáze K2. V odpovědi se vrací detail uloženého záznamu.
Postup modifikace existujícího záznamu probíhá tak, že si zpravidla nejprve datový objekt přes K2 API přečteme, upravíme hodnoty jeho polí a pomocí tohoto požadavku pošleme zpět k uložení. Při tom je důležité vždy načíst a předat zpět hodnotu datového pole „TimeStamp“ (resp. všech systémových polí – více v popisu detailní struktury datového objektu služby Meta). Pokud hodnota pole TimeStamp (resp. hodnoty systémových polí) nebudou odeslány zpět, operace skončí s chybou. Kontrola pole TimeStamp je zavedena kvůli zamezení kolizím při současné změně záznamu více uživateli (tedy pokud mezi tím, co se datový objekt načetl, a voláním uložení došlo k jeho úpravě někým jiným).
Při editaci vlastněných položek je možné konkrétní položku označit příznakem „Deleted“. Po odeslání na K2 API pak dojde v rámci ukládání změn v hlavičce a položkách i k odstranění dané položky. Editovaná nebo odstraňovaná položka musí mít v požadavku uvedené všechny složky svého primárního klíče.
Parametry:
- {classname} – název třídy datového objektu (např. TD_Part), nebo zkrácený název (Part)
- {*PrimaryKeys} – složky primárního klíče oddělené znakem /. Pro dvousložkový například /Data/{classname}/první složka/druhá složka
- fields - čárkou oddělený seznam názvů datových polí, jejichž hodnotu požadujeme vrátit. Lze zadávat i cestu k polím přes vazbu nebo název položkového modulu následovaný názvem pole z položkového data objektu (jednotlivé názvy polí cesty se oddělují tečkou).
Struktura těla požadavku:
- objekt DataObjectWrapper se zadanými hodnotami datových polí
Příklad se smazáním položky:
<DataObjectWrapper xmlns="K2.Data" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<DOClassName>Part</DOClassName>
<FieldValues>
…
<NameValue>
<Name>ListBusinessChild</Name>
<Value i:type="ChildDataObjectWrapper">
<Items>
<Item>
<DOClassName>MBusiness</DOClassName>
<Deleted>true</Deleted>
<FieldValues>
<NameValue>
<Name>RID</Name>
<Value i:type="a:long" xmlns:a="http://www.w3.org/2001/XMLSchema">8495445311489</Value>
</NameValue>
</FieldValues>
</Item>
</Items>
</Value>
</NameValue>
</FieldValues>
</DataObjectWrapper>
Struktura odpovědi:
- Shodná jako u čtení detailu konkrétního záznamu pomocí metody GET
Služba META
Slouží k získání struktury datových objektů
Seznam dostupných datových objektů zveřejněných pro K2 API
GET /Meta
Struktura odpovědi:
<ArrayOfDataObjectMetaData>
<DataObjectMetaData> // informace o jedné třídě datového objektu
<Caption /> // zobrazovaný název
<ClassName /> // classname – název třídy používaný v URL
<IsHeader /> // příznak, zda jde o hlavičkový typ objektu
<V3ClassName /> // interní název třídy datového objektu (třída DM)
</DataObjectMetaData>
...
</ArrayOfDataObjectMetaData>
Detailní struktura konkrétního datového modulu
GET /Meta/{classname}
Struktura odpovědi:
<DataObjectMetaData>
<Caption /> // zobrazovaný název
<ChildList /> // seznam položkových polí datového objektu
<ClassName /> // classname – název třídy používaný v URL
<FieldList /> // seznam skalárních polí datového objektu
<IsHeader /> // příznak, zda jde o hlavičkový typ objektu
<LinkList /> // seznam vazebních polí datového objektu
<PrimaryKeyFieldList /> // seznam polí primárního klíče
<SystemFields /> // seznam polí, které je nutné přenášet při změněxexistujícího datového objektu
<V3ClassName /> // interní název třídy datového objektu (třída DM)
</DataObjectMetaData>
Prvky seznamů ChildList, FieldList, LinkList, PrimaryKeyFieldList a SystemFields jsou objekty FieldMetaData:
<FieldMetaData>
<Caption /> // Záhlaví pole
<Description /> // Popis pole
<Name /> // Pojmenování pole
<FieldName /> // Název pole pro URL a označení v datech
<V3FieldName /> // Odpovídající název pole v K2 (ProgName)
<ValueType /> // Typ hodnoty pole, může být: Date, Time, DateTime, Bitmap, Numeric
<IsRequired /> // Povinné pole pro uložení
<IsReadOnly /> // Pole je pouze pro čtení
<LinkClassName /> // Název (classname) typu datového objektu vazebního pole
<LinkV3ClassName/> // Odpovídající název datového modulu vazebního pole
<ChildClassName /> // Název (classname) typu datového objektu položek
<ChildV3ClassName/> // Odpovídající název datového modulu položek
<KeyIndex /> // Pořadové číslo pole v primárním klíči
<ItemURL /> // Odkaz na definici odpovídajícího typu datového objektu, používá se pro vazební a položková pole
</FieldMetaData>
Poznámka: Kolekce SystemFields je k dispozici až od verze K2.point. Všechna pole uvedená v této kolekci je nutné při editaci načíst a posílat v požadavku na uložení změn zpět. Bez nich K2 API nedovolí záznam uložit.
Služba Formation
Slouží pro získání seznamu dostupných skriptů a sestav a k jejich spouštění.
Všechny skripty a sestavy používané přes K2 API musí být upraveny pro běh na aplikačním serveru K2 a označeny jako AS3Compatible. Dále musí být umístěny v databázi (modul Skripty, sestavy), nemohou být v souborovém systému. Mohou být také přiřazeny ke konkrétnímu datovému modulu, nad kterým má smysl je spouštět.
Seznam dostupných skriptů a sestav
GET /Formation?<volitelné parametry>
Parametry:
- ClassName – bez uvedení tohoto parametru se vrací seznam všech skriptů a sestav. Pokud je parametr uveden, vrací se pouze skripty a sestavy přiřazené k danému typu datového objektu a skripty bez uvedeného přiřazení.
Struktura odpovědi:
<ArrayOfFormationId>
<FormationId> // popisný objekt skriptu
<DefinitionURL /> // URL adresa pro detail definice skriptu/sestavy
<FormationID /> // Název souboru skriptu/sestavy
<ItemURL /> // URL adresa pro spuštění skriptu/sestavy
<Name / > // Název skriptu/sestavy
</FormationId>
...
</ArrayOfFormationId>
Spuštění skriptu nebo sestavy bez určení dat
Při tomto typu spuštění se skriptu nepředává AktDM, skript s ním tedy nemůže pracovat. V případě skriptu jsou vráceny standardně výstupní parametry (ty, jejichž hodnota byla za běhu skriptu změněna) nebo soubor PDF v případě spuštění sestavy.
GET /Formation/{folder}/{name}/{ext}?<parametry skriptu>
Parametry:
- {folder} – název adresáře (Special/Standard)
- {name} – název souboru skriptu/sestavy
- {ext} – přípona (pas pro skripty, am pro sestavy)
- <parametry skriptu> - do URL lze zadat parametry skriptu ve tvaru parametr=hodnota.
- returnOutFileData – volitelný parametr pro spouštění sestav a skriptů vracejících soubor. V případě nastavení na „true“ se místo URL adresy ke stažení souboru budou vracet přímo binární data souboru v BulkData odpovědi.
Struktura odpovědi:
<FormationOutput>
<URL /> // URL adresa výstupního souboru
<Parameters> // hodnoty výstupních parametrů
<Parameter>
<Name /> // Název parametru
<Value /> // Hodnota parametru
</Parameter>
...
</Parameters>
<BulkData /> // výstupní binární data
</FormationOutput>
Příklad:
http://localhost/WS136/xml/Formation/Standard/WkfWSProcDef/PAS?DefTypeAbbr=TEST – spustí skript ::\\DBNAME\Standard\WkfWSProcDef.PAS a nastaví mu parametr DefTypeAbbr na hodnotu „TEST“.
Spuštění skriptu s určením dat
Na rozdíl od předchozího umožňuje před spuštěním poslat definici dat, nad kterými má být sestava nebo skript spuštěn, a také poslat hodnoty parametrů. Zbylé chování zůstává stejné.
POST /Formation/{folder}/{name}/{ext}
Struktura těla požadavku:
<FormationInput>
<Conditions /> // podmínky výběru (formát jako v URL adrese)
<CurrentPrimaryKey> // definice primárního klíče záznamu pro spuštění
<Segment>
<Name /> // název datového pole
<Value /> // hodnota datového pole
</Segment>
</CurrentPrimaryKey>
<DataObjectName /> // classname datového objektu
<ORConditions /> // true – mezi podmínkami je OR, false - AND
<Parameters> // hodnoty parametrů skriptu
<Parameter>
<Name /> // Název parametru
<Value /> // Hodnota parametru
</Parameter>
</Parameters>
<PrimaryKeys> // seznam primárních klíčů záznamů pro spuštění
<PrimaryKey>
<Segment>
<Name />
<Value />
</Segment>
</PrimaryKey>
</PrimaryKeys>
<ReturnUrl /> // true – vrátit URL adresu výstupního souboru (např. PDF s výstupem sestavy)
</FormationInput>
Spuštění skriptu s HTML výsledkem
Umožňuje spustit skript, který vygeneruje HTML stránku a tuto stránku rovnou zobrazit v prohlížeči.
GET /Formation/html/{folder}/{name}/pas
Komplexní příklad tohoto volání webové služby ukazuje standardní skript Příklad 127 - generování HTML pro web. služby K2.
Spuštění skriptu nebo sestavy a stažení výstupního souboru
Umožňuje spustit sestavu nebo skript vytvářející soubor a tento soubor pak přímo stáhnout. Po zadání URL do prohlížeče dojde k zobrazení dialogu prohlížeče pro uložení/otevření souboru. V případě skriptu je možné pomocí skriptové procedury SetOutFileName nastavit i název stahovaného souboru.
GET/POST /Formation/download/{folder}/{name}/{ext}
Případné parametry skriptu lze zadávat v URL adrese (případ GET metody) nebo v těle POST požadavku.
Příklad spouštěného skriptu:
program TestDownload;
info
Title = 'TestDownload';
As3Compatible = true;
end;
modules
DM: TD_Job;
var
Exec: TAmExecutorNonVisual;
begin
DM.CreateDm;
DM.SetState(tfNormal, DM.PrimaryKey, False);
Exec := TAmExecutorNonVisual.Create;
try
Exec.AktDm := DM;
Exec.OpenCachedReport('TaskList.AM');
Exec.Execute;
Exec.ToExport('', 0, 9999, extyXLS, exdeToFile, prinPath + '\TasksList.xls');
SetOutFileName(prinPath + '\TasksList.xls');
finally
Exec.Free;
end;
end.
Ošetření chyby při práci s K2 API
Chyby, které nastanou při deserializaci těla požadavků ještě před zavoláním kódu webové služby ošetřuje .NET a vrací status BadRequest, aniž by se daly zjistit bližší detaily chyby. Tato chyba je vrácena v html formátu.
Chyba, která nastane v kódu K2 API případně na aplikačním serveru je vrácena jako textová odpověď ve formátu: [ErrorKind]ErrorText.
ErrorKind – Výčet určující typ chyby:
- AS3Message - může nastat při zpracování sestavy nebo skriptu
- AS3Warning - může nastat při zpracování sestavy nebo skriptu
- AS3Error - při zpracování požadavku aplikačním serverem došlo k chybě
- AS3Terminated - jedná se o kritickou chybu aplikačního serveru, relace pod kterou byl požadavek zpracováván, byla ukončena z důvodu ukončení běhu aplikačního serveru nebo chybě sítě mezi aplikačním serverem a databázovým serverem.
- RequestError – chyba při zpracovávání požadavku K2 API. Nejčastěji jde o chybě specifikovaný požadavek (status BadRequest). Status Unauthorized znamená chybu ověření uživatele.
- CommunicationError – nastala chyba komunikace mezi K2 API a aplikačním serverem.
- UnknownError – neidentifikovaná chyba
ErrorText – bližší popis vzniklé chyby.
Příklad volání speciálního skriptu
Příklad skriptu
program PrikladWS(
ParamText {$DESC 'Vstupní textový parametr'}: string = '';
ParamCislo {$DESC 'Vstupní číselný parametr'}: integer = 0;
Vystup {$DESC 'Výstupní parametr'}: string = ''
);
info
Title = 'Příklad WS';
AS3Compatible = true;
end;
modules
TD_Part;
begin
Vystup := 'Předány byly hodnoty: ParamText=' + ParamText + ', ParamCislo=' + IntToStr(ParamCislo) + ', Vystup=' + Vystup;
if (AktDM is TD_Part) then begin
Vystup := Vystup + ', AktDM=' + Trim(TD_Part(AktDM).Zkratka1);
end;
WriteLn(DateTimeToStr(Now) + ': ' + Vystup);
end.
Skript musí být uložen v databázi (kniha Skripty a sestavy) jako PrikladWS.pas. V sekci info musí být AS3Compatible nastaveno na true. Nastavením tohoto parametru autor skriptu potvrzuje, že ověřil přeložitelnost a spustitelnost skriptu na AS (tj. ze skriptu odstranil veškeré vizuální části a skript může běžet ve vícevláknovém prostředí AS).
Tento skript do výstupního parametru Vystup vloží text se vstupními hodnotami všech parametrů skriptu, a pokud je skript spuštěn nad datovým modulem partnerů, přidá i zkratku aktuální partnera. Aktuální datum a čas a stejný text zapíše na standardní výstup skriptu (v adresáři aktuálního uživatele K2 vznikne textový soubor K2Export.txt s tímto textem).
Příklad volání GET požadavkem
Předány jsou pouze hodnoty parametrů skriptu, AktDm ve skriptu není nastaven
URL:
http://localhost/WS136/xml/Formation/Special/PrikladWS/pas?ParamText=aaa&ParamCislo=123
Výsledná odpověď:
<FormationOutput xmlns="K2.Data" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Parameters>
<Parameter>
<Description/>
<Name>Vystup</Name>
<Value i:type="a:string" xmlns:a="http://www.w3.org/2001/XMLSchema">Předány byly hodnoty: ParamText=aaa, ParamCislo=123, Vystup=</Value>
</Parameter>
</Parameters>
</FormationOutput>
Příklad volání POST požadavkem
Nastavení AktDm na partnera s číslem 5 a nastavení hodnot parametrů.
URL:
http://localhost/WS136/xml/Formation/Special/PrikladWS/pas
HTTP hlavička:
Content-Type: application/xml; charset=utf-8
Content-Length: 472
Tělo požadavku:
<FormationInput xmlns="K2.Data" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:t="http://www.w3.org/2001/XMLSchema">
<CurrentPrimaryKey>
<Segment>
<Name>CisPart</Name>
<Value i:type="t:integer">5</Value>
</Segment>
</CurrentPrimaryKey>
<DataObjectName>TD_Part</DataObjectName>
<Parameters>
<Parameter>
<Name>ParamText</Name>
<Value i:type="t:string">Zadaný text</Value>
</Parameter>
<Parameter>
<Name>ParamCislo</Name>
<Value i:type="t:integer">12345</Value>
</Parameter>
</Parameters>
</FormationInput>
Poznámka: V hlavičce musí být především uveden „Content-Type“, tedy jaká data K2 API posíláme, a dále v těle musí být u všech Name-Value dvojic u hodnoty specifikován datový typ, aby K2 API při deserializaci věděl, na jaký datový typ má text z XML dokumentu převést.
Výsledná odpověď:
<FormationOutput xmlns="K2.Data" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Parameters>
<Parameter>
<Description/>
<Name>Vystup</Name>
<Value i:type="a:string" xmlns:a="http://www.w3.org/2001/XMLSchema">Předány byly hodnoty: ParamText=Zadaný text, ParamCislo=12345, Vystup=, AktDM=DEMO TRADE</Value>
</Parameter>
</Parameters>
</FormationOutput>
Autentizace požadavků K2 API
K2 API může pracovat v tzv. anonymním režimu pouze kvůli odladění volání služeb. V produkčním prostředí musí být vždy zapnuto vyžadování autentizace. Po instalaci je K2 API standardně v tomto režimu. Přepnutí do anonymního se provádí v konfiguračním souboru web.config v instalačním adresáři K2 API nastavením hodnoty parametru Anonymous na true.
Pro předání a ověření identity je nutné v každém požadavku odesílaném na K2 API uvést standardní http hlavičku Authorization na hodnotu {UserName}:{HMACHash}, kde {UserName} je uživatelské jméno uživatele a {HMACHash} je textový řetězec vytvořený pomocí algoritmu HMAC MD5. Klíčem pro hash je heslo uživatele a hashovaná zpráva je plná URL adresa v nekódované podobě (tedy bez URL kódování speciálních znaků) převedená na velká písmena Výsledný HMAC hash se ještě převede pomocí base64 kódování na text.
Alternativně je možné předat hash i přímo v URL adrese pomocí parametru „x-auth“. V tomto případě se sestaví celá URL požadavku, na konec se připojí &x-auth= a celý text se předá hashovací funkci. Výsledek hashovací funkce se opět připojí na konec tohoto textu.
Příklady
Příklad algoritmu v jazyce Java
public static String calcHMAC(String src, String password)
{
SecretKeySpec sk = new SecretKeySpec(password.getBytes(), "HmacMD5");
Mac mac = Mac.getInstance("HmacMD5");
mac.init(sk);
byte[] result = mac.doFinal(URLDecoder.decode(src, "UTF8").toUpperCase().getBytes());
return Base64.encodeToString(result, Base64.NO_WRAP);
}
Příklad algoritmu v jazyce C#
public static string CalcHMAC(string src, string password)
{
byte[] secretBytes = Encoding.UTF8.GetBytes(password);
HMACMD5 hmac = new HMACMD5(secretBytes);
byte[] dataBytes = Encoding.UTF8.GetBytes(Uri.UnescapeDataString(src).ToUpper());
byte[] computedHash = hmac.ComputeHash(dataBytes);
return Convert.ToBase64String(computedHash);
}
Příklad algoritmu v jazyce Go
func getAuthHeader(source_url string, username string, password string) string { // 1. initialize hmac encoder, key is password hmacEncoder := hmac.New(md5.New, []byte(password))
// 2. url decode & convert to uppercase urlDecoded, _ := url.QueryUnescape(source_url) upperFullURL := strings.ToUpper(urlDecoded)
// 3. hmac encode hmac encoder hmacEncoder.Write([]byte(upperFullURL)) hmacHash := base64.StdEncoding.EncodeToString(hmacEncoder.Sum(nil))
return username + ":" + hmacHash
}
Příklad v K2 skriptu
function CalcHMAC(ASrc, APassword: string): string;
begin
if not CreateHMacMD5HashBase64(AnsiUpperCase(HTTPDecode(ASrc)), APassword, Result) then
Result:= ' ';
end;
Příklad funkce v K2 skriptu pro doplnění hashe přímo v URL
function AppendAuthorizationHeader(aURL: string; aUsername: string; aPassword: string): string;
var
lHash: string;
begin
Result := aUrl;
if (Pos('?', aURL)=0) then
aURL := aURL + '?x-auth='
else
aURL := aURL + '&x-auth=';
if CreateHMacMD5HashBase64(AnsiUpperCase(aURL), aPassword, lHash) then
Result := aURL + HTTPEncode(aUsername + ':' + lHash);
end;
Příklad algoritmu v jazyce PHP
function getAuthorizationHeader($password, $fullUrl) {
return base64_encode(hash_hmac('md5', mb_strtoupper(rawurldecode($fullUrl), 'UTF- 8'), $password, true));
}
Pokročilá konfigurace K2 API
Veškerá konfigurace serveru webových služeb se provádí pomocí obvyklého konfiguračního souboru IIS – web.config. Kromě specifických nastavení K2 API (např. informace o aplikačním serveru, nastavení logování) obsahuje další nastavení IIS a služeb WCF.
Nastavení limitu velikosti požadavku, případně maximální délky URL adresy
V případě odesílání velkých dat pomocí POST nebo PUT požadavku na K2 API lze narazit na omezení maximální velikosti požadavku, které aplikuje výchozí nastavení IIS. Toto omezení se projevuje tak, že K2 API začne odpovídat chybovými zprávami s kódem 4xx, například 400 Not found nebo 413 Entity too large. K2 API od verze move.02 obsahuje výchozí nastavení maximální velikosti přijímaných dat na 50MB. Toto nastavení lze změnit v konfiguračním souboru na těchto místech:
- httpRuntime.maxRequestLength v sekci system.web – obecné nastavení maximální velikosti http požadavku. Hodnota je uváděna v kB.
- requestLimits.maxAllowedContentLength v sekci system.webServer/security/requestFiltering – nastavení modulu IIS „filtrování požadavků“. Tímto parametrem je možné nastavit maximální velikost těla požadavku. Hodnota se uvádí v bajtech.
Element <requestLimits> má i další atributy, např. maxQueryString nebo maxUrl, kterými lze ovlivnit maximální délku parametrů v URL adrese, resp. Celé URL adresy. - binding.maxReceivedMessageSize – nastavení velikosti přijímané zprávy u konkrétního „bindingu“ služby. Hodnota se opět uvádí v bajtech.
Element <binding> se v konfiguračním souboru vyskytuje vícekrát (pro HTTP a HTTPS komunikaci) a je potřeba zpravidla nastavit na všech místech. - Element <readerQuotas> pro binding – lze využít v případě zasílání nadměrně komplikovaných dat (např. hodně vnořených úrovní XML/JSON, dlouhé textové hodnoty elementů v XML)
Konfigurace „bindingů“
Ve standardním konfiguračním souboru jsou uvedeny následující bindingy pro všechny režimy K2 API:
- UnsecureBinding – binding pro REST API přes nezabezpečený http protokol. V případě neuvedení, nebude http protokol podporován.
- ssl – binding pro REST API přes zabezpečený https protokol. V případě neuvedení, nebude https protokol podporován.
- wsUnsecure, wsssl – pro SOAP v1.2 rozhraní služby Formation
- basicUnsecure, basicssl – pro SOAP v1.1 rozhraní služby Formation