Formati del corpo e suddivisione degli array

Non tutti i sistemi inviano dati in formato JSON e non tutte le richieste riguardano un unico elemento. Due impostazioni consentono di coprire entrambi i casi.

Formati del corpo

Il formato viene ricavato dall'intestazione Content-Type della richiesta. Indipendentemente dal formato, la mappatura dei campi utilizza gli stessi percorsi con punti.

Tipo di contenuto	Analizzato come	Mittenti tipici
application/json	JSON	La maggior parte delle API, n8n, Make, Zapier
application/x-www-form-urlencoded	Campi del modulo	Twilio, PayPal IPN, moduli HTML semplici
multipart/form-data	I campi dei moduli e le parti del file diventano il nome del file	Generatori di moduli, endpoint di caricamento
text/xml, application/xml, *+xml	XML	Sistemi ERP e di gestione dei trasportatori di vecchia generazione

Due dettagli che vale la pena conoscere:

• Un corpo che è un JSON valido viene sempre interpretato come JSON, anche quando il mittente lo contrassegna come qualcos’altro. Molti strumenti inviano JSON con un tipo di contenuto “form”, e ciò ne garantisce il corretto funzionamento.
• I corpi dei dati in formato Form e XML potrebbero contenere campi che non avete mappato. Non c’è alcun problema: è il mittente a decidere la propria struttura, pertanto tali corpi non sono soggetti al controllo rigoroso che si applica ai dati JSON da voi controllati.

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

Attributi XML

Un attributo XML è disponibile con il proprio nome preceduto dal prefisso @_; pertanto, <order id="7"> viene mappato come order.@_id, mentre <order><name>Bob</name></order> diventa order.name. I valori vengono forniti sotto forma di testo, il che garantisce la precisione degli ID di lunghezza elevata.

Suddivisione degli array in serie

Quando una richiesta contiene un elenco - ad esempio 20 ordini provenienti da un sistema ERP o un lotto di aggiornamenti delle scorte - solitamente si desidera che il workflow venga eseguito una volta per ogni voce, anziché una sola volta per l’intero lotto.

In Impostazioni avanzate -> Suddividi gli array in serie, indichi il percorso dell'array:

Percorso	Da utilizzare quando
items	L'array è un campo di primo livello: { "items": [ ... ] }
data.orders	È annidato: { "data": { "orders": [ ... ] } }
$	Il corpo stesso costituisce l'array: [ { ... }, { ... } ]
(vuoto)	Disattivato. Un'esecuzione per ogni richiesta, impostazione predefinita.

Ogni elemento diventa una propria esecuzione con quell’elemento come payload, pertanto i percorsi di mappatura sono relativi all’elemento stesso: si utilizzi sku, non 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 }

Regole e limiti

• Al massimo 100 elementi per richiesta. I lotti più grandi vengono respinti, in modo che un mittente incontrollato non possa intasare il Suo workflow.
• Se a un elemento manca un campo mappato o se è troppo grande per Shopify Flow, l’intera richiesta viene respinta e non viene inviato nulla; la posizione dell’elemento non valido viene indicata nel messaggio di errore. Ciò garantisce che un batch venga elaborato nella sua interezza o non venga elaborato affatto, anziché essere applicato solo parzialmente.
• Gli elementi che sono valori semplici anziché oggetti vengono restituiti come { "value": ... }.
• La suddivisione non può essere combinata con una risposta sincrona: un unico richiedente non può ricevere risposta da più istanze. Si veda Risposta sincrona.
• La riproduzione di un'esecuzione precedente dalla cronologia comporta il reinvio di quel singolo elemento, non dell'intero lotto.

Nella storia

Ogni elemento costituisce una voce a sé stante, pertanto è possibile visualizzarlo, riprovare e riprodurlo separatamente.