JSON関数 ​

このページは機械翻訳により提供されています。翻訳内容と英語版に相違がある場合は、英語版が優先されます。

JSON関数は、JSONテキストとWEL値の間で変換し、パスで構造をクエリします。

通常のレシピデータでJSON関数が必要になることはほとんどありません。入力フィールドはすでにWEL値として到着し、データを変換アクションが結果をシリアライズします。フィールド内にJSONが存在する場合、たとえば本文を文字列として配信するウェブフック、JSONドキュメントを保持するデータベース列、または送信先にテキストとして渡す必要があるペイロードなどで使用します。

変換 ​

次の関数は、JSONテキストとWEL値の間で変換します:

parse_json ​

JSON文字列をWEL値に解析します。

wel
parse_json(text, options)
パラメーター説明
テキスト解析するJSON文字列。文字列以外のデータ型はE100をスローします。不正な形式のJSONテキストはE209をスローします。 {"a":1,"a":2}のようにキーが重複しているJSONオブジェクトは、最後の出現のみを暗黙的に保持するのではなく、E223をスローします。 129階層から256階層までのネストはE222をスローします。 256階層を超えるネストは代わりにE211をスローします。
optionsJSONのパース方法を制御するための任意指定のマップ。
  • numbers: JSON数値をどのように表現するか。小数をFloatではなくDecimalとしてパースするには、'decimal'を指定します。
認識されないオプションキーは無視されず、E225をスローします。
JSON文字列をWEL値に解析する

次の例では、JSON文字列をWEL値に解析します:

Formula

wel
parse_json('{"sku": "WID-1", "qty": 3}')

出力

wel
{sku: "WID-1", qty: 3}

デフォルトでは金額の解析で精度が失われます

小数部を含むJSON数値はFloatになるため、149.50は149.5として解析され、小数位のスケールが失われます。フィールドが通貨額である場合は、{numbers: 'decimal'}を渡して、正確なDecimalとして扱われるようにします。金額でDecimalが重要な理由については、データ型を参照してください。

to_json ​

WEL値をJSON文字列にシリアライズします。

WELはListやMapを文字列に暗黙的に変換しません。誤ってコレクションを文字列化してしまうと、下流の処理で最も発見が難しい変換バグの一つになるためです。代わりに、これをテキストにするには、この関数または別の明示的なシリアライザーを呼び出します。

wel
to_json(value, options)
パラメーター説明
valueシリアライズする値。無限大のfloat値、またはトップレベルのSkip値はE210をスローします。 lambda値はE107を発生させます。
optionsシリアライズ設定のための任意指定のマップ。
  • spacing: トークン間に使用する空白文字。
  • indent: pretty出力のインデント。
  • pretty: 出力を複数行に整形します。
  • format_binary: Binary値をどのようにレンダリングするか。 'base64'、'base64url'、または'hex'を指定できます。
  • format_datetime: DateTime値をどのようにレンダリングするか。
  • format_date: PlainDate値をどのようにレンダリングするか。
  • number_format: 数値をどのようにレンダリングするか。 'js_safe'は、JSON数値がJavaScriptで正確に表現できる範囲外の整数を、素の数値ではなく文字列としてシリアライズします。
認識されないオプションキーはE225をスローします。
WEL値をJSON文字列にシリアライズする

次の例では、WEL値をJSON文字列にシリアライズします:

Formula

wel
to_json({sku: 'WID-1', qty: 3})

出力

wel
{"sku":"WID-1","qty":3}

ユースケース: JSON文字列フィールドを展開する ​

ウェブフックは本文を単一の文字列フィールドとして配信します。 JSON関数を使用して解析し、送信先が受け入れるフィールドのみを保持します:

入力

json
{
  "payload": "{\"order_id\":\"SO-1001\",\"total\":149.5,\"internal\":true}"
}

Formula

wel
parse_json(_.payload) >> pluck(['order_id', 'total'])

出力

json
{"order_id": "SO-1001", "total": 149.5}

pluckは許可リストであるため、internalは削除され、ソースが後で追加するフィールドも削除されます。

パスでクエリ ​

次の関数は、先にWEL値に解析することなく、JSONPath式を使用して構造をクエリします:

json_path ​

WELがサポートするRFC 9535 JSONPathのサブセットを使用して値をクエリします。一致したノードのListを返し、一致がない場合は空のリストを返します。

サポートされているセレクター:

セレクター構文意味
ルート$渡されたvalue。 $単体は、valueがnullであっても常にマッチします。
子.key, ['key']Mapの名前付きフィールド。キーに空白やドットなど.keyで表現できない文字が含まれる場合は、['key']のブラケット形式を使用します。
インデックス[0], [-1]List内の、ある位置にある要素。負のインデックスは末尾から数えるため、[-1]は最後の要素を選択します。
ワイルドカード[*], .*位置やキーでのフィルタリングを行わず、Listのすべての要素、またはMapのすべての値。
再帰的降下..key, ..*任意のネストの深さで、keyに一致するすべて、または..*を使ったすべての値。
スライス[start:end:step]Listのstartからendの直前まで、step要素ごとに進みながら範囲を指定します。 startを省略するとリストの先頭が既定値になり、endを省略するとリストの末尾が既定値になり、stepを省略すると1が既定値になります。

フィルター、ユニオン、関数拡張は、RFC 9535の正式な機能ですが、WELはこれらをサポートしないため、使用するとE220をスローします。代わりにdeep_collect_byまたはfilter_byを使用します。無効なセレクターはE219をスローします。

wel
json_path(value, path)
パラメーター説明
valueクエリする構造。
パスStringとしてのJSONPath式。
ワイルドカードでネストされた構造をクエリする

次の例では、ワイルドカードを使用してネストされたリストからすべての価格を収集します:

Formula

wel
json_path({store: {book: [{price: 10}, {price: 20}]}}, '$.store.book[*].price')

出力

wel
[10, 20]
再帰的降下で任意の深さにある値をクエリする

次の例では、再帰的降下を使用して任意の深さにあるキーを検索します:

Formula

wel
json_path({a: {b: {c: 'x'}}}, '$..c')

出力

wel
["x"]
一致しないパスは空のリストを返す

次の例では、パスが何にも一致しない場合に空のリストを返します:

Formula

wel
json_path({a: 1}, '$.missing')

出力

wel
[]

ユースケース: ネストされたレスポンスからすべてのSKUを取り出す ​

APIは注文を返し、それぞれに独自の明細項目があります。各レベルを個別にたどるのではなく、1つの再帰パスでJSONPath式を使用してすべてのSKUを収集します:

入力

json
{
  "orders": [
    {"line_items": [{"sku": "WID-1"}, {"sku": "GAD-7"}]},
    {"line_items": [{"sku": "BOX-2"}]}
  ]
}

Formula

wel
json_path(_, '$..line_items[*].sku')

出力

json
["WID-1", "GAD-7", "BOX-2"]

結果はリストなので、注文が存在しないペイロードの場合は[]が返されます。以降のステップは、nullで失敗するのではなく動作し続けます。

json_pointer ​

RFC 6901 JSONポインター(「/a/b/0」など)を使用して値を1つ解決します。 json_pathとは異なり、ポインターはちょうど1か所だけを指すため、結果はListではなく値そのものになります。

wel
json_pointer(value, pointer)
パラメーター説明
valueクエリする構造。
ポインターStringとしてのRFC 6901ポインター。各トークンは、valueがMapの場合はキー(Unicode正規化は行われません)、valueがListの場合はインデックスを参照します。空でないポインターは/で始まっている必要があります。空文字列はvalueをそのまま返し、nullやSkipも含めて変更しません。文字列以外のデータ型はE100をスローします。 URIフラグメント(#/a)、相対ポインター、ワイルドカード、およびパーセントデコードは、捕捉可能なE229をスローします。構文的には有効でも解決できないポインターはE230をスローします。

トークン内では、~1は/に、~0は~にデコードされるため、これらの文字を含むキーにはエスケープ形式が必要です。~の後に他の任意の文字が続く場合は無効な構文となり、E229をスローします。

json_pointerは既に存在する値のみを解決するため、WELは範囲外のリストインデックス、先頭に0を含むインデックス、または-の追加トークンに対してE230を発生させます。

E229とE230はいずれも捕捉可能なため、json_pointer(data, '/optional/value') |? nullは、パスが存在しない可能性がある場合のフォールバックを提供します。

ポインターで入れ子になったフィールドを参照

Formula

wel
json_pointer(parse_json('{"a":{"b":1}}'), '/a/b')

出力

wel
1
  • ディープマップ関数: json_pathがサポートしないフィルターを含め、述語で値を収集します。
  • マップ関数: pluck、except、およびflatten_mapに関する情報。
  • データ型: 金額の解析時にDecimalが重要な理由。
  • Error codes: E100、E107、E209、E210、E211、E218、E219、E220、E222、E223、E229、E230などのジョブ失敗のトラブルシューティング。

最終更新日: