> ## 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 端口中，可以在 ArcScript 中呼叫 jsonDOMGet 來檢索此資料中定義的人員的`name`和`age`，並將它們作為標題新增到 {siteNameShort} 中的訊息中。 下面的 ArcScript 程式碼顯示瞭如何執行此操作的範例：

```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 端口中，可以呼叫 ArcScript 中的 jsonDOMGet 來使用`orders`陣列中某個物件中存在的元素的從 1 開始的索引 jsonpath 來存取特定訂單的`id`。 下面的 ArcScript 程式碼顯示瞭如何執行此操作的範例：

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