本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 IDT 內容
<a name="idt-context"></a>

當 IDT 執行測試套件時，測試套件可以存取一組資料，用於判斷每個測試的執行方式。此資料稱為 IDT 內容。例如，`userdata.json`在 IDT 內容中，測試執行器提供的使用者資料組態可用於測試套件。

IDT 內容可視為唯讀 JSON 文件。測試套件可以使用物件、陣列、數字等標準 JSON 資料類型，從 擷取資料並將資料寫入內容。

## 內容結構描述
<a name="idt-context-schema"></a>

IDT 內容使用下列格式：

```
{
    "config": {
        <config-json-content>
        "timeoutMultiplier": timeout-multiplier,
        "idtRootPath": <path/to/IDT/root>
    },
    "device": {
        <device-json-device-element>
    },
    "devicePool": {
        <device-json-pool-element>
    },
    "resource": {
        "devices": [
            {
                <resource-json-device-element>
                "name": "<resource-name>"
            }
        ]
    },
    "testData": {
        "awsCredentials": {
            "awsAccessKeyId": "<access-key-id>",
            "awsSecretAccessKey": "<secret-access-key>",
            "awsSessionToken": "<session-token>"
        },
        "logFilePath": "/path/to/log/file"
    },
    "userData": {
        <userdata-json-content>
    }
}
```

**`config`**  
來自 [`config.json` 檔案](set-config-custom.md#config-json-custom)的資訊。`config` 欄位也包含下列其他欄位：    
**`config.timeoutMultiplier`**  
測試套件使用的任何逾時值的乘數。此值由 IDT CLI 的測試執行器指定。預設值為 `1`。  
**`config.idRootPath`**  
此值是設定`userdata.json`檔案時 IDT 絕對路徑值的預留位置。這由建置和快閃記憶體命令使用。

**`device`**  
為測試執行選取之裝置的相關資訊。此資訊等同於所選裝置的 [`device.json` 檔案中](set-config-custom.md#device-config-custom)的`devices`陣列元素。

**`devicePool`**  
為測試執行選取之裝置集區的相關資訊。此資訊等同於所選裝置集區`device.json`檔案中定義的最上層裝置集區陣列元素。

**`resource`**  
`resource.json` 檔案中資源裝置的相關資訊。    
**`resource.devices`**  
此資訊等同於 `resource.json` 檔案中定義的`devices`陣列。每個`devices`元素都包含下列額外欄位：    
**`resource.device.name`**  
資源裝置的名稱。此值設定為 `test.json` 檔案中`requiredResource.name`的值。

**`testData.awsCredentials`**  
測試用來連線至雲端的 AWS AWS 登入資料。此資訊是從 `config.json` 檔案取得。

**`testData.logFilePath`**  
測試案例寫入日誌訊息的日誌檔案路徑。如果此檔案不存在，測試套件會建立此檔案。

**`userData`**  
測試執行器在 [`userdata.json` 檔案中](set-config-custom.md#userdata-config-custom)提供的資訊。

## 在內容中存取資料
<a name="accessing-context-data"></a>

您可以使用組態檔案和文字可執行檔中的 JSONPath 標記法，搭配 `GetContextValue`和 `GetContextString` APIs 來查詢內容。用於存取 IDT 內容的 JSONPath 字串語法會有所不同，如下所示：
+ 在 `suite.json`和 中`test.json`，您可以使用 `{{{{query}}}}`。也就是說，請勿使用根元素`$.`來啟動表達式。
+ 在 中`statemachine.json`，您可以使用 `{{$.{{query}}}}`。
+ 在 API 命令中，您可以使用 `{{query}}`或 `{{$.{{query}}}}`，視命令而定。如需詳細資訊，請參閱 SDKs中的內嵌文件。

下表說明典型foobar JSONPath 表達式中的運算子：


| 運算子  | 說明  | 
| --- | --- | 
| $ | 根元素。由於 IDT 的最上層內容值是 物件，因此您通常會使用 $. 來啟動查詢。 | 
| .childName | childName 使用 物件的名稱存取子元素。如果套用至陣列， 會產生新的陣列，並將此運算子套用至每個元素。元素名稱區分大小寫。例如，存取 config 物件中awsRegion值的查詢是 $.config.awsRegion。 | 
| [start:end] | 從陣列篩選元素，擷取從start索引開始到end索引的項目，兩者都包含在內。 | 
| [index1, index2, ... , indexN] | 從陣列篩選元素，僅從指定的索引擷取項目。 | 
| [?(expr)] | 使用 expr表達式篩選陣列中的元素。此表達式必須評估為布林值。 | 

若要建立篩選條件表達式，請使用下列語法：

```
{{<jsonpath>}} | {{<value>}} {{operator}} {{<jsonpath>}} | {{<value>}} 
```

在此語法中：
+ `jsonpath` 是使用標準 JSON 語法的 JSONPath。
+ `value` 是使用標準 JSON 語法的任何自訂值。
+ `operator` 是下列其中一個運算子：
  + `<` （小於）
  + `<=` （小於或等於）
  + `==` （等於）

    如果表達式中的 JSONPath 或值是陣列、布林值或物件值，則這是您可以唯一支援的二進位運算子。
  + `>=` （大於或等於）
  + `>` （大於）
  + `=~` （規則表達式比對）。若要在篩選條件表達式中使用此運算子，表達式左側的 JSONPath 或值必須評估為字串，而右側必須是遵循 [RE2 語法](https://github.com/google/re2/wiki/Syntax)的模式值。

您可以使用格式為 {{{{query}}}} 的 JSONPath 查詢，做為`test.json`檔案中 `args`和 `environmentVariables` 欄位內，以及`suite.json`檔案中 `environmentVariables` 欄位內的預留位置字串。IDT 會執行內容查詢，並將查詢的評估值填入欄位。例如，在 `suite.json` 檔案中，您可以使用預留位置字串來指定每個測試案例變更的環境變數值，IDT 會將每個測試案例的正確值填入環境變數。不過，當您在 `test.json`和 `suite.json` 檔案中使用預留位置字串時，下列考量適用於您的查詢：
+ 在所有小寫中，您必須在查詢中每次出現 `devicePool`金鑰。也就是說，請`devicepool`改用 。
+ 對於陣列，您只能使用字串陣列。此外，陣列使用非標準`item1, item2,...,itemN`格式。如果陣列只包含一個元素，則會將其序列化為 `item`，使其與字串欄位無法區分。
+ 您無法使用預留位置從內容中擷取物件。

由於這些考量，我們建議您盡可能使用 API 來存取測試邏輯中的內容，而不是 `test.json`和 `suite.json` 檔案中的預留位置字串。不過，在某些情況下，使用 JSONPath 預留位置擷取單一字串以設定為環境變數可能會更方便。