> ## 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.

# xmlDOMGet

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

export const siteNameShort = "知行之桥";

从 XML 文档中获取值。

## 必需的参数

* **map:\***: 一组一个或多个输入，其中映射参数的名称位于冒号之前（例如 `map:foo`），值是文档中所需 XML 元素的 xpath。有关详细信息，请参阅[示例](#示例)。

## 可选的参数

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

## 输出属性

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

## 示例

### 从 XML 文档中检索值

请考虑以下 XML 数据，它作为输入数据传递给 {siteNameShort} 中的 Script 端口：

```xml theme={null}
<Items>
  <Car>
    <Make>Subaru</Make>
    <Model>WRX</Model>
  </Car>
</Items>
```

在 Script 端口中，你可以在 {siteNameShort}Script 中调用 xmlDOMGet，从此数据中检索汽车的 `make` 和 `model`，并将它们作为消息头添加到 {siteNameShort} 中的消息。下面的 {siteNameShort}Script 代码展示了如何执行此操作。

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

<!-- Calling the operation, passing in the xml item and creating a "result" output item -->
<arc:call op="xmlDOMGet" in="xml" out="result">
  <!-- result.make and result.model has the value of the xpath because map:make and map:model 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 make and model as headers on the message -->
  <arc:set attr="output.header:carmake" value="[result.make]" />
  <arc:set attr="output.header:carmodel" value="[result.model]" />
</arc:call>

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

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

### 使用索引访问特定的重复 XML 元素

用户经常需要访问特定的重复 XML 元素。例如，你可能想要访问以下 XML 中第二个 `order` 的 `id`，该 XML 作为输入文件传递给 Script 端口。

```xml theme={null}
<Items>
    <orders>
        <order>
            <date>02/27/2023</date>
            <id>1234</id>
        </order>
        <order>
            <date>02/28/2023</date>
            <id>5678</id>
        </order>
        <order>
            <date>03/01/2023</date>
            <id>9876</id>
        </order>
    </orders>
</Items>
```

在 Script 端口中，你可以在 {siteNameShort}Script 中调用 xmlDOMGet，使用某个重复 `orders` 元素中元素的从 1 开始的 xpath 来访问特定订单的 `id`。下面的 {siteNameShort}Script 代码展示了如何执行此操作。

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

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

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

### 使用 repeatelement 参数

请考虑以下 XML 数据，它作为输入文件传递给 Script 端口：

```xml theme={null}
<Items>
    <hello>world</hello>
    <colors>
        <color>yellow</color>
        <example>banana</example>
    </colors>
    <colors>
        <color>red</color>
        <example>apple</example>
    </colors>
    <colors>
        <color>orange</color>
        <example>orange</example>
    </colors>
</Items>
```

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

`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="xml.uri" value="[FilePath]" />
<arc:set attr="xml.repeatelement#" value="/Items/colors" />
<arc:set attr="xml.repeatmode" value="ITEM" />
<!-- Note, the values for the map are relative to the repeatelement path -->
<arc:set attr="xml.map:color" value="color" />
<arc:set attr="xml.map:example" value="example" /> 

<!-- Calling the operation, passing in the xml item and creating a "result" output item -->
<arc:call op="xmlDOMGet" in="xml" 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
```