本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# Device Advisor 工作流程
本教學課程說明如何建立自訂測試套件，以及針對您要在主控台中測試的裝置執行測試。在測試完成之後，您可以檢視測試結果和詳細記錄。
## 先決條件
開始本教學課程之前，請先完成[設定](device-advisor-setting-up.md)中概述的步驟。
## 建立測試套件定義
首先，[安裝 AWS SDK](https://docs.aws.amazon.com/iot/latest/developerguide/iot-connect-service.html#iot-service-sdks)。
### `rootGroup` 語法
根群組是 JSON 字串，指定哪些測試案例包含在您的測試套件中。它也會針對這些測試案例指定任何必要的組態。使用根群組根據您的需求建構和排序您的測試套件。測試套件的階層如下：
```
test suite → test group(s) → test case(s)
```
一個測試套件必須至少具有一個測試群組，而且每個測試群組必須至少具有一個測試案例。Device Advisor 會依您定義測試群組和測試案例的順序執行測試。
每個根群組都遵循這個基本結構：
```
{
"configuration": { // for all tests in the test suite
"": ""
}
"tests": [{
"name": ""
"configuration": { // for all sub-groups in this test group
"": ""
},
"tests": [{
"name": ""
"configuration": { // for all test cases in this test group
"": ""
},
"test": {
"id": ""
"version": ""
}
}]
}]
}
```
在根群組中，您可以使用 `name`、`configuration`，以及群組包含的 `tests` 來定義測試套件。`tests` 群組包含個別測試的定義。您可以使用 `name`、`configuration`，以及針對該測試定義測試案例的 `test` 區塊來定義每個測試。最後，每個測試案例都是使用 `id` 和 `version` 定義的。
如需如何為每個測試案例 (`test` 區塊) 使用 `"id"` 和 `"version"` 欄位的相關資訊，請參閱 [Device Advisor 測試案例](device-advisor-tests.md)。該節還包含可用 `configuration` 設定的相關資訊。
下列區塊是根群組組態的範例。此組態指定 *MQTT Connect Happy Case* 和 *MQTT Connect Exponential Backoff Retries* 測試案例，以及組態欄位的描述。
```
{
"configuration": {}, // Suite-level configuration
"tests": [ // Group definitions should be provided here
{
"name": "My_MQTT_Connect_Group", // Group definition name
"configuration": {} // Group definition-level configuration,
"tests": [ // Test case definitions should be provided here
{
"name": "My_MQTT_Connect_Happy_Case", // Test case definition name
"configuration": {
"EXECUTION_TIMEOUT": 300 // Test case definition-level configuration, in seconds
},
"test": {
"id": "MQTT_Connect", // test case id
"version": "0.0.0" // test case version
}
},
{
"name": "My_MQTT_Connect_Jitter_Backoff_Retries", // Test case definition name
"configuration": {
"EXECUTION_TIMEOUT": 600 // Test case definition-level configuration, in seconds
},
"test": {
"id": "MQTT_Connect_Jitter_Backoff_Retries", // test case id
"version": "0.0.0" // test case version
}
}]
}]
}
```
您必須在建立測試套件定義時提供根群組組態。儲存回應物件中傳回的 `suiteDefinitionId`。您可以使用此 ID 擷取測試套件定義資訊，以及執行測試套件。
以下是一個 Java 開發套件範例：
```
response = iotDeviceAdvisorClient.createSuiteDefinition(
CreateSuiteDefinitionRequest.builder()
.suiteDefinitionConfiguration(SuiteDefinitionConfiguration.builder()
.suiteDefinitionName("your-suite-definition-name")
.devices(
DeviceUnderTest.builder()
.thingArn("your-test-device-thing-arn")
.certificateArn("your-test-device-certificate-arn")
.deviceRoleArn("your-device-role-arn") //if using SigV4 for MQTT over WebSocket
.build()
)
.rootGroup("your-root-group-configuration")
.devicePermissionRoleArn("your-device-permission-role-arn")
.protocol("MqttV3_1_1 || MqttV5 || MqttV3_1_1_OverWebSocket || MqttV5_OverWebSocket")
.build()
)
.build()
)
```
## 取得測試套件定義
在建立您的測試套件定義之後，您會在 `CreateSuiteDefinition` API 操作的回應物件中收到 `suiteDefinitionId`。
當此操作傳回 `suiteDefinitionId` 時，您可能會在每個群組內看到新的 `id` 欄位，以及在根群組內看到測試案例定義。您可以使用這些 ID 來執行測試套件定義的子集。
Java 開發套件範例：
```
response = iotDeviceAdvisorClient.GetSuiteDefinition(
GetSuiteDefinitionRequest.builder()
.suiteDefinitionId("your-suite-definition-id")
.build()
)
```
## 取得測試端點
使用 `GetEndpoint` API 操作取得裝置所使用的測試端點。選取最適合您測試的端點。若要同時執行多個測試套件，請透過提供 `thing ARN`、`certificate ARN` 或 `device role ARN` 來使用裝置層級端點。若要執行單一測試套件，請不提供引數給 GetEndpoint 操作，以選擇帳戶層級端點。
開發套件範例：
```
response = iotDeviceAdvisorClient.getEndpoint(GetEndpointRequest.builder()
.certificateArn("your-test-device-certificate-arn")
.thingArn("your-test-device-thing-arn")
.deviceRoleArn("your-device-role-arn") //if using SigV4 for MQTT over WebSocket
.build())
```
## 啟動測試套件執行
在建立了測試套件定義，並將測試裝置設定為連線至 Device Advisor 測試端點之後，請使用 `StartSuiteRun` API 執行您的測試套件。
對於 MQTT 客戶，請使用 `certificateArn` 或 `thingArn` 執行測試套件。當設定這兩者時，如果憑證屬於物件，則會使用此憑證。
對於 MQTT over WebSocket 客戶，請使用 `deviceRoleArn` 來執行測試套件。如果指定的角色與測試套件定義中指定的角色不同，則指定的角色會覆寫定義的角色。
對於 `.parallelRun()`，如果使用裝置層級端點，來使用一個 AWS 帳戶平行執行多個測試套件，請使用 `true`。
開發套件範例：
```
response = iotDeviceAdvisorClient.startSuiteRun(StartSuiteRunRequest.builder()
.suiteDefinitionId("your-suite-definition-id")
.suiteRunConfiguration(SuiteRunConfiguration.builder()
.primaryDevice(DeviceUnderTest.builder()
.certificateArn("your-test-device-certificate-arn")
.thingArn("your-test-device-thing-arn")
.deviceRoleArn("your-device-role-arn") //if using SigV4 for MQTT over WebSocket
.build())
.parallelRun(true | false)
.build())
.build())
```
從回應儲存 `suiteRunId`。您將使用此資訊來擷取此測試套件執行的結果。
## 取得測試套件執行
在您開始測試套件執行之後，您可以使用 `GetSuiteRun` API 來檢查其進度及結果。
開發套件範例：
```
// Using the SDK, call the GetSuiteRun API.
response = iotDeviceAdvisorClient.GetSuiteRun(
GetSuiteRunRequest.builder()
.suiteDefinitionId("your-suite-definition-id")
.suiteRunId("your-suite-run-id")
.build())
```
## 停止測試套件執行
若要停止仍在進行的測試套件執行，您可以呼叫 `StopSuiteRun` API 操作。在您呼叫 `StopSuiteRun` API 操作之後，服務將會啟動清除程序。當服務執行清除程序時，測試套件執行狀態會更新為 `Stopping`。清除程序需要幾分鐘的時間來完成。一旦此程序完成，測試套件執行狀態就會更新為 `Stopped`。在測試執行完全停止之後，您可以啟動另一個測試套件執行。您可以使用 `GetSuiteRun` API 操作定期檢查套件執行狀態，如上節所示。
開發套件範例：
```
// Using the SDK, call the StopSuiteRun API.
response = iotDeviceAdvisorClient.StopSuiteRun(
StopSuiteRun.builder()
.suiteDefinitionId("your-suite-definition-id")
.suiteRunId("your-suite-run-id")
.build())
```
## 取得成功資格測試套件執行的資格報告
如果執行成功完成的資格測試套件，則可以使用 `GetSuiteRunReport` API 操作擷取資格報告。您可以使用此資格報告，搭配 AWS IoT Core 資格計畫限定您的裝置。若要判斷您的測試套件是否為資格測試套件，請檢查 `intendedForQualification` 參數是否設定為 `true`。在呼叫 `GetSuiteRunReport` API 操作之後，您可以從傳回的 URL 下載報告，最長可達 90 秒。如果上次呼叫 `GetSuiteRunReport` API 操作的經歷時間超過 90 秒，請再次呼叫該操作來擷取新的有效 URL。
開發套件範例：
```
// Using the SDK, call the getSuiteRunReport API.
response = iotDeviceAdvisorClient.getSuiteRunReport(
GetSuiteRunReportRequest.builder()
.suiteDefinitionId("your-suite-definition-id")
.suiteRunId("your-suite-run-id")
.build()
)
```