JSON関数
JSON関数は、JSONテキストとWEL値の間で変換し、パスで構造をクエリします。
通常のレシピデータでJSON関数が必要になることはほとんどありません。入力フィールドはすでにWEL値として到着し、データを変換アクションが結果をシリアライズします。フィールド内にJSONが存在する場合、たとえば本文を文字列として配信するウェブフック、JSONドキュメントを保持するデータベース列、または送信先にテキストとして渡す必要があるペイロードなどで使用します。
変換
次の関数は、JSONテキストとWEL値の間で変換します:
parse_json
JSON文字列をWEL値に解析します。
parse_json(text, options)| パラメーター | 説明 |
|---|---|
| テキスト | 解析するJSON文字列。文字列以外のデータ型はE100をスローします。不正な形式のJSONテキストはE209をスローします。 {"a":1,"a":2}のようにキーが重複しているJSONオブジェクトは、最後の出現のみを暗黙的に保持するのではなく、E223をスローします。 129階層から256階層までのネストはE222をスローします。 256階層を超えるネストは代わりにE211をスローします。 |
| options | JSONのパース方法を制御するための任意指定のマップ。
E225をスローします。 |
JSON文字列をWEL値に解析する
次の例では、JSON文字列をWEL値に解析します:
Formula
parse_json('{"sku": "WID-1", "qty": 3}')出力
{sku: "WID-1", qty: 3}デフォルトでは金額の解析で精度が失われます
小数部を含むJSON数値はFloatになるため、149.50は149.5として解析され、小数位のスケールが失われます。フィールドが通貨額である場合は、{numbers: 'decimal'}を渡して、正確なDecimalとして扱われるようにします。金額でDecimalが重要な理由については、データ型を参照してください。
to_json
WEL値をJSON文字列にシリアライズします。
WELはListやMapを文字列に暗黙的に変換しません。誤ってコレクションを文字列化してしまうと、下流の処理で最も発見が難しい変換バグの一つになるためです。代わりに、これをテキストにするには、この関数または別の明示的なシリアライザーを呼び出します。
to_json(value, options)| パラメーター | 説明 |
|---|---|
| value | シリアライズする値。無限大のfloat値、またはトップレベルのSkip値はE210をスローします。 lambda値はE107を発生させます。 |
| options | シリアライズ設定のための任意指定のマップ。
E225をスローします。 |
WEL値をJSON文字列にシリアライズする
次の例では、WEL値をJSON文字列にシリアライズします:
Formula
to_json({sku: 'WID-1', qty: 3})出力
{"sku":"WID-1","qty":3}ユースケース: JSON文字列フィールドを展開する
ウェブフックは本文を単一の文字列フィールドとして配信します。 JSON関数を使用して解析し、送信先が受け入れるフィールドのみを保持します:
入力
{
"payload": "{\"order_id\":\"SO-1001\",\"total\":149.5,\"internal\":true}"
}Formula
parse_json(_.payload) >> pluck(['order_id', 'total'])出力
{"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をスローします。
json_path(value, path)| パラメーター | 説明 |
|---|---|
| value | クエリする構造。 |
| パス | StringとしてのJSONPath式。 |
ワイルドカードでネストされた構造をクエリする
次の例では、ワイルドカードを使用してネストされたリストからすべての価格を収集します:
Formula
json_path({store: {book: [{price: 10}, {price: 20}]}}, '$.store.book[*].price')出力
[10, 20]再帰的降下で任意の深さにある値をクエリする
次の例では、再帰的降下を使用して任意の深さにあるキーを検索します:
Formula
json_path({a: {b: {c: 'x'}}}, '$..c')出力
["x"]一致しないパスは空のリストを返す
次の例では、パスが何にも一致しない場合に空のリストを返します:
Formula
json_path({a: 1}, '$.missing')出力
[]ユースケース: ネストされたレスポンスからすべてのSKUを取り出す
APIは注文を返し、それぞれに独自の明細項目があります。各レベルを個別にたどるのではなく、1つの再帰パスでJSONPath式を使用してすべてのSKUを収集します:
入力
{
"orders": [
{"line_items": [{"sku": "WID-1"}, {"sku": "GAD-7"}]},
{"line_items": [{"sku": "BOX-2"}]}
]
}Formula
json_path(_, '$..line_items[*].sku')出力
["WID-1", "GAD-7", "BOX-2"]結果はリストなので、注文が存在しないペイロードの場合は[]が返されます。以降のステップは、nullで失敗するのではなく動作し続けます。
json_pointer
RFC 6901 JSONポインター(「/a/b/0」など)を使用して値を1つ解決します。 json_pathとは異なり、ポインターはちょうど1か所だけを指すため、結果はListではなく値そのものになります。
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
json_pointer(parse_json('{"a":{"b":1}}'), '/a/b')出力
1関連情報
- ディープマップ関数:
json_pathがサポートしないフィルターを含め、述語で値を収集します。 - マップ関数:
pluck、except、およびflatten_mapに関する情報。 - データ型: 金額の解析時に
Decimalが重要な理由。 - Error codes:
E100、E107、E209、E210、E211、E218、E219、E220、E222、E223、E229、E230などのジョブ失敗のトラブルシューティング。
最終更新日: