ボディ形式と配列の分割

すべてのシステムがJSONを送信するわけではなく、また、すべてのリクエストが単一の事柄に関するものとは限りません。2つの設定で、これらの両方のケースに対応できます。

本文の形式

フォーマットは、リクエストのContent-Typeヘッダーから取得されます。フォーマットが何であれ、フィールドのマッピングには同じドット区切りのパスが使用されます。

コンテンツの種類	次のように解析されます	代表的な送信者
application/json	JSON	ほとんどのAPI、n8n、Make、Zapier
application/x-www-form-urlencoded	フォームの入力項目	Twilio、PayPal IPN、プレーンなHTMLフォーム
multipart/form-data	フォームの入力欄やファイルのパーツがファイル名になります	フォームビルダー、アップロードエンドポイント
text/xml, application/xml, *+xml	XML	旧式のERPシステムおよび運送業者システム

知っておくべき2つの点：

• 有効なJSONである本文は、送信者が別のラベルを付けていたとしても、常にJSONとして読み込まれます。多くのツールは、コンテンツタイプを「form」としてJSONを送信していますが、これにより正常に動作し続けます。
• フォームやXMLの本文には、マッピングされていないフィールドが含まれている場合があります。それでも問題ありません。送信側がその形式を決定するため、これらの本文については、ご自身が管理するJSONに適用される厳格なチェックは行われません。

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

XML属性

XML属性は、その名前の先頭に「@_」を付加した形式で利用可能です。したがって、<order id="7"> は order.@_id として、<order><name>Bob</name></order> は order.name としてマッピングされます。値はテキストとして渡されるため、長いIDも正確に保持されます。

配列を連続する要素のグループに分割する

1つのリクエストにリストが含まれている場合――たとえば、ERPからの20件の注文や、在庫更新の一括処理など――通常は、ワークフローをバッチ全体に対して1回実行するのではなく、項目ごとに1回ずつ実行したいものです。

[詳細設定] → [配列をランに分割] で、配列のパスに名前を付けてください：

パス	次のような場合に使用してください
items	この配列はトップレベルのフィールドです：{ "items": [ ... ] }
data.orders	これはネストされています：{ "data": { "orders": [ ... ] } }
$	本体自体が配列となっています：[ { ... }, { ... } ]
(空)	オフ。リクエストごとに1回実行されます（デフォルト設定です）。

各要素は、その要素自体をペイロードとする独立した実行単位となるため、マッピングのパスは当該アイテムを基準とします。つまり、map sku とし、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 }

ルールと制限

• 1回のリクエストにつき、最大100件までです。それ以上のバッチは拒否されるため、悪質な送信者によるワークフローへの過剰な送信を防ぐことができます。
• マッピングされたフィールドが欠けている項目や、Shopify Flowの処理容量を超える項目がある場合、リクエスト全体が拒否され、何も送信されません。その際、エラー情報には問題のある項目の位置が記載されます。これにより、バッチ処理は「半分だけ適用される」のではなく、「すべてか何もかも」という形になります。
• オブジェクトではなく単純な値である項目は、{ "value": ... } として受け取られます。
• スプリッティングは同期応答と組み合わせることはできません。つまり、1人の呼び出し元に対して複数の実行インスタンスで応答することはできません。同期応答 をご覧ください。
• 「履歴」から過去の実行を再生すると、バッチ全体ではなく、その1つの項目だけが再送信されます。

歴史において

各項目はそれぞれ個別のエントリとなっているため、それぞれを個別に確認したり、再試行したり、再生したりすることができます。