Formaty treści i dzielenie tablic

Nie każdy system wysyła dane w formacie JSON, a nie każde żądanie dotyczy jednej rzeczy. Dwa ustawienia obejmują oba przypadki.

Formaty treści

Format jest pobierany z nagłówka Content-Type żądania. Niezależnie od formatu, mapowanie pól wykorzystuje te same ścieżki z kropkami.

Typ treści	Zostało przetworzone jako	Typowi nadawcy
application/json	JSON	Większość interfejsów API, n8n, Make, Zapier
application/x-www-form-urlencoded	Pola formularza	Twilio, PayPal IPN, zwykłe formularze HTML
multipart/form-data	Pola formularza oraz części pliku stają się nazwą pliku	Narzędzia do tworzenia formularzy, punkty końcowe przesyłania danych
text/xml, application/xml, *+xml	XML	Starsze systemy ERP i systemy przewoźników

Dwie rzeczy, o których warto wiedzieć:

• Treść, która jest poprawnym JSON-em, jest zawsze odczytywana jako JSON, nawet jeśli nadawca oznaczy ją jako coś innego. Wiele narzędzi wysyła JSON z typem zawartości „form”, co pozwala im nadal działać.
• Treści formularzy i plików XML mogą zawierać pola, których Państwo nie zmapowali. Nie stanowi to problemu: nadawca sam określa ich strukturę, dlatego treści te nie podlegają rygorystycznej kontroli, która ma zastosowanie do danych JSON, nad którymi Państwo sprawują kontrolę.

curl -X POST https://your-app-url/webhook/ab12cd34 \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Api-Key: your-token" \
  --data-urlencode "From=+15551234567" \
  --data-urlencode "Body=Where is my order?"

# Map fieldOne to: From
# Map fieldTwo to: Body

Atrybuty XML

Atrybut XML jest dostępny pod nazwą z prefiksem @_, więc <order id="7"> jest mapowany jako order.@_id, a <order><name>Bob</name></order> jako order.name. Wartości są przekazywane w postaci tekstu, co pozwala zachować dokładność długich identyfikatorów.

Podział tablic na sekwencje

Gdy jedno żądanie zawiera listę - na przykład 20 zamówień z systemu ERP lub partię aktualizacji stanów magazynowych - zazwyczaj oczekuje się, aby proces przebiegał osobno dla każdej pozycji, a nie tylko raz dla całej partii.

W sekcji Ustawienia zaawansowane -> Podziel tablice na serie proszę podać ścieżkę do tablicy:

Ścieżka	Należy stosować, gdy
items	Tablica jest polem najwyższego poziomu: { "items": [ ... ] }
data.orders	Ma strukturę zagnieżdżoną: { "data": { "orders": [ ... ] } }
$	Sama treść stanowi tablicę: [ { ... }, { ... } ]
(puste)	Wyłączone. Jedno uruchomienie na żądanie - ustawienie domyślne.

Każdy element stanowi osobny przebieg, w którym ten element pełni rolę ładunku, dlatego ścieżki mapowania są względne względem danego elementu: należy mapować sku, a nie items.0.sku.

{
  "items": [
    { "sku": "ABC-1", "qty": 2 },
    { "sku": "ABC-2", "qty": 1 },
    { "sku": "ABC-3", "qty": 7 }
  ]
}

// Split path: items
// Map fieldOne to: sku
// Map fieldTwo to: qty
// Response: { "runs": 3, "blocked": 0 }

Zasady i ograniczenia

• Maksymalnie 100 pozycji na jedno żądanie. Większa partia zostanie odrzucona, aby zapobiec zalaniu Państwa procesu przez niekontrolowanego nadawcę.
• Jeśli w którymkolwiek elemencie brakuje przypisanej właściwości lub jest on zbyt duży dla usługi Shopify Flow, całe żądanie zostaje odrzucone i nic nie jest wysyłane, a pozycja elementu, który spowodował błąd, jest podana w komunikacie o błędzie. Dzięki temu partia jest przetwarzana w całości lub wcale, a nie tylko częściowo.
• Elementy, które są zwykłymi wartościami, a nie obiektami, są przekazywane w postaci { "value": ... }.
• Funkcji split nie można łączyć z odpowiedzią synchroniczną: na jedno wywołanie nie może odpowiadać wiele instancji. Zobacz Odpowiedź synchroniczna.
• Ponowne uruchomienie poprzedniego przebiegu z sekcji „Historia” powoduje ponowne wysłanie tylko tego jednego elementu, a nie całej partii.

W dziale „Historia”

Każda pozycja stanowi osobny wpis, dzięki czemu można je przeglądać, ponownie wypróbowywać i odtwarzać osobno.