Jak vydolovat z funkčnosti poskytované nopCommerce pluginem XML transformace to potřebné, se dozvíte v tomto krátkém přehledu. Plugin XML transformace využívá XSLT šablonu pro úpravu obsahu zdrojového XML souboru dostupného z nějaké webové adresy na Internetu.
Konfigurace pluginu
Po instalaci pluginu je veškerá funkčnost pluginu vypnutá, a proto je potřeba navštívit v administraci konfigurační stránku pluginu a provést potřebná nastavení.
- Povoleno - bez povoleného pluginu nebude funkcionalita vykonávána. Po instalaci je tato volba odškrtnuta.
- API klíče - slouží jako možnost omezit přístup k transformačnímu URL. Pokud není uvedený žádný klíč, nebude se kontrola provádět.
- API klíče pro soubory - speciální klíče (nelze zaměnit s předchozími), které umožní přes REST API nahrávat do adresáře /files/transform na e-shopu XSLT soubory nebo je odstraňovat. Pokud není zadán žádný "Api klíč pro soubory", nebude možné tyto operace vykonávat.
- Seznam povolených IP - IP adresy (v4), ze kterých je povoleno přistupovat k REST API. Pokud není zadána žádná adresa (výchozí stav), tak není tato kontrola prováděna.
- Výchozí interval mezipaměti pro vstup - pokud v rámci dotazu na transformační URL vystaveného REST API není specifikován parametr InCacheTime, bude použita tato hodnota. Výchozí hodnota je 1h.
- Výchozí interval mezipaměti pro výstup - pokud v rámci dotazu na transformační URL vystaveného REST API není specifikován parametr outCacheTime, bude použita tato hodnota. Výchozí hodnota je 1h.
- Výchozí typ obsahu výstupu - pokud v rámci dotazu není nastaven parametr resMime, bude použita tato hodnota. Ve výchozím stavu je "application/xml".
Pro souborové operace doporučujeme delší hodnotu klíče. Pokud vám aplikačně implementovaná zabezpečení nevyhovují, doporučujeme je posílit pomocí nastavení vaší reversní proxy.
Základní použití pluginu
Hlavní použití spočívá ve schopnosti pluginu "vloudit" mezi zdrojové XML a místem, kde se má toto XML použít, úpravu pomocí XSLT šablony. Podmínkou je, že místo, které bude očekávat pro svůj vstup XML soubor je schopno akceptovat URL včetně parametrů dotazu (Query Stringu).
Příklad: Máme zdrojový XML soubor dostupný např. na adrese https://nejaky-server.xyz/cesta/dlouha/soubor.xml, ale nemůžeme jej použít tak jak je. Buď sami nebo s pomocí někoho, kdo to umí, jsme získali XSLT šablonu, která potřebnou úpravu dokáže. Pokud ji máme již někde zveřejněnou např. na adrese https://jiny-server.zzz/cesta/sablona.xslt, tak už máme skoro vyhráno.
Nyní stačí při nakonfigurovaném pluginu (např. jak je uvedeno na obrázku výše) do potřebného místa vložit místo adresy na původní XML soubor adresu https://muj-eshop.yyy/zac/file-transform/xslt?xmlUrl=https://nejaky-server.xyz/cesta/dlouha/soubor.xml&xsltUrl=https://jiny-server.zzz/cesta/sablona.xslt&apiKey=FWm4Tzsge95ELRtC a pokud transformace proběhla v pořádku, bude pomocí tohoto nového URL vrácen upravený feed.
Poznámka: Ve výše uvedeném příkladě za předpokladu, že je plugin nastaven tak, jak je na obrázku, bude od prvního dotazu po dobu jedné hodiny vracen stejný výsledek bez ohledu na to, jestli se zdrojové XML nebo transformační XSLT změnilo. Změnit interval lze přidáním parametru inCacheTime a outCacheTime (např. &inCacheTime=10&outCacheTime=10 ... nastaví dobu držení vstupních a výstupních souborů na 10 minut) nebo použitím parametru refresh (&refresh=true ... způsobí, že se nepoužije ani jedna z cachí tj. stáhnou se aktuální vstupy a "vytransformuje" nový výstup).
Pokud URL ke zdroji XML nebo XSLT obsahuje parametry dotazu, je potřeba tento řetězec tzv. URL enkódovat např. pomocí online služby urlencoder.org.
Pro ladění výsledného dotazu a otestování funkčnosti doporučujeme aplikaci Postman.
V případě, že nemáte kam XSLT soubor dát, aby byl veřejně dostupný, můžete jej nahrát mezi statické soubory na váš e-shop. To můžete udělat buď přes FTP nebo SSH, jak jste zvyklí, a nebo pomocí HTTP PUT metody REST API rozhraní (viz. popis níže). V případě použití REST API bude nahraný soubor dostupný na adrese https://muj-eshop.yyy/files/transform/nazev-souboru.xslt.
Omezení funkčnosti
Plugin používá pro aplikaci transformace XSLT v1.0 a XPath v1.0. Ačkoliv se jedná o poměrně omšelé standardy (z r. 1999) a na světě již existují kodifikované novější verze XSLT, stále jde o jediné levné řešení pro implementace založené na Microsoft .NET (Core), na kterém nopCommerce běží. Microsoft do svých knihoven podporu pro novější standardy (zatím) nezahrnul. Využití knihoven třetích stran je v tomto směru poměrně nešikovné, buď z důvodu licenčních poplatků nebo kvůli řešení, které je založeno na použití mezivrstvy pro volání Java implementace.
Je však potřeba zmínit, že při zvládnutí XSLT 1.0 a XPath 1.0 jde i s těmito instrumenty velmi účinně docílit potřebných výsledků.
Popis aplikačního rozhraní
Níže naleznete úplnou dokumentaci k vystavenému REST API, která byla vygenerována z implementace pluginu. Tu samou (nebo ještě aktuálnější) dokumentaci naleznete po instalaci pluginu na adrese https://vas-server:port/zac/file-transfer/swagger. Pozor však na to, že swagger (nebo nověji OpenAPI specifikace) je dostupný pouze v instalacích nopCommerce, kde je proměnná prostředí ASPNETCORE_ENVIRONMENT na hodnotě "Development", tj. mělo by se jednat pouze o vývojové prostředí!
Potřebujete něco kolem pluginu XML transformace a problematiky XSLT prokonzultovat? Ozvěte se, rádi pomůžeme.