Jan Tischler / jan.tischler@mafra.cz Poslední revize: 3.8.2011 Importní rozhraní Úvod Tento dokument popisuje chování server-side skriptů a mechanismů použitých pro synchronizaci pomocí externího softwaru se serverem Reality.iDNES.cz. Synchronizace probíhá s využitím třech prostředků: Volání PHP skriptů Data ve formátu XML FTP přenos na server. XML soubor, který popisuje danou nemovitost je generován na straně klienta. Pomocí FTP protokolu je přenesen spolu s fotografiemi na server, kde je následně zpracován voláním specifického skriptu (viz. níže). Skripty - obecně Exportní modul komunikuje s importním rozhraním pomocí HTTP dotazů zasílaných odpovídajícím skriptům. Výstupy skriptů jsou ve formátu text/plain, a jednotlivé řádky jsou oddělené znaky CR LF (0x0D 0x0A hexadecimálně). V případě úspěchu vrací Specifická data V případě chyby vrací všechny skripty (až na popsané výjimky) ERROR Chybová hláška Chybová hláška oznamuje uživateli, kde došlo při zpracování požadavku k chybě. Ve většině případů by měla být srozumitelná pro makléře, který export inicioval. Výsledná zpráva, kterou skript generuje je ve výchozím stavu v kódování windows-1250. Chceteli docílit, aby rozhraní komunikovalo v UTF-8, stačí při volání jednotlivých skriptů přidat parametr utf8=1. Důležité předpoklady V dalším textu bude jako základ url adresy skriptu považováno http://reality.idnes.cz/import/ Vlastní popis skriptu je již použít jen jeho název a odpovídající parametry. V dalším zápisu je použita obecná notace <jmeno> - povinná hodnota parametru [nepovinna_cast] nepovinná hodnota / část ~ 1 ~
Krok 1 Ověření jména a hesla Pro ověření existence uživatele (realitní kanceláře), platnosti jeho hesla, případně stavu služby je před započetím vlastního exportu třeba zavolat následující skript. check_login.php?login=<jmeno>&pwd=<heslo> V případě úspěchu (zadáno platné jméno a heslo) vrací Krok 2 - Stažení informací o nabídkách get_list.php?login=<jmeno>&pwd=<heslo>&id_exported=[id_exported] id_exported nepovinný parametr, je-li použit, výpis se omezuje jen na nabídku s tímto id, pokud ne, pracuje se všemi nabídkami zvolené RK Jako specifická data vrací skript id_exported pro všechny nabídky, co existují na serveru (pro odpovídající realitní kancelář). V případě úspěchu vrací Id_Exported1 Id_Exported2 Pokud na serveru není žádná nabídka (či v případě použití parametru Id_Exported nabídka s tímto Id neexistuje), skript vrací pouze. ~ 2 ~
Krok 3 Stažení informací o existujících fotografiích / videích Exportní sofware musí také mít možnost zjistit, jaké fotografie resp. videa jsou vyexportovány u nabídek na realitním serveru, aby mohl rozhodnout o jejich přenosu na FTP. K tomu slouží dva skripty, pro každý typ média jeden. Skripty: get_photo.php?login=<jmeno>&pwd=<heslo>&id_exported=[id_exported] get_video.php?login=<jmeno>&pwd=<heslo>&id_exported=[id_exported] id_exported nepovinný parametr, je-li použit, výpis se omezuje jen na nabídku s tímto id, pokud není uveden, pracuje se všemi nabídkami zvolené RK Jako specifická data vrací skripty na řádku: Id_Exported PhotoHash resp. Id_Exported VideoHash Tedy Id nabídky a hash fotografie/videa (více o hashi v kapitole o fotografiích/videu) V případě úspěchu vrací Id_Exported1 Hash1-1 Id_Exported1 Hash1-2 Id_Exported2 Hash2-1 Id_Exported2 Hash2-2 Id_Exported2 Hash2-3 Při omezení na jedno id_exported zasílané v parametru, platí totéž co u kroku 2. Hash kódy fotografií jsou seřazeny v přesné korespondenci s pořadím uvedeným v XML, tj. hash fotografie s <ord>1</ord> je vypsán na prvním řádku, <ord>2</ord> na dalším, atd. Jedinou výjimku v tomto ohledu tvoří hash kódy fotografíí, které při předchozím importu nebyly zpracovány, např. z důvodu nepodporovaného formátu souboru, nebo chyby integrity JPEG, se kterou si knihovna GD2 nedokázala poradit. ~ 3 ~
Krok 4 Vytvoření dat pro přenos Data o nabídce jsou přenášena v XML souboru a jeden soubor odpovídá právě jedné nabídce. Název souboru XML je <login>_<id_exported>.xml kde login login realitní kanceláře id_exported id nabídky, jejíž data jsou v tomto souboru obsažena Pojmenování souboru prosím dodržujte! Respektováním tohoto doporučení usnadníte ladění případných chyb v exportech a správné zatřídění záloh XML souborů na straně serveru. XML soubor obsahuje validní XML v kódování windows-1250 (resp. UTF-8). 1) Základní položky u nabídky Id_Exported unikátní číselný identifikátor nabídky na straně exportujícího. Toto číslo je klíčové ve všech skriptech, které vrací informace o nabídkách (viz skripty popsané výše). Akce update nebo delete. update nabídka se má nahrát na realitní server či aktualizovat. O tom, zda jde o přidání nové nemovitosti nebo aktualizaci starší rozhoduje skript import.php v závislosti na existenci id_exported v databázi. delete smazání nabídky ze serveru. Je-li akce delete, žádné další položky kromě id_exported nejsou v XML souboru požadovány. Pokud na serveru neexistuje, skript vrací chybu ERROR s hláškou o neexistující nabídce. (2010-07-20 - úprava v rámci revize, dosud skript vracel ) 2) Struktura datového souboru v notaci XML <?xml version="1.0" encoding="windows-1250"?> <nabidka> <id_exported>235</id_exported> <akce>update</akce> <isa>1</isa> další uzly... <foto> <ord>1</ord> <hash>45577e4fcc787</hash> <filename>20000000_45577e4fcc787.jpg</filename> </foto> <foto> <ord>2</ord> <hash>c1234a1233e7</hash> <filename>20000000_c1234a1233e7.jpg</filename> ~ 4 ~
</foto>... další fotografie... </nabidka> Pokud je nějaká z nepovinných položek nevyplněna, nechť v datovém souboru úplně chybí (případně je prázdná nebo má uveden atribut isnull= true ). Položky typu boolean nechť nabývají hodnot 0 (ne) nebo 1 (ano) Podrobný popis všech dalších položek, spolu s číselníky, je v dokumentu reality-polozky_vxx.xls kde XX značí číslo verze. 3) Fotografie V souboru s nabídkou jsou vždy uvedeny informace o všech fotografiích, které mají u této nabídky být. Fyzicky se přenáší pouze ty fotografie, které dosud na serveru nejsou, tj. pro které nebyl vrácen v skriptu pro vracení fotografií odpovídající hash. Fotografie je identifikována hash kódem, generovaným na straně klienta. Jedná se o textový řetězec o maximální délce 100 znaků, který unikátně identifikuje fotografii v rámci jedné realitní kanceláře (v ideálním případě MD5 z obsahu fotografie, která je přenášena). Hash kódy fotografií jsou vraceny ve skriptu, který zjišťuje, jaké fotografie již na serveru jsou a tento údaj je na serveru uchováván. Pokud se fotografie přenáší i fyzicky, je pojmenována <login>_<hash>.jpg a toto jméno je uvedeno v záznamu každé fotografie v XML souboru odpovídající nabídky. Položky XML notace související s fotografií: ord označení pozice fotografie hash hash kód filename jméno souboru fotografie Maximální počet fotografií na jednu nemovitost je 30. Délka nejdelší strany fotografie je 800px, menší obrázky se nezvětšují. Doporučujeme fotografie posílat v optimální velikosti, tj. nejlépe v maximálním povoleném rozměru. Příliš malá nebo nekvalitní fotografie nebudí dobrý dojem u klienta, příliš velká (přesahující povolené rozměry) zbytečně zatěžuje server a spojení. Ve řádkovém a galerijním výpisu nemovitostí na serveru je zobrazena vždy miniatura fotografie, která je nahrána na první místo (ord = 1) a tato miniatura je použita i v ostatních případech reprezentace nemovitosti v rámci serveru. Soubor nabídky a soubory s fotografiemi jsou přeneseny na zvolený FTP účet. Poté je volán skript pro zpracování (viz krok 5). 4) Makléř / Pobočka Export by měl rovněž obsahovat informaci o makléři, pokud byl nemovitosti nějaký přidělen. S makléřem je zacházeno v podstatě dvěma způsoby: ~ 5 ~
a) automatický import makléře (nové rozšíření specifikace) Vzhledem k tomu, že je administrace údajů makléřů na více serverech nepraktická, lze při splnění určitých podmínek umožnit automatický import makléře z XML nabídky na server. Pokud XML obsahuje následující uzly, je provedeno automatické uložení makléře na server: makler_id, makler_jmeno, makler_prijmeni Byl-li makléř s odpovídajícím makler_id již na server uložen, a došlo-li ke změně jeho kontaktních údajů v XML, je provedena jeho aktualizace. <makler_id> je tedy unikátní ID makléře na straně exportujícího, a umožňuje pozdější kontrolu změn a aktualizace (např. jména makléře, telefonu, apod.), <makler_jmeno> obsahuje pouze jméno makléře, <makler_prijmeni> obsahuje pouze příjmení makléře. <makler_foto> je fotografie makléře o nejdelší straně 100px (při rozumné kvalitě, samozřejmě, aby makléř nevypadal jako robot), zakódovaná pomocí algoritmu base64. Pokud makléř fotku nemá, uzel je možné úplně vynechat. Těmto makléřům není umožněn samostatný přístup do systému ani nejsou zaslány přihlašovací údaje. Automaticky importovaní makléři, kteří zůstanou po dobu jednoho měsíce bez přiřazené zakázky jsou po této době smazáni. b) identifikace ručně uloženého makléře (původní model) Pokud nejsou splněny podmínky uvedené v bodu a), je na straně importního rozhraní proveden pokus o nalezení odpovídajícího makléře v systému, který mohl být uložen ručně v administračním rozhraní. Uzel <makler_jmeno> obsahuje jméno a příjmení makléře, dle původní specifikace. Identifikace probíhá v následujících krocích: identifikace dle emailu makléře identifikace dle vzorce jméno příjmení obsaženého v makler_jmeno identifikace dle vzorce příjmení jméno obsaženého v makler_jmeno Pokud je v nějakém z těchto kroků makléř nalezen, je zakázka spojena s makléřem. V opačném případě jsou u zakázky zobrazeny informace z XML bez jakýchkoliv vazeb na systém. Rozhraní zůstává zpětně kompatibilní s původními verzemi. c) začlenění pod pobočku (nepovinné) Pokud exportujete jako centrála pod jedním účtem nemovitosti svých poboček a pobočky jsou založeny u nás na serveru, pak můžete využít v rámci exportu možnost zatřídění nemovitostí pod pobočku přidáním xml uzlu <id_pobocka>. Číselná hodnota parametru odpovídá id pobočky (id_rk) na serveru. Pokud je id platné, dojde k uložení pod odpovídající pobočku a makléř bude při automatickém importu pod tuto pobočku rovněž začleněn. V případě nejasností se informujte na podrobnosti. ~ 6 ~
5) Video Od března 2010 podporuje server přidání video sekvencí k jednotlivým nemovitostem - ručně vloženým i importovaným přes administrační rozhraní webu. Ve snaze ušetřit importujícím dodatečnou interakci s administračním rozhraním serveru při nahrávání videa jsme zavedli možnost přidání videa k nemovitostem v rámci exportu. V tuto chvíli se však jedná pouze o jednosměrnou cestu. Následné odstranění videa, resp. jeho skrytí, je možné pouze prostřednictvím administrace. Začlenění do exportu je téměr identické s fotografiemi, a pojmenování souborů rovněž. Jméno souboru je konstruováno jako <login>_<hash>.ext, kde login je přihlašovací jméno pod nímž exportujete, hash odpovídá MD5 otisku souboru s videem a ext je přípona videa odpovídající jeho formátu. Standardně podporované formáty videa jsou: FLV Flash Video (nativní formát přehrávače videa) AVI, MOV, MPEG, WMV Další formáty, jimiž disponujete a nejsou uvedeny ve výčtu, se mnou prosím konzultujte. Přednostně je preferován formát FLV, neboť při jeho použití odpadá nutnost konverze na straně serveru a importující má plnou kontrolu nad kvalitou výsledku. Video prochází po nahrání procesem konverze a schválení obsahu, tudíž na serveru není viditelné okamžitě po nahrání, ale většinou do druhého pracovního dne. Pokud se přihlásíte do administrace a otevřete si detail nemovitosti, uvidíte stav zpracování videa. Více o videoprohlídkách na http://reality.idnes.cz/vyhody#videoprohlidky Velikost jednoho videa by v ideálním případě neměla přesahovat 50MB. Rozšíření XML o uzly <video> : <nabidka> <video> <ord>1</ord> <hash>7e4ef92d1472fa1a2d41b2d3c1d2b77a</hash> <filename>20000000_7e4ef92d1472fa1a2d41b2d3c1d2b77a.mov</filename> </video> <video> <ord>2</ord> <hash>6938032a0bd25994cbc0ca236aeb2c08</hash> <filename>20000000_6938032a0bd25994cbc0ca236aeb2c08.wmv</filename> </video> </nabidka> ~ 7 ~
Krok 5 Spuštění importu dat na serveru a získání reportu o výsledku Po nahrání souborů na ftp je spuštěno jejich zpracování. Skript vrací informace o úspěchu či neúspěchu dané akce v obvyklé formě. import.php?login=<jmeno>&pwd=<heslo>&filename=<soubor.xml> filename jméno XML souboru, který byl uložen na ftp a má se zpracovat V případě úspěchu vrací doplňující informace o průběhu akce V případě chyby vrací ERROR chybová hláška Chybová hláška při odmítnutí exportu obsahuje výčet chybějících parametrů, případně důvody, proč nedošlo ke zpracování, resp. chyby při zpracování. V případě jakékoliv chyby v průběhu zpracování nabídky, která neumožní dokončení procesu, zpracování končí a skript vrací odpovídající chybovou hlášku. ~ 8 ~
Rozšířené funkce importního rozhraní URL s detailem nabídky Pro zprostředkování zpětné vazby a ověření správného mapování hodnot je k dispozici skript vracející URL adresu s detailem nabídky. nemo_detail.php?login=<jmeno>&pwd=<heslo>&id_exported=<id_exported> id_exported id, pod kterým byla nabídka exportována V případě úspěchu vrací URL adresa nabídky Hopování Od 1.7. 2011 bude zavedeno nové řazení výpisů na serveru. Testovat tuto funkci lze na testovacím serveru, v ostrém provozu bude nasazena od výše uvedeného data. Hopování je funkce, která umožňuje dočasně posunout vybrané nabídky rk na první pozice ve výpisu. Následující text popisuje, za jakých okolností lze operaci provádět a jaký je její výsledný efekt. Cílem této funkce je eliminovat nadměrnou zátěž serveru a zároveň poskytnout klientům možnost, jak nenásilnou cestou posunout své nabídky na vrchol výpisu. Omezení pro hopování: nově uložená nabídka nelze tentýž den hopovat, neboť je v iniciálním stavu již na počátku výpisu. každou nabídku lze hopovat pouze jedenkrát denně má-li rk do 100 inzerátů, lze denně odhopovat celou její nabídku pro vyšší počet (101+) je povoleno hopovat 1/3 z celkového počtu nabídek, maximálně však 500. cena za jeden hop je stejná jako cena za vložení nového inzerátu, není-li uvedeno jinak. Charakteristika řazení výpisu: dle nového modelu bude výchozí výpis seřazen dle data posledního hopu. nově uložená nabídka má datum posledního hopu rovno datu jejího uložení do systému Penalizace mazaných a znovu nahrávaných nabídek: nabídka, která bude smazána a znovu nahrána bude pokládána za původní a datum jejího uložení (tj. i její pozice ve výchozím seřazení výpisu) bude použita hodnota z jejího prvního uložení. hop.php?login=<jmeno>&pwd=<heslo>&id_exported=<id_exported> ~ 9 ~
id_exported id, pod kterým byla nabídka exportována V případě úspěchu vrací zpráva o úspěšném dokončení operace a stržené částce z kreditu V případě neúspěchu vrací chybové hlášky následujícího charakteru (::příčína / hláška): :: nevalidní id_exported Je třeba specifikovat id_exported! :: neexistujíci nemovitost Záznam s id_exported = $id_exported na serveru neexistuje! :: interní chyba při transformaci id_exported -> id_nemo Neplatné ID nemovitosti :: chcete hopovat tutéž nemovitost 2x za den Nemovitost s id_nemo= $id_nemo (id_exported= $id_exported) již byla dnes hopována. :: datum uložení je dnešní Nelze hopovat dnes uloženou nemovitost. :: výchozí počet zakázek je 0 není z čeho vypočítat limit (v podstatě implikuje chybu výše) Na počátku dnešního dne neměla rk na serveru žádné nemovitosti - nelze hopovat. :: zbyvajici počet hopovatelnych nemovitosti je 0 Překročili jste limit denního počtu hopovaných nemovitostí! :: nedostatečný kredit pro provedení operace Pro hopnutí nemovitosti s id_nemo= $id_nemo (id_exported= $id_exported) nemáte dostatečný kredit. :: pokus o hopovaní z pozice pobočky bez vlastního kreditu a bez povoleného čerpání centrálního kreditu Nemáte povoleno čerpání centrálního kreditu! :: nerozlišená chyba při odečtení kreditu Nebylo možné strhnout kredit za hopnutí nemovitosti s id_nemo= $id_nemo (id_exported= $id_exported). Slova napsaná tučně a uvozená znakem $ představují proměnnou. Všechny chybové hlášky jsou uvozeny klasickým "ERROR" a CRLF. ~ 10 ~
Rozšířený export statistik návštěvnosti Od 1.5.2011 (včetně) je možné získat statistické údaje o nabídkách uložených na serveru na denní bázi. Statistiky jsou exportovány ve formátu XML (viz. níže) a výstup obsahuje data všech existujících nabídek, u kterých byla ten den provedena nějaká ze sledovaných akcí (návštěva detailu nemovitosti, odeslání emailu, přeposlání známému, a podobně). nemo_stats.php?login=<jmeno>&pwd=<heslo>&xml=<bool>&date=<yyyy-mm-dd> xml parametr udává režim výstupu (jediná podporovaná hodnota v tuto chvíli je 1, tj. výstup kompletně v XML včetně chyb). date datum ve formátu YYYY-MM-DD, dřívejší hodnoty než 2011-05-01 vrací prázdný výsledek Vzorový XML výstup úspěch <?xml version="1.0" encoding="windows-1250"?> <stats> <control> <status>ok</status> <listed>1</listed> </control> <data> <stat> <id_exported>2476923</id_exported> <id_nemo>28507</id_nemo> <display>2</display> <display_v>0</display_v> <print>0</print> <send_f>0</send_f> <send_q>0</send_q> <fav_add>0</fav_add> <click_mail>0</click_mail> <click_rk_url>0</click_rk_url> <click_profile>0</click_profile> <ts_create>2011-04-19 15:19:02</ts_create> <ts_update>2011-04-19 16:10:09</ts_update> </stat> </data> </stats> XML je rozděleno na dvě části. Uzel <control> obsahuje souhrnné informace o výsledku. Uzel <data> pak v potomcích <stat> denní statistiky každé nemovitosti, která ten den měla nějaký zásah do statistik. ~ 11 ~
V případě, že v den specifikovaný parametrem date nemá žádná z nabídek rk záznam ve statistikách, XML obsahuje pouze část <control>, kde <listed>0</listed>. Pokud dojde k chybě při zpracování, control/stat bude mít hodnotu error, a doplněn uzel <error> s popisem chyby, viz. příklad: <stats> <control> <status>error</status> <error>zadané datum '2011-060-1' není platné!</error> </control> </stats> Popis jednotlivých uzlů vnořených v uzlu <stat>: id_exported ID, pod kterým byla zakázka vyexportována id_nemo interní ID serveru Reality.iDNES.cz display počet zobrazení v požadovaný den display_v počet přehrání videosekvence print počet požadavků na vytištění detailu nemovitosti send_f přeposlané upozornění známému (počet úspěšných odeslání zprávy) send_q odeslaný dotaz makléři (počet úspěšných odeslání zprávy) fav_add počet přidání do oblíbených click_mail počet kliknutí na odkaz mailto: v detailu nemovitosti click_rk_url počet kliknutí na url realitní kanceláře click_profile klik na link do profilu rk ts_create čas prvotního uložení nabídky ts_update čas poslední změny (posledního update skrz importní rozhraní) Odstranění automaticky importovaných makléřů V kroku 4. bodu 4) Makléř je možno za určitých podmínek zajistit automatické uložení makléře do systému na serveru a jeho existenci jako plnohodnotné entity. Ve chvíli, kdy tento automaticky importovaný makléř nemá žádné nemovitosti (např. ukončil spolupráci s rk, apod.), je zde logicky tendence ho ze systému odstranit. K tomu slouží následující skript. agent_kill.php?login=<jmeno>&pwd=<heslo>&mode=<mode>&ids=[id_agent] mode režim mazání, viz níže. ids seznam makléřů, které chcete smazat (oddělený středníkem) Režim mazání all skript vezme všechny automaticky importované makléře rk na serveru a ty z nich, kteří jsou bez nemovitostí, smaže. select množinu importovaných makléřů, nad kterou se má provést mazací operace determinuje parametr ids, obsahující seznam identifikátorů odpovídající hodnotám uzlu <id_agent> z XML, které posíláte v rámci exportu nemovitostí. ~ 12 ~
Návratové hodnoty skriptu jsou obdobné jako u ostatních a v případě úspěchu je vrácen počet smazaných makléřů a případně počet nezmazaných z množiny ids. Testování Pro počáteční testování je nutné požádat o přístup k testovacímu serveru. Na základě tohoto aktu je na požadovanou emailovou adresu odeslán email s údaji nutnými pro testování. Před přechodem na ostrý provoz je třeba sdělit IP adresu/adresy, ze které/kterých budou probíhat exporty. Pokud export neprobíhá centralizovaně, je možné domluvit alternativní autentizační mechanismus. Na základě žádosti bude přidělen přístup k testovacímu rozhraní a odeslány přistupové údaje ke službě přistupové údaje k FTP účtu pro nahrávání obrázků a exportů popis některých zákonitostí spojených s přenosem souborů Po dostatečném otestování, tj. importu několika nabídek pro každý typ nemovitosti na testovací server a oboustranné kontrole správnosti hodnot a správného zatřídění, lze přidělit přístup k ostrému importnímu rozhraní. FAQ Q: Při importu dostávám hlášku Chcete zpracovávat neexistující soubor, ačkoliv se zdá, že je vše v pořádku, co dělám špatně? A: Zkontrolujte přihlašovací údaje k FTP účtu. S největší pravděpodobností kopírujete data na testovací server a export spouštíte na ostrém. Pro ostré přenosy je FTP login external_export. Q: Při zpracování dostávám hlášku Chyba při zpracování XML souboru!. A: Možné příčiny: nevalidní XML (nepovolené znaky, nesprávná notace, chybející uzavírací značky), chyba při přenosu XML souboru (soubor je na FTP vytvořen, ale je prázdný). Q: Importuji nemovitost s několika fotografiemi, v detailu nemovitosti však vidím pouze jednu nebo žádnou, nebo jen některé z přiřazených. A: Možné příčiny: Jedna nebo žádná fotografie zkontrolujte správné zapouzdření uzlů v XML. Uzly každé fotografie jsou zapouzdřeny v uzlu <foto> a těmto je nadřazený hlavní uzel <nabidka>. Viz vzorový výsek XML krok 4, bod 2). Jen některé fotografie zkontrolujte formát přenášených fotografií, zda odpovídá podporovaným formátům a zároveň, zda soubory, které se přenáší na FTP pro následné zpracování neobsahují chyby, resp. zda jsou fotografie přenášeny v režimu BINARY, nikoliv text. Případné komentáře a další dotazy prosím směrujte na mou emailovou adresu uvedenou v záhlaví dokumentu. Děkuji. JT --- Konec dokumentu --- ~ 13 ~