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, detekce změn lokálně a odesílání pouze modifikací. Vyžaduje sledování změn a správu stavu na straně klienta.
**Nejlepší pro:**
- Synchronizace v reálném čase
- Časté malé aktualizace
- Jemná kontrola nad změnami
card: Feed API
icon: zap
Odeslání jednoho velkého JSON (i gigabajty) se všemi hodnotami. Systém efektivně porovnává a aktualizuje pouze skutečné změny.
**Nejlepší pro:**
- Hromadná synchronizace dat
- Pravidelné úplné synchronizace
- Jednodušší integrační logika

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 unikátních identifikátorů. Dokonce i položky bez unikátních ID (jako řádkové položky) jsou párovány pomocí mechanismu pravděpodobnosti.

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 se zapisují pouze skutečné změny, což minimalizuje režii a udržuje auditní stopy.

Základní komponenty

Feed API využívá dva výkonné nástroje: Mapper a Importer

card: Mapper
icon: settings
Transformuje externí datové formáty (XML, JSON, CSV) do interního formátu. Zpracovává mapování polí, transformace dat 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:/devdoc/mapper|Zobrazit dokumentaci|book-open]
card: Importer
icon: upload
Zpracovává mapovaná data a inteligentně aktualizuje databázi. Zpracovává operace upsert, mazání a správu vztahů.
**Klíčové vlastnosti:**
- Operace Upsert
- Párování založené na vyhledávání
- Pravděpodobnostní párování
- Dávkové zpracování
[navigate:/devdoc/imports|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

Řídí, zda mají být existující položky, které nejsou ve feedu, odstraněny.

"items": [
  { "code": "ITEM-1", "quantity": 10 }
],
"items@removeAll": true  // Odstranit položky, které nejsou ve feedu

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"  // Doporučeno pro velké feedy
"@atomic": true     // Všechno nebo nic
"@atomic": false    // Nezávislé záznamy

Příklad: Feed produktů

Kompletní příklad synchronizace produktů pomocí 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 Mapperu

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ý Import 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 vyř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 se zapisují 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 řádkovými položkami

{
  "@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í:**
I když řádkové položky faktur obvykle nemají jedinečné identifikátory, systém používá mechanismus pravděpodobnosti k jejich spárování na základě produktu, množství a dalších polí. To zajišťuje přesné aktualizace bez duplicitních řádkových položek.

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é ke generování exportů dat:

Export založený na dotazech

Použijte dotazovací jazyk k extrahování dat a exportu v různých formátech.

GET /api/products?format=json&export=true

Reverzní Mapper

Použijte mappery v opačném směru k transformaci interních dat zpět do externích formátů.

Dopředný Mapper

Použijte dopředné mappery ke generování specializovaných exportních formátů.

Podporované exportní formáty:

JSON, XML, CSV, Excel, PDF, HTML, Vlastní

[navigate:/devdoc/exports|Zobrazit dokumentaci k exportu|file-text]

Doporučené postupy

• Používejte dávkový režim pro velké feedy — Nastavte @atomic: "batch" pro optimální výkon s velkými datovými sadami.
• Používejte vyhledávání namísto ID databáze — Preferujte code:, email: nebo jiné obchodní klíče pro lepší přenositelnost.
• Využijte @removeAll pro kompletní synchronizaci — Použijte @removeAll: true k 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 svou logiku mapperu a importu s malou podmnožinou před zpracováním velkých feedů.
• Monitorujte výsledky importu — Kontrolujte protokoly importu a zprávy o chybách, abyste identifikovali a opravili problémy s daty.

Testovací nástroje

Interaktivní nástroje pro testování a ověřování nastavení Feed API

[navigate:/devdoc/test-mapper|Test Mapper|settings] [navigate:/devdoc/test-import|Test Import|upload]

Otestujte konfiguraci mapperu pomocí vzorových dat a otestujte importní operace

Související dokumentace

[navigate:/devdoc/mapper|Dokumentace k Mapperu|settings] [navigate:/devdoc/imports|Importní systém|upload] [navigate:/devdoc/exports|Exportní systém|file-text] [navigate:/devdoc/query|Dotazovací jazyk|database]