Co je to?
Poznámka pro administrátory: Toto je vysokorychlostní „dálnice“ pro přesun obrovského množství dat mezi vaším e-shopem a dalšími obchodními systémy (jako je váš sklad nebo účetní software). Je navržena tak, aby efektivně zpracovávala tisíce nebo dokonce miliony záznamů.
Pro koho je to určeno? Administrátoři by si to měli přečíst, aby pochopili, jak platforma zůstává synchronizovaná s vašimi dalšími obchodními nástroji. Zatímco technické „jak na to“ je pro vaše vývojáře, měli byste vědět, že tato funkce zajišťuje, že váš produktový sklad, ceny a objednávky jsou vždy aktuální napříč všemi vašimi systémy.
Klíčové výhody pro e-shop:
- Naprostá přesnost dat: Automaticky porovnejte celý váš produktový katalog a aktualizujte pouze to, co se skutečně změnilo, čímž zabráníte chybám v datech.
- Velkokapacitní synchronizace: Bez námahy zpracujte obrovské soubory (dokonce i gigabajty), které by standardní importní nástroje zhroutily.
- Zjednodušená logika: Namísto ručního sledování každé malé změny mohou vaši vývojáři jednoduše poslat „celkový obraz“ a nechat náš systém, aby se postaral o zbytek.
- Automatické čištění: Zajistěte, aby produkty odstraněné z vašeho skladového systému byly automaticky skryty nebo odstraněny také z vašeho e-shopu.
Co je Feed API?
Při synchronizaci dvou systémů máte dva hlavní přístupy:
card: Klasické API
icon: refresh-cw
Čtení dat přes API, lokální detekce změn a odesílání pouze modifikací. Vyžaduje sledování změn a správu stavu na straně klienta.
**Nejlepší pro:**
- Synchronizaci v reálném čase
- Časté malé aktualizace
- Jemně odstupňovanou kontrolu nad změnami
card: Feed API
icon: zap
Odeslání jednoho velkého JSONu (až gigabajty) se všemi hodnotami. Systém efektivně porovnává a aktualizuje pouze skutečné změny.
**Nejlepší pro:**
- Synchronizaci hromadných dat
- Pravidelné plné synchronizace
- Jednodušší integrační logiku
Jak Feed API funguje
1. Efektivní přednačtení
Systém efektivně přednačítá existující data pro porovnání pomocí optimalizovaných databázových dotazů.
2. Inteligentní párování
Záznamy jsou párovány pomocí vyhledávání (code:, id:) nebo jedinečných identifikátorů. Dokonce i položky bez jedinečných ID (jako jsou položky řádků) jsou párovány pomocí pravděpodobnostního mechanismu.
3. Detekce změn
Systém porovnává všechna data a identifikuje skutečné změny, čímž eliminuje falešné rozdíly.
4. Selektivní aktualizace
Do databáze jsou zapsány pouze skutečné změny, což minimalizuje režii a udržuje auditní záznamy.
Klíčové komponenty
Feed API využívá dva výkonné nástroje: Mapovač a Importer
card: Mapovač
icon: settings
Transformuje externí datové formáty (XML, JSON, CSV) do interního formátu. Zpracovává transformace Mapovače, datové transformace a konverze typů.
**Klíčové vlastnosti:**
- Podpora JSONPath a XPath
- Vyhodnocování výrazů
- Rozlišení vyhledávání
- Mapování vnořených entit
[navigate:mapper.md|Zobrazit dokumentaci|book-open]
card: Importer
icon: upload
Zpracovává mapovaná data a inteligentně aktualizuje databázi. Zpracovává upserty, mazání a správu vztahů.
**Klíčové vlastnosti:**
- Operace upsert
- Párování na základě vyhledávání
- Pravděpodobnostní párování
- Dávkové zpracování
[navigate:imports.md|Zobrazit dokumentaci|book-open]
Klíčové direktivy
Základní direktivy pro operace Feed API
Vyhledávání (code:, id:, atd.)
Identifikujte záznamy pomocí různých typů vyhledávání namísto ID databáze.
"category": "code:ELECTRONICS"
"manufacturer": "id:12345"
"customer": "email:john@example.com"
@removeAll
Určuje, zda mají být odstraněny existující položky, které nejsou ve feedu.
"items": [
{ "code": "ITEM-1", "quantity": 10 }
],
"items@removeAll": true // Remove items not in feed
Výchozí: true pro režim pole/objektu, false pro režim sloučení
@operation
Explicitně řídí typ operace pro každý záznam.
{ "@operation": "upsert", "code": "PROD-1", "name": "Product 1" }
{ "@operation": "delete", "code": "PROD-OLD" }
{ "@operation": "create", "name": "New Product" }
Hodnoty: create, update, upsert, delete
@where
Hromadné operace pomocí klauzulí where pro hromadné aktualizace nebo mazání.
{
"@operation": "update",
"@where": "category = 'code:OLD_CAT'",
"category": "code:NEW_CAT"
}
@atomic
Řídí chování transakcí a zpracování chyb.
"@atomic": "batch" // Recommended for large feeds
"@atomic": true // All-or-nothing
"@atomic": false // Independent records
Příklad: Feed produktů
Kompletní příklad synchronizace produktů přes Feed API
1. Zdrojová data (externí systém)
{
"products": [
{
"productCode": "WIDGET-001",
"productName": "Super Widget",
"price": 99.99,
"categoryCode": "ELECTRONICS",
"variants": [
{
"sku": "WIDGET-001-RED",
"color": "Red",
"stock": 50
},
{
"sku": "WIDGET-001-BLUE",
"color": "Blue",
"stock": 30
}
]
},
{
"productCode": "GADGET-002",
"productName": "Mega Gadget",
"price": 149.99,
"categoryCode": "ELECTRONICS"
}
]
}
2. Konfigurace Mapovače
type JSON
@atomic = "batch"
@language = "en"
products = '$.products[*]' {
id[code] = 'productCode'
name = 'productName'
price = 'price'
category[code] = 'categoryCode'
variants = 'variants[*]' {
code = 'sku'
color = 'color'
stockQuantity = 'stock'
@removeAll = "true"
}
}
3. Výsledný importní JSON
{
"@atomic": "batch",
"products": [
{
"id": "code:WIDGET-001",
"name": "Super Widget",
"price": 99.99,
"category": "code:ELECTRONICS",
"variants": [
{
"code": "WIDGET-001-RED",
"color": "Red",
"stockQuantity": 50
},
{
"code": "WIDGET-001-BLUE",
"color": "Blue",
"stockQuantity": 30
}
],
"variants@removeAll": true
},
{
"id": "code:GADGET-002",
"name": "Mega Gadget",
"price": 149.99,
"category": "code:ELECTRONICS"
}
]
}
**Co se stane:**
- Produkty jsou párovány podle kódu (`code:WIDGET-001`)
- Kategorie je rozřešena pomocí vyhledávání (`code:ELECTRONICS`)
- Existující varianty, které nejsou ve feedu, jsou odstraněny (`@removeAll: true`)
- Nové varianty jsou vytvořeny, existující jsou aktualizovány
- Do databáze jsou zapsány pouze skutečné změny
- Zpracování probíhá v dávkách pro optimální výkon
Příklad: Feed faktur
Synchronizace faktur s položkami řádků
{
"@atomic": "batch",
"invoices": [
{
"id": "code:INV-2024-001",
"customer": "code:CUSTOMER-123",
"issueDate": "2024-01-15",
"dueDate": "2024-02-15",
"items": [
{
"product": "code:WIDGET-001",
"quantity": 5,
"unitPrice": 99.99,
"description": "Super Widget - Red"
},
{
"product": "code:GADGET-002",
"quantity": 2,
"unitPrice": 149.99,
"description": "Mega Gadget"
}
],
"items@removeAll": true
}
]
}
**Pravděpodobnostní párování:**
Přestože položky řádků faktur obvykle nemají jedinečné identifikátory, systém používá pravděpodobnostní mechanismus k jejich párování na základě produktu, množství a dalších polí. To zajišťuje přesné aktualizace bez duplicitních položek řádků.
Generování feedů
Feed API může také generovat exporty dat v různých formátech
Feed API můžete použít nejen pro importy, ale také pro generování exportů dat:
Export založený na dotazech
Použijte dotazovací jazyk k extrakci dat a jejich exportu v různých formátech.
GET /api/products?format=json&export=true
Reverzní Mapovač
Použijte mapovače v opačném směru k transformaci interních dat zpět do externích formátů.
Dopředný Mapovač
Použijte dopředné mapovače k generování specializovaných exportních formátů.
Podporované exportní formáty:
JSON, XML, CSV, Excel, PDF, HTML, Vlastní
Osvědčené postupy
- Použijte dávkový režim pro velké zdroje dat — Nastavte
@atomic: "batch"pro optimální výkon s velkými datovými sadami. - Použijte vyhledávání namísto ID databáze — Upřednostněte
code:,email:nebo jiné obchodní klíče pro lepší přenositelnost. - Využijte @removeAll pro kompletní synchronizaci — Použijte
@removeAll: truek zajištění odstranění smazaných položek z cílového systému. - Nejprve testujte s malými datovými sadami — Ověřte svůj Mapovač a importní logiku s malou podmnožinou před zpracováním velkých zdrojů dat.
- Monitorujte výsledky importu — Zkontrolujte protokoly importu a chybové zprávy k identifikaci a opravě problémů s daty.
Související dokumentace
[navigate:mapper.md|Dokumentace Mapovače|settings] [navigate:imports.md|Importní systém|upload] [navigate:query.md|Dotazovací jazyk|database]