跳转至

JSON Extract Value 属性提取与 JMESPath 查询节点

使用 JMESPath 查询表达式从 JSON 数据中提取特定值。

节点核心功能 (Description)

JSON Extract Value 节点允许创作者利用强大的 JMESPath 查询语法从复杂的 JSON 数据载荷中精准提取目标字段。它深度支持多层嵌套对象访问、数组数字索引切片以及通配符批量提取算子，极大简化了从深层或大型 JSON 数据结构中导航与抽取信息的操作。

配置与参数规范 (Parameters)

输入插槽 (Input Parameters)

参数名称 (Parameter) 数据类型 (Type) 语义说明 (Description) 默认值 (Default)
json json, str, dict 待执行提取的目标源 JSON 数据。 {}
path str 用于定位与提取数据的 JMESPath 表达式（例如 'user.name'、'items[0].title'、'[*].assignee' 等）。 ""

输出引脚 (Output Parameters)

输出名称 (Parameter) 数据类型 (Type) 语义说明 (Description)
output json 依据路径精准提取并返回的数据工件。

核心特性解析 (Features)

  • JMESPath 强大语法支持：依托工业标准 JMESPath 语法，支持极高自由度的数据过滤与字段投影；
  • 点号路径导航 (Dot Notation)：使用直观的点号语法快速穿透多层嵌套的字典键；
  • 数组下标索引 (Array Indexing)：使用 [index] 语法精确定位列表中指定次序的元素；
  • 通配符投影操作 (Wildcard Operations)：使用 [*] 语法一键提取列表中所有对象的特定字段；
  • 原生 Python 类型返回：直接返回原生的 Python 对象（字符串、字典、列表、布尔等），下游开箱即用，无需多余的再次反序列化；
  • 空安全防御机制 (Safe Extraction)：若目标路径在 JSON 中不存在，安全降级返回空字典 {}，绝不导致抛错断流。

JMESPath 基础语法速查 (JMESPath Syntax)

📚 深入学习：关于 JMESPath 完整语法规则与高级特性，请参考 JMESPath 官方文档。

基础对象键访问 (Object Access)

# 访问嵌套对象属性
path = "user.name"  # 获取用户的姓名
path = "user.profile.email"  # 获取深层嵌套的邮箱地址

数组下标索引 (Array Indexing)

# 访问列表中的具体元素
path = "items[0]"  # 获取第一个元素
path = "items[0].title"  # 获取第一个元素的标题字段
path = "users[2].name"  # 获取第三个用户的名字

通配符批量投影 (Wildcard Operations)

# 提取数组中所有对象的指定字段并合并为列表
path = "items[*].title"  # 获取 items 列表中所有项目的 title 字段
path = "users[*].name"  # 获取 users 列表中所有用户的 name
path = "[*].assignee"  # 从根数组中提取所有受让人信息

深度复合路径 (Complex Paths)

# 组合对象与数组进行深度导航
path = "orders[0].items[1].price"  # 获取首个订单中第二个商品的单价
path = "projects[*].tasks[*].assignee"  # 获取所有项目下全部任务的所有受让人

使用代码示例 (Examples)

基础对象字段提取

# 输入 JSON: {"user": {"name": "John", "age": 30}}
# 路径 Path: "user.name"
# 输出 Output: "John"  # 返回原生 Python 字符串

数组单项提取

# 输入 JSON: {"items": [{"title": "Book", "price": 25}, {"title": "Magazine", "price": 10}]}
# 路径 Path: "items[0].title"
# 输出 Output: "Book"  # 返回原生 Python 字符串

目标路径不存在时的回退

# 输入 JSON: {"user": {"name": "John"}}
# 路径 Path: "user.email"
# 输出 Output: {}  # 目标键不存在时，安全返回空字典

多样化返回类型自适应

节点直接返回匹配到的原生类型，免除二次解析：

# 字符串提取 -> 返回 Python 字符串
# Path: "product.name" -> "Widget"

# 子对象提取 -> 返回 Python 原生字典
# Path: "user" -> {"name": "John", "age": 30}

# 数组提取 -> 返回 Python 原生列表
# Path: "items" -> [{"title": "Book"}, {"title": "Magazine"}]

典型适用场景 (Use Cases)

  • API 响应字段精确提取：从上游返回的几千行大型 API JSON 报文中，一键抓取关键业务字段；
  • 数据扁平化过滤：过滤多余冗余属性，仅保留下游节点消费的核心数组；
  • 配置项动态读取：从大型配置文件树中按路径解构出当前环境所需的特定分支；
  • 多模型输出拆解：配合 Agent 输出的结构化 JSON，解构分发至不同的下游展示界面。