Book Contents

Book Index

K2 API - webové služby K2

Book Contents

Book Index

Ú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.

pic_3917

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ěží.

Book Contents

Book Index

Instalace a základní nastavení

Prerekvizity

AS3USER='AN'
AS3PASSWORD='ANPassword'
AS3USERS=5
AS3IO=2000034152

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ů:

Nejčastější problémy při instalaci a konfiguraci K2 API

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).

Book Contents

Book Index

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}

Book Contents

Book Index

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.

Book Contents

Book Index

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:

  1. {classname} – název třídy datového objektu (např. TD_Part), nebo alias (tedy alternativní název, např. Part)
  2. 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).
  3. 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).
  4. 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.
  5. page - proměnná ovládá posun na jiné stránky - možné hodnoty jsou last, prev, next, first
  6. 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.
  7. orOperator – určuje logickou spojku mezi jednotlivými podmínkami v conditions
  8. conditions – slouží pro filtrování dat (tedy sestavování výběrů nad datovým modulem).

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:

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:

Struktura těla požadavku:

Struktura odpovědi:

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:

Struktura těla požadavku:

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:

Book Contents

Book Index

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.

Book Contents

Book Index

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:

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:

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:

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>

Book Contents

Book Index

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));

}

Book Contents

Book Index

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:

  1. httpRuntime.maxRequestLength v sekci system.web – obecné nastavení maximální velikosti http požadavku. Hodnota je uváděna v kB.
  2. 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.
  3. 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.
  4. 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: