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:

1. 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.
    
2. 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://epomzetest.gov.cz/ssl/nosso-app/EPO/WS/v2Online/vOKOsrv.ashx
• produkční – https://epomze.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/>).