A raktárkészlet változása

Ha a webáruház úgy lett beállítva, a rendszer lenyomatot készít minden változásról, ami a termékek mennyiségében történik. Ehhez az is szükséges, hogy a mennyiségeket nyilvántartsuk (egyébként ez nem kötelező), tehát minden új termékhez írjuk be a kezdő darabszámot.

Rendeléskor minden termékhez külön adatbázistáblában eltárolódik, milyen differencia lépett föl a termék mennyiségében.

Ugyanígy új termék felvitelekor (ha megadunk mennyiséget), termék módosításakor (ha változtatunk a mennyiségen) és a termék törlésekor (ha volt megadva mennyiség) is kerül egy bejegyzés a változási naplóba.

Ezen kívül az adatfogadó service-en keresztül is módosulhatnak a mennyiségek.

A rendszer eltárolja az adott termék azonosítási adatait (rekordazonosító, cikkszám, rendelésnél egyedi attribútumok), az időpontot, hogy milyen módon került tárolásra, valamint bizonyos esetben megjegyzéseket és egyéb adatokat.

Az adatok kiolvasására az adatlekérdezési service-en keresztül van lehetőség. Az adatfogadó és -lekérdező interfész együtt – megfelelő körültekintés mellett – lehetővé teszi a raktárkészlet szinkronizálását más rendszerekkel, de használható például távoli naplózásra vagy módosítások ütemezésére is.

Az adatfogadó service

Az adatokat egy PHP program fogadja http protokollon keresztül (a címet és a jelszót a funkció beillesztésekor adjuk meg Önnek).

Mind a fogadott, mind a válaszként küldött üzenetek XML formátumúak. A service használatához egyedi jelszót állítunk be, melyet GET vagy POST paraméterként 'password' néven kell küldeni.

Az adatokat az alábbi XML-struktúrában kell küldeni:

Megjegyzés: az XML-ek fejléce mindig:

<?xml version="1.0" encoding="UTF-8"?>

– ezt a példákban külön nem fogjuk kiírni.

A gyökérelem neve commands, ebben foglalnak helyet a módosításra vonatkozó parancsok gyermekelemként. Jelenleg egyetlen parancs implementált: ennek neve diff. A diff címkében kötelezően megadandó a változás mértéke (value) és valamelyik azonosító adat: item_id – a rekordazonosító, item_pnumber – a cikkszám. Ha mindkettő szerepel, az item_id lesz figyelembe véve. Opcionálisan megadható a negative paraméter is (alapértelmezett értéke 0). Ezzel szabályozható, hogy a mennyiség negatív értékké válhat-e. Ha egy termék mennyisége 2, és a value -3, akkor alapértelmezetten az új mennyiség 0 lesz, a differencia pedig -2. Ha viszont a negative be van kapcsolva, az eredmény -1, a differencia pedig -3 lesz. Pozitív értékeknél a '+' jel opcionális.

A válasz-XML-ben minden küldött parancsról nyugtázást kapunk.

Legyen a lekérés a következő:

Ekkor a válasz-XML például így nézhet ki:

Látható, hogy a data gyökérelem gyermek eleme a responses tag, és ebben vannak a response tag-ek, melyek a válaszinformációkat tartalmazzák. Minden küldött parancshoz egy response tartozik. A command mező értéke jelen esetben mindig 'diff'. Az item_id és item_pnumber adják a termék azonosító adatait. Ha a termék nem található, csak az jelenik meg, amit a lekérésben megadtunk. A state paraméter jelzi, hogy sikeres volt a művelet. Három lehetséges értéke van:

• 'success' – ha a művelet sikeres volt

• 'error' – ha a művelet sikertelen volt

• 'none' – ha nem történt művelet

Az 'error' tipikusan akkor keletkezik, ha a termék nem található.

A 'none' állapot akkor jön létre, ha a termék darabszáma 0 (esetleg negatív), és a negative attribútum nem volt bekapcsolva, illetve ha kifejezetten 0 szerepelt a value-nál.

A comment attribútummal megjegyzést adhatunk a művelethez.

Az adatlekérdezési service

Adatlekérdezésnél nem XML-t kell küldeni, hanem http query-n keresztül adhatók meg a paraméterek. Az alapcímzésen kívül a GET és a POST adatok egyenértékűek, tehát mindegy, melyik csatornát használjuk. A program csak ezt a két csatornát használja. Azonos változók esetén a POST felülírja a GET-et.

A használható paraméterek:

• starttime – lekért időszak kezdete

• endtime – lekért időszak vége

• item_id – a termék rekordazonosítója

• item_pnumber – termék cikkszáma

• trans_type – tranzakció típusa (például rendelés)

• typeobj_id – tranzakció típus szerinti refrencia-azonosítója

• aggregate – csoportosítás kérése

• get_last_amount – utolsó érték (csak aggregate=item_id vagy aggregate=item_pnumber esetén használható)

Ha az aggregate nincs beállítva, normál lekérdezés fut le. Az első hat paraméter használatával ÉS jellegű szűkítést adhatunk meg. Mind a hat paraméter külön-külön opcionális. Ha starttime és enddimte is meg van adva, az endttime-nak későbbinek kell lennie.

A dátumoknál érvényes dátumot kell megadni (pl. „2011-01-01 10:00:00”), az item_id és typeobj_id paramétereknek pedig egész számnak kell lenniük.

Az eredménylista rendezése mindig a tranzakcióhoz rendelt azonosító alapján történik, ez egyúttal időrendi sorrendet is jelent.

Az eredmény alapesetben az alábbihoz lesz hasonló:

A data gyökérelem tájékoztat arról, hogy nem aggregált lekérdezésről van szó, nincs hiba, és hogy az eredményhalmazban 3 találat van.

A találatok a közvetlenül az eltárolt módosítások kivonatai, egy termék többször is előfordulhat.

A paraméterek jelentése:

• trans_id – a tranzakcióhoz rendelt azonosító

• trans_time – a tranzakció időpontja

• trans_type – milyen módon történt a tranzakció ('order' – rendeléssel; 'admin' – az admin felületen; 'service' – az adatfogadó service-n keresztül)

• typeobj_id – referencia azonosító (mint a lekérésben) – ha a trans_type értéke 'admin', a módosító adminisztrátor azonosítója, ha 'order', akkor a megrendelés azonosítója, egyéb esetben 0

• item_id – a termék rekordazonosítója

• item_pnumber – a termék cikkszáma

• trans_diff – a változás mértéke

• item_amount – a termék mennyisége a tranzakció után

• trans_attributes – kapcsolódó paraméterek

• trans_comment – kapcsolódó megjegyzések

Ha az aggregate paramétert használjuk, a lekérdezési folyamat megváltozik, és a találatok csoportosításra kerülnek.

Az aggregate a következő értékeket veheti föl:

'item_id' – csoportosítás a termékazonosító szerint

'item_pnumber' – csoportosítás a cikkszám szerint

'trans_type' – csoportosítás a tranzakció típusa szerint

'typeobj_id' – csoportosítás a referencia-azonosító (és -típus) szerint

'month' – havi bontás

'all' – teljes összesítés

Ha az aggregate értéke 'item_id' vagy 'item_pnumber', akkor termékenként csoportosítunk (és egy termék egyszer jelenik meg). Ekkor lehetővé a get_last_amount paraméter használata. Ha ezt 1-re állítjuk (engedélyezzük), minden item tag-be be kerül a last_amount attribútum. Ez pontosan azt adja meg, hogy a csoportosított találaton belül az utolsó tranzakció után mi volt a termék mennyisége.

Ha az aggregate értéke 'month', a találatok havi bontásba lesznek csoportosítva. Értelemszerűen csak azok a hónapok fognak szerepelni, amelyekben van találat. Ekkor a sorok egy year és egy month attribútumot kapnak, bennük az adott évvel illetve hónappal (mint egész számmal).

Ha az aggregate értéke 'all', az eredmény egyetlen sor lesz, ami a teljes összesítés tartalmazza (ha nincs találat, nem jelenik meg ez a sor).

Egy csoportosított lekérdezés eredménye például így nézhet ki:

A data gyökérelemben látszik, hogy csoportosított lekérdezés történt. Az aggr_as paraméter megmondja, milyen oszlopra történt a csoportosítás. A találatok elemeinek neve itt is item.

Az első paraméter az aggregált oszlop neve, itt item_id. Ha az aggregate értéke más lenne, itt az az attribútum szerepelne. A last_amount-nál az utolsó módosítás utáni mennyiséget látjuk. A diff most az első módosulás előtti és az utolsó módosulás utáni mennyiségek különbsége. A count megadja, hány érték lett csoportosítva a találatba. A firsttime a csoportban szereplő első tranzakció időpontja, a lasttime az utolsóé (ha a count értéke 1, akkor a kettő megegyezik).

Hibakezelés

Bármilyen hiba esetén kötött formátumú kimenet keletkezik.

Az alábbi hibaüzenet akkor például keletkezik, ha rossz jelszót adtunk meg:

Itt a data blokk error paramétere '1', ami jelzi, hogy hiba történt. A gyermekelem neve error, a type paraméter jelzi a hiba típusát, az elem tartalma pedig egy szöveges (angol nyelvű) leírást mellékel hozzá.

Az adatfogadó service-nél a hiba típusa 'authentication' vagy 'xml' lehet. Authentikációs hiba lép föl, ha a jelszó helytelen, vagy a funkció ki van kapcsolva. Az 'xml' hiba tipikus példája, amikor a küldött XML szintaktikai hibát tartalmaz.

A lekérdező programnál jelenleg az alábbi hibatípusok léteznek:

• 'authentication' – helytelen jelszó vagy a service ki van kapcsolva

• 'format' – formai hiba (ha például rossz formátumú dátumot adunk meg, vagy nem egy egész számot küldünk a rekordazonosító helyén)

• 'semantic' – ha a kérés szemantikai okból teljesíthetetlen (például az endtime korábbi, mint a starttime, vagy nem támogatott adatmezőre akarunk csoportosítani)

• 'internal' – ha belső hiba történt (azok a hibák, amit nem a lekérdező fél követ el – pl. adatbázishiba)

Tippek

• Adatküldéskor akár mindig a teljes lista is beküldhető. A 0-s differenciák soha nem kerülnek be a tranzakciós naplóba.

• Ha azt szeretnénk megnézni, hogy egy adott termékből adott időszakban mennyit rendeltek, állítsuk be a kívánt időszakot, az item_id vagy item_pnumber paraméter legyen a keresett termék azonosítója, a trans_type legyen 'order', az aggregate értéke pedig 'all'!

• A dátum értékeket (starttime, enddtime) többféle formátumban is megadhatjuk. Az alapértelmezett forma: „2011-01-01 10:00:00”, de a kötőjelek helyett pontot is írhatunk. A másodperc értéke vagy pedig a teljes idő-rész elhagyható. Ha például starttime helyén „2011-01-01 10:05”-öt adunk meg, a rendszer automatikusan a végére teszi a nullázott másodpercértéket. Ha az endtime helyén „2011-02-25”-öt adunk meg, a rendszer automatikusan „2011-02-25 23:59:59”-re egészíti ki.

• Nyomon követhetjük egy termék népszerűségének növekedését (vagy csökkenését), ha beállítjuk az item_id (vagy item_pnumber) paramétert, az aggregate értékét pedig 'month'-ra állítjuk.