> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# jsonDOMGet

> 使用 jsonpath 映射从 JSON 文档中检索值，支持重复元素和数组。

export const siteNameShort = "知行之桥";

从 JSON 文档中获取值。

## 必需的参数

* **map:\***: 一组一个或多个输入，其中映射参数的名称以冒号开头（例如，`map:foo`），并且值是文档中所需 json 元素的 jsonpath（请参阅[示例](#示例) 了解详情）。

## 可选的参数

* **uri**: JSON 文件的 URI。这可以是动态文件引用，例如输入文件的 `[FilePath]`、磁盘上的静态文件路径或 JSON 文件的公共 URL。
* **text**：对 JSON 数据的可读句柄引用。 此句柄由 [jsonOpen](./op-json-open) 操作创建，当输入 JSON 不是文件或原始文本，或者需要执行访问文档的文件数据的多个操作时，此句柄非常有用。
* **handle**: 对 JSON 数据的可读句柄引用。 该句柄由 jsonOpen 运算器创建，仅当目标 JSON 不是输入文件时才需要。 有关详细信息和示例，请参阅 [jsonOpen](./op-json-open)。
* **repeatelement#**: 文档中重复出现的元素的 jsonpath。
* **repeatmode**: 定义 `repeatelement#` 值在输出项上的存储方式。 允许的值为 `ITEM` 和 `ARRAY` 。 当设置为 `ITEM`（默认值）时，从重复元素找到的值将作为单独的属性存储在运算器生成的每个输出项上。 当设置为 `ARRAY` 时，从重复元素找到的值将作为数组属性存储在单个输出项上，并且需要通过其基于 1 的索引进行访问（例如，`[result.color#2]`将引用 到结果项的 `color` 属性中的第二个值）。

## 输出属性

* **\***: 使用 map 参数映射的 JSON 元素的输出值。 通过引用输出项和映射输入项的名称（例如 `[results.foo]`）来访问它们。 输出项的名称（在本例中为 `results`）由用户确定。 有关其他上下文，请参阅[示例](#示例)。

## 示例

### 从 JSON 文档中检索值

考虑以下的 JSON 数据，它作为输入数据传递给{siteNameShort}的 [Script 端口](../../connectors/script)：

```json theme={null}
{
    "name": "Nancy",
    "age": "31",
    "gender": "Female"
}
```

在 Script 端口中，可以在 {siteNameShort}Script 中调用 jsonDOMGet 来检索此数据中定义的人员的`name`和`age`，并将它们作为标题添加到 {siteNameShort} 中的消息中。 下面的 {siteNameShort}Script 代码显示了如何执行此操作的示例：

```xml theme={null}
<!-- Setting the input uri and map parameters -->
<arc:set attr="json.uri" value="[FilePath]" />
<arc:set attr="json.map:name" value="/json/name" />
<arc:set attr="json.map:age" value="/json/age" />

<!-- Calling the operation, passing in the json item and creating a "result" output item -->
<arc:call op="jsonDOMGet" in="json" out="result">
  <!-- result.name and result.age has the value of the json path because map:name and map:age was 
       set in the input to the op, and result is the name of the output item. Once this
       op closes, result falls out of scope, so use your value inside the arc:call block --> 
  <!-- Setting the values for name and age as headers on the message -->
  <arc:set attr="output.header:personsname" value="[result.name]" />
  <arc:set attr="output.header:personsage" value="[result.age]" />
</arc:call>

<!-- Setting the output file and pushing the file out -->
<arc:set attr="output.filepath" value="[FilePath]" />
<arc:push item="output" />
```

该代码执行后，{siteNameShort}将带有新添加的消息头的文件作为输出向下推送到工作流中。

### 访问 JSON 对象中数组的特定索引

用户经常需要访问 JSON 数据中数组的特定索引。 例如，可能想要访问下面 JSON 对象中 `orders` 数组中第二个订单对象的 `id`，该对象作为输入文件传递到 Script 端口。

```json theme={null}
{
    "warehouseid":"WH1234",
    "orders": [
        {
            "date": "02/27/2023",
            "id": "1234"
        },
        {
            "date": "02/28/2023",
            "id": "5678"
        },
        {
            "date": "03/01/2023",
            "id": "9876"
        }
    ]
}
```

在 Script 端口中，可以调用 {siteNameShort}Script 中的 jsonDOMGet 来使用`orders`数组中某个对象中存在的元素的从 1 开始的索引 jsonpath 来访问特定订单的`id`。 下面的 {siteNameShort}Script 代码显示了如何执行此操作的示例：

```xml theme={null}
<!-- Setting the input uri and map parameters -->
<arc:set attr="json.uri" value="[FilePath]" />
<arc:set attr="json.map:id" value="/json/orders/\[2\]/id" />

<!-- Calling the operation, passing in the json item and creating a "result" output item -->
<arc:call op="jsonDOMGet" in="json" out="result">
  <!-- Setting the result from the mapped id parameter as a header on the message -->
  <arc:set attr="output.header:orderid" value="[result.id]" />
</arc:call>

<!-- Setting the output file and pushing the file out -->
<arc:set attr="output.filepath" value="[FilePath]" />
<arc:push item="output" />
```

### 使用 repeatelement 参数

考虑下面的 JSON 数据，该数据作为输入文件传递到 Script 端口：

```json theme={null}
{
    "hello": "world",
    "colors": [
        {
            "color": "yellow",
            "example": "banana"
        },
        {
            "color": "red",
            "example": "apple"
        },
        {
            "color": "orange",
            "example": "orange"
        }
    ]
}
```

在 Script 端口内，针对输入文件执行以下代码。 `repeatelement#` 参数用于定义具有重复值的元素。 在此示例中， `color` 和 `example` 值在 `/json/colors` 元素中重复，该元素是一个 JSON 数组。 当设置 `repeatelement#` 时，jsonDOMGet 运算器将循环遍历该元素中存在的值。

`repeatmode` 参数定义 `repeatelement#` 值存储为输出的方式。 当设置为 `ITEM` （默认值）时，重复元素找到的值将作为单独的属性存储在输出项上。 当设置为 `ARRAY` 时，重复元素找到的值将作为数组属性存储在输出项上，并且需要通过基于 1 的索引进行访问（例如， `[result.color#2]` 将解析为 `red` 和 `result.example#2` 将解析为 `apple` ）。

```xml theme={null}
<!-- Initializing the output data -->
<arc:set attr="out.data" />
<!-- Setting the input uri, repeatmode and map parameters -->
<arc:set attr="json.uri" value="[FilePath]" />
<arc:set attr="json.repeatelement#" value="/json/colors/" />
<arc:set attr="json.repeatmode" value="ITEM" />
<!-- Note, the values for the map are relative to the repeatelement path -->
<arc:set attr="json.map:color" value="color" />
<arc:set attr="json.map:example" value="example" />

<!-- Calling the operation, passing in the json item and creating a "result" output item -->
<arc:call op="jsonDOMGet" in="json" out="result">
  <!-- Setting the output data to the enumerated results of the call -->
  <arc:set attr="out.data">[out.data]
    <arc:enum list="color,example" separator=",">[_value]: [result.[_value]]\n
    </arc:enum>
  </arc:set>
</arc:call>

<!-- Setting the output filename and pushing the file out -->
<arc:set attr="out.filename" value="data.txt" />
<arc:push item="out" />
```

输出文件：

```
color: yellow
example: banana
color: red
example: apple
color: orange
example: orange
```