> ## 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 端口中，你可以在 ArcScript 中呼叫 xmlDOMGet，從此資料中檢索汽車的 `make` 和 `model`，並將它們作為訊息頭新增到 {siteNameShort} 中的訊息。下面的 ArcScript 程式碼展示瞭如何執行此操作。

```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 端口中，你可以在 ArcScript 中呼叫 xmlDOMGet，使用某個重複 `orders` 元素中元素的從 1 開始的 xpath 來存取特定訂單的 `id`。下面的 ArcScript 程式碼展示瞭如何執行此操作。

```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
```