Postupy volání datových služeb
Metodika připojení k datovým službám je postavena na standardním řešení webových služeb (web services) a je podřízena standardům této oblasti. Komunikace prostřednictvím webových služeb je synchronní (on-line), takže odpověď na příslušný dotaz obdržíte vždy přímo v daném spojení. Základní charakteristiky tedy jsou:
- Komunikační protokol: HTTP/HTTPS
- Datový/komunikační formát: XML
- Typ spojení: synchronní (on-line)
- Metoda odesílání requestu: POST
- Kódová stránka: UTF-8
- content type v HTTP hlavičce: text/xml;charset=UTF-8
- Pro vlastní komunikace se využívá základní komunikační obálka standardu SOAP 1.1. ( příklad (1 kB))
- V případě požadované vyšší míry zabezpečení (individuálně dle služby) je součástí SOAP obálky i struktura obsahující požadované identifikační údaje, a to ve struktuře:
- vOKO WSS Token (1 kB), nebo
- xml:Signature (dle standardu http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0.pdf)
- Základní struktura dotazu pro veřejnou webovou službu je specifikována jako vOKO:Request (1 kB) Takto strukturovaný dotaz se vkládá jako jediný obsah do elementu Body komunikační SOAP obálky. Odpověď je pak dána předpisem pro vOKO:Response (1 kB), který je opět jediným obsahem elementu Body komunikační SOAP obálky.
- Struktura vlastního datového obsahu je individuální vždy pro příslušnou službu a je součástí příslušné dokumentace.
Důležité upozornění!
Při otevření XML dokumentu v prohlížeči Mozilla Firefox (a některých dalších) nejsou zobrazeny jmenné prostory. Pro správnou interpretaci ukázek používejte v tomto případě zobrazení zdrojového kódu stránky.
Problém je znázorněn na následujícím obrázku (výchozí zobrazení v prohlížeči vlevo, zdrojový kód - XML - se jmennými prostory vpravo).
Typy zabezpečení – autorizace
Aktuálně jsou definovány 2 typy zabezpečení veřejných webových služeb MZe, a to:
- Veřejná služba (označena BA)– tedy s přístupem bez jakékoliv autorizace
Tento přístup nevyžaduje žádnou úroveň autentizace a proto v SOAP obálce nemusí být uvedena žádná další struktura.
- Služba se zabezpečením na úrovni Portálu farmáře (označena PF) – je využito zjednodušené autorizace na základě přihlašovacích údajů do Portálu farmáře (uživatelského jméno a WS klíče). Formát autentizačních údajů vkládaných do komunikační obálky je dán specifikací programu vOKO (
vOKO WSS Token
(1 kB)): do hlavičky SOAP obálky se vkládá speciální element, který obsahuje typové označení autentizačního údaje (v tomto případě fixní hodnotu „A01“) a vlastní autentizační řetězec (klíč). Postup jeho vygenerování je popsán zde.
Ukázka SOAP obálky s identifikačními údaji ve formátu vOKO-wss:Token je zde vOKO WSS Token (1 kB).
Služby typu PF je možné volat i s autorizací pomocí elektronického podpisu. U vybraných služeb je možné tímto způsobem činit úplná podání vůči poskytovateli služby.
Adresy serverů pro služby
požadavky (reqeusty) na všechny služby se posílají na stejnou adresu:
- testovací – https://eagritest.cz/ssl/nosso-app/EPO/WS/v2Online/vOKOsrv.ashx
- produkční – https://eagri.cz/ssl/nosso-app/EPO/WS/v2Online/vOKOsrv.ashx
Specifikace requestu
SERVICEID - služby BA i PF
Požadovaná služba se rozlišuje hodnotou parametrem SERVICEID uvnitř každé zprávy (requestu). Tedy: Volání příslušné služby provedete tak, že její identifikátor (např. LPI_DDP01A) vložíte do parametru SERVICEID.
subjectID - služby PF
Do elementu Subject se vkládá povinný atribut subjectID, který obsahuje SZRID, které přidělilo MZe nebo SZIF v rámci registrace firmy do Portálu farmáře eAGRI. Hodnota SZRID je k dispozici po přihlášení do PF eAGRI.cz a po kliknutí na uživatelské jméno v horním pravém rohu.
UIDkey - služba PF
Do elementu UIDkey se vkládá povinný atribut dn, který obsahuje přidělení login uživatele - 99xxx nebo 98xxx.
RequestID - služby BA i PF
Jedná se o nepovinný element, který umožňuje "označkovat" request volitelným identifikátorem ze strany informačního systému subjektu. Hodnota se potom vrací v odpovědi služby.
Využití vOKO
Stejně jako v celé oblasti „Elektronické podatelny MZe“ je možné využít v rámci vlastních aplikačních řešení program vOKO a jeho komunikační modul, který v celém rozsahu řeší problematiku komunikačních obálek včetně definovaných prvků zabezpečení. Pokud se rozhodnete tuto možnost využít, stačí předávat programu vOKO (resp. jeho komunikačnímu modulu) zjednodušený <vOKO:Request/>).