本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 AWS IoT Device Tester for AWS IoT Greengrass V2 AWS IoT Device Tester (IDT) 是可下載的測試架構，可讓您驗證 IoT 裝置。您可以使用 IDT for AWS IoT Greengrass AWS IoT Greengrass 來執行資格套件，並為您的裝置建立和執行自訂測試套件。 IDT for 會在連接到要測試之裝置的主機電腦 (Windows、macOS 或 Linux) AWS IoT Greengrass 上執行。它會執行測試並彙總結果。它還提供命令列界面來管理測試程序。 ## AWS IoT Greengrass 資格套件 使用 AWS IoT Device Tester for AWS IoT Greengrass V2 來驗證 AWS IoT Greengrass 核心軟體是否在您的硬體上執行，並且可以與 通訊 AWS 雲端。它也會使用 end-to-end測試 AWS IoT Core。例如，它會驗證您的裝置是否可以部署元件並進行升級。 如果您想要將硬體新增至 AWS Partner Device Catalog，請 AWS IoT Greengrass 執行資格套件來產生可提交的測試報告 AWS IoT。如需詳細資訊，請參閱 [AWS 裝置資格計劃](https://aws.amazon.com/partners/dqp/)。 ![\[AWS IoT Device Tester for AWS IoT Greengrass V2 如何驗證 AWS IoT Greengrass 核心軟體是否在您的硬體上執行，以及如何與 通訊的概觀 AWS 雲端。\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/images/devicetester_gg.png) IDT for AWS IoT Greengrass V2 使用測試*套件*和*測試群組*的概念來組織測試。 + 測試套件是一組測試群組，用來驗證裝置是否適用於特定版本的 AWS IoT Greengrass。 + 測試群組是與特定功能相關的一組個別測試，例如元件部署。 如需詳細資訊，請參閱[使用 IDT AWS IoT Greengrass 執行資格套件](idt-greengrass-qualification.md)。 ## 自訂測試套件 從 IDT v4.0.1 開始，IDT for AWS IoT Greengrass V2 結合了標準化的組態設定和結果格式，以及測試套件環境，可讓您為裝置和裝置軟體開發自訂測試套件。您可以為自己的內部驗證新增自訂測試，或將其提供給客戶進行裝置驗證。 測試寫入器如何設定自訂測試套件，決定執行自訂測試套件所需的設定組態。如需詳細資訊，請參閱[使用 IDT 來開發和執行您自己的測試套件](idt-custom-tests.md)。 # for AWS IoT Greengrass V2 AWS IoT Device Tester 支援的版本 本主題列出支援的 IDT for AWS IoT Greengrass V2 版本。最佳實務是建議您使用支援目標版本 AWS IoT Greengrass V2 的最新版本 IDT for AWS IoT Greengrass V2。的新版本 AWS IoT Greengrass 可能需要您下載新版本的 IDT for AWS IoT Greengrass V2。如果 IDT for AWS IoT Greengrass V2 與您 AWS IoT Greengrass 正在使用的 版本不相容，您會在啟動測試執行時收到通知。 下載軟體即表示您同意[AWS IoT Device Tester 授權合約](https://docs.aws.amazon.com/greengrass/v2/developerguide/idt-license.html)。 **注意** IDT 不支援由多位使用者從共用位置執行，例如 NFS 目錄或 Windows 網路共用資料夾。我們建議您將 IDT 套件解壓縮到本機磁碟機，並在本機工作站上執行 IDT 二進位檔。 ## 最新版 IDT for AWS IoT Greengrass V2 您可以使用此版本的 IDT for AWS IoT Greengrass V2 搭配此處列出的 AWS IoT Greengrass 版本。 **適用於 的 IDT v4.9.4 AWS IoT Greengrass** 支援的 AWS IoT Greengrass 版本： + [Greengrass 核](greengrass-nucleus-component.md) v2.12.0、v2.11.0、v2.10.0 和 v2.9.5 IDT 軟體下載： + IDT v4.9.4 搭配測試套件 GGV2Q\$12.5.4 for [Linux](https://docs.aws.amazon.com/greengrass/v2/developerguide/devicetester_greengrass_v2_4.9.4_testsuite_2.5.4_linux.zip) + IDT v4.9.4 搭配適用於 [macOS](https://docs.aws.amazon.com/greengrass/v2/developerguide/devicetester_greengrass_v2_4.9.4_testsuite_2.5.4_mac.zip) 的測試套件 GGV2Q\$12.5.4 + IDT v4.9.4 搭配測試套件 GGV2Q\$12.5.4 for [Windows](https://docs.aws.amazon.com/greengrass/v2/developerguide/devicetester_greengrass_v2_4.9.4_testsuite_2.5.4_win.zip) 版本備註： + 針對執行 AWS IoT Greengrass Core 軟體版本 2.12.0、2.11.0、2.10.0 和 2.9.5 的裝置，啟用裝置驗證和資格。 + 移除串流管理員和機器學習測試群組。 其他備註： + 如果您的裝置使用 HSM，且您使用的是 2.10.x 核心，請遷移至 Greengrass 2.11.0 版或更新版本。 測試套件版本： `GGV2Q_2.5.4` + 版 2024.05.03 ## 的早期 IDT 版本 AWS IoT Greengrass 也支援下列舊版的 IDT for AWS IoT Greengrass V2。 **適用於 的 IDT v4.9.3 AWS IoT Greengrass** 支援的 AWS IoT Greengrass 版本： + [Greengrass 核](greengrass-nucleus-component.md) v2.12.0、v2.11.0、v2.10.0 和 v2.9.5 IDT 軟體下載： + IDT v4.9.3 搭配測試套件 GGV2Q\$12.5.3 for [Linux](https://docs.aws.amazon.com/greengrass/v2/developerguide/devicetester_greengrass_v2_4.9.3_testsuite_2.5.3_linux.zip) + 適用於 [macOS](https://docs.aws.amazon.com/greengrass/v2/developerguide/devicetester_greengrass_v2_4.9.3_testsuite_2.5.3_mac.zip) 的測試套件 GGV2Q\$12.5.3 的 IDT v4.9.3 + IDT v4.9.3 搭配測試套件 GGV2Q\$12.5.3 for [Windows](https://docs.aws.amazon.com/greengrass/v2/developerguide/devicetester_greengrass_v2_4.9.3_testsuite_2.5.3_win.zip) 版本備註： + 修正從 Windows 主機測試 Linux 裝置時元件測試中的問題，反之亦然。 + 從`localcomponent`測試群組中移除`component`測試案例。資格不再需要此測試案例。 其他備註： + 如果您的裝置使用 HSM，且您使用的是 2.10.x 核心，請遷移至 Greengrass 2.11.0 版或更新版本。 測試套件版本： `GGV2Q_2.5.3` + 版 2024.04.05 ## 不支援的 AWS IoT Device Tester for AWS IoT Greengrass V2 版本 本主題列出不支援的 IDT for AWS IoT Greengrass V2 版本。不支援的版本不會收到錯誤修正或更新。如需詳細資訊，請參閱[適用於 AWS IoT Device Tester 的支援政策 AWS IoT Greengrass](idt-support-policy.md)。 **適用於 的 IDT v4.9.2 AWS IoT Greengrass** 版本備註： + 修正 Lambda 測試套件因 Java 8 已棄用而失敗的問題。 測試套件版本： `GGV2Q_2.5.2` + 版 2024.03.18 **適用於 的 IDT v4.9.1 AWS IoT Greengrass** 版本備註： + 可讓您驗證並限定執行 AWS IoT Greengrass Core 軟體版本 2.12.0、2.11.0、2.10.0 和 2.9.5 的裝置。 + 次要錯誤修正。 測試套件版本： `GGV2Q_2.5.1` + 版 2023.10.05 **適用於 的 IDT v4.7.0 AWS IoT Greengrass** 支援的 AWS IoT Greengrass 版本： + [Greengrass 核 v](greengrass-nucleus-component.md)2.11.0、v2.10.0 和 v2.9.5 版本備註： + 可讓您驗證並限定執行 AWS IoT Greengrass Core 軟體版本 2.11.0、2.10.0 和 2.9.5 的裝置。 + 新增支援，以在 AWS Systems Manager 參數存放區中存放 IDT 使用者資料值，並使用預留位置語法將其擷取到組態中。 + 次要錯誤修正。 測試套件版本： `GGV2Q_2.5.0` + 版 2022.12.13 **適用於 的 IDT v4.5.11 AWS IoT Greengrass** 版本備註： + 可讓您驗證並限定執行 AWS IoT Greengrass Core 軟體版本 2.9.1、2.9.0、2.8.1、2.8.0、2.7.0 和 2.6.0 的裝置。 + 新增在核心裝置上測試 PreInstalled Greengrass 的支援。 + 次要錯誤修正。 測試套件版本： `GGV2Q_2.4.1` + 版 2022.10.13 **適用於 的 IDT v4.5.8 AWS IoT Greengrass** 版本備註： + 可讓您驗證並限定執行 AWS IoT Greengrass Core 軟體版本 2.7.0、2.6.0 和 2.5.6 的裝置。 + 可讓您在核心裝置上使用 PreInstalled Greengrass 進行測試。 + 次要錯誤修正。 測試套件版本： `GGV2Q_2.4.0` + 版 2022.08.12 **適用於 的 IDT v4.5.3 AWS IoT Greengrass** 版本備註： + 可讓您驗證並限定執行 AWS IoT Greengrass Core 軟體版本 2.7.0、2.6.0、2.5.6、2.5.5、2.5.4 和 2.5.3 的裝置。 + 更新 DockerApplicationManager 測試以使用 ECR 型 docker 映像。 + 次要錯誤修正。 測試套件版本： `GGV2Q_2.3.1` + 版 2022.04.15 **適用於 的 IDT v4.5.1 AWS IoT Greengrass** 版本備註： + 可讓您驗證並限定執行 AWS IoT Greengrass Core 軟體 v2.5.3 的裝置。 + 新增支援，以驗證和驗證使用硬體安全模組 (HSM) 來存放 AWS IoT Greengrass Core 軟體所使用的私有金鑰和憑證的 Linux 型裝置。 + 實作新的 IDT 測試協調器來設定自訂測試套件。如需詳細資訊，請參閱[設定 IDT 測試協調器](idt-test-orchestrator.md)。 + 其他次要錯誤修正。 測試套件版本： `GGV2Q_2.3.0` + 版 2022.01.11 **適用於 的 IDT v4.4.1 AWS IoT Greengrass** 版本備註： + 可讓您驗證並限定執行 AWS IoT Greengrass Core 軟體 v2.5.2 的裝置。 + 新增使用使用者定義 IAM 角色做為權杖交換角色的支援，待測裝置會擔任此角色來與 AWS 資源互動。 您可以在 [`userdata.json`](set-config.md#userdata-config)檔案中指定 IAM 角色。如果您指定自訂角色，IDT 會使用該角色，而不是在測試執行期間建立預設字符交換角色。 + 其他次要錯誤修正。 測試套件版本： `GGV2Q_2.2.1` + 版 2021.12.12 **適用於 的 IDT v4.4.0 AWS IoT Greengrass** 版本備註： + 可讓您驗證並限定執行 AWS IoT Greengrass Core 軟體 v2.5.0 的裝置。 + 新增在 Windows 上執行 AWS IoT Greengrass Core 軟體的驗證和合格裝置的支援。 + 支援使用公有金鑰驗證進行安全 shell (SSH) 裝置連線。 + 使用安全最佳實務改善 IDT 許可 IAM 政策。 + 其他次要錯誤修正。 測試套件版本： `GGV2Q_2.1.0` + 版 2021.11.19 **適用於 的 IDT v4.2.0 AWS IoT Greengrass** 版本備註： + 包括對執行 AWS IoT Greengrass Core 軟體 v2.2.0 及更新版本之裝置上的下列功能資格的支援： + Docker—驗證裝置可以從 Amazon Elastic Container Registry (Amazon ECR) 下載 Docker 容器映像。 + 機器學習 - 驗證裝置可以使用[深度學習執行期](https://github.com/neo-ai/neo-ai-dlr)或 [TensorFlow Lite](https://www.tensorflow.org/lite/guide/python) ML 架構執行機器學習 (ML) 推論。 + 串流管理員 - 驗證裝置可以下載、安裝和執行 AWS IoT Greengrass 串流管理員。 + 可讓您驗證並限定執行 AWS IoT Greengrass Core 軟體 v2.4.0、v2.3.0、v2.2.0 和 v2.1.0 的裝置。 + 將每個測試案例的測試日誌分組到 `/results//logs/`目錄中的個別 ** 資料夾。 + 其他次要錯誤修正。 測試套件版本： `GGV2Q_2.0.1` + 版 2021.08.31 **適用於 的 IDT v4.1.0 AWS IoT Greengrass** 版本備註： + 可讓您驗證並限定執行 AWS IoT Greengrass Core 軟體 v2.3.0、v2.2.0、v2.1.0 和 v2.0.5 的裝置。 + 透過移除指定 `GreengrassNucleusVersion`和 `GreengrassCLIVersion` 屬性的需求來改善`userdata.json`組態。 + 包括對 AWS IoT Greengrass Core 軟體 v2.1.0 和更新版本 Lambda 和 MQTT 功能資格的支援。您現在可以使用 IDT for AWS IoT Greengrass V2 來驗證您的核心裝置是否可以執行 Lambda 函數，以及裝置是否可以發佈和訂閱 AWS IoT Core MQTT 主題。 + 改善記錄功能。 + 其他次要錯誤修正。 測試套件版本： `GGV2Q_1.1.1` + 版 2021.06.18 **適用於 的 IDT v4.0.2 AWS IoT Greengrass** 版本備註： + 可讓您驗證並限定執行 AWS IoT Greengrass Core 軟體 v2.1.0 的裝置。 + 新增對 AWS IoT Greengrass Core 軟體 v2.1.0 和更新版本 Lambda 和 MQTT 功能資格的支援。您現在可以使用 IDT for AWS IoT Greengrass V2 來驗證您的核心裝置是否可以執行 Lambda 函數，以及裝置是否可以發佈和訂閱 AWS IoT Core MQTT 主題。 + 改善記錄功能。 + 其他次要錯誤修正。 測試套件版本： `GGV2Q_1.1.1` + 版 2021.05.05 **適用於 的 IDT v4.0.1 AWS IoT Greengrass** 版本備註： + 可讓您驗證並限定執行第 2 AWS IoT Greengrass 版軟體的裝置。 + 可讓您使用 AWS IoT Device Tester for 開發和執行自訂測試套件 AWS IoT Greengrass。如需詳細資訊，請參閱[使用 IDT 來開發和執行您自己的測試套件](idt-custom-tests.md)。 + 提供 macOS 和 Windows 的程式碼簽署 IDT 應用程式。在 macOS 上，您可能需要授予 IDT 的安全例外狀況。如需詳細資訊，請參閱[macOS 上的安全例外狀況](idt-troubleshooting.md#security-exception-macos)。 測試套件版本： `GGV2Q_1.0.0` + 版 2020.12.22 + 除非您將`features`陣列`value`中對應的 設定為 ，否則測試套件只會執行資格所需的測試`yes`。 # 下載 IDT for AWS IoT Greengrass V2 本主題說明下載 AWS IoT Device Tester for AWS IoT Greengrass V2 的選項。您可以使用下列其中一個軟體下載連結，也可以依照指示以程式設計方式下載 IDT。 **Topics** + [手動下載 IDT](#idt-download-options) + [以程式設計方式下載 IDT](#idt-programmatic-download-process) 下載軟體即表示您同意[AWS IoT Device Tester 授權合約](https://docs.aws.amazon.com/greengrass/v2/developerguide/idt-license.html)。 **注意** IDT 不支援由多位使用者從共用位置執行，例如 NFS 目錄或 Windows 網路共用資料夾。我們建議您將 IDT 套件解壓縮到本機磁碟機，並在本機工作站上執行 IDT 二進位檔。 ## 手動下載 IDT 本主題列出支援的 IDT for AWS IoT Greengrass V2 版本。最佳實務是，建議您使用支援目標版本 AWS IoT Greengrass V2 的最新版本 IDT for AWS IoT Greengrass V2。的新版本 AWS IoT Greengrass 可能需要您下載新版本的 IDT for AWS IoT Greengrass V2。如果 IDT for AWS IoT Greengrass V2 與您正在使用的 AWS IoT Greengrass 版本不相容，您會在啟動測試執行時收到通知。 **適用於 的 IDT v4.9.4 AWS IoT Greengrass** 支援的 AWS IoT Greengrass 版本： + [Greengrass 核](greengrass-nucleus-component.md) v2.12.0、v2.11.0、v2.10.0 和 v2.9.5 IDT 軟體下載： + IDT v4.9.4 搭配 [Linux](https://docs.aws.amazon.com/greengrass/v2/developerguide/devicetester_greengrass_v2_4.9.4_testsuite_2.5.4_linux.zip) 版測試套件 GGV2Q\$12.5.4 + IDT v4.9.4 搭配 [macOS](https://docs.aws.amazon.com/greengrass/v2/developerguide/devicetester_greengrass_v2_4.9.4_testsuite_2.5.4_mac.zip) 的測試套件 GGV2Q\$12.5.4 + IDT v4.9.4 搭配測試套件 GGV2Q\$12.5.4 for [Windows](https://docs.aws.amazon.com/greengrass/v2/developerguide/devicetester_greengrass_v2_4.9.4_testsuite_2.5.4_win.zip) 版本備註： + 為執行 AWS IoT Greengrass Core 軟體 2.12.0、2.11.0、2.10.0 和 2.9.5 版的裝置啟用裝置驗證和資格驗證。 + 移除串流管理員和機器學習測試群組。 其他備註： + 如果您的裝置使用 HSM，且您使用 2.10.x 的 核，請遷移至 Greengrass 核 2.11.0 版或更新版本。 測試套件版本： `GGV2Q_2.5.4` + 2024.05.03 版 ## 以程式設計方式下載 IDT IDT 提供 API 操作，可用來擷取 URL，以程式設計方式下載 IDT。您也可以使用此 API 操作來檢查您是否有最新版本的 IDT。此 API 操作具有下列端點。 ``` https://download.devicetester.iotdevicesecosystem.amazonaws.com/latestidt ``` 若要呼叫此 API 操作，您必須具有執行 **iot-device-tester:LatestIdt**動作的許可。包含您的 AWS 簽章，並使用 `iot-device-tester`做為服務名稱。 ### API 請求 HostOs主機機器的作業系統。您可以從以下選項中選擇： + `mac` + `linux` + `windows` TestSuiteType – 測試套件的類型。選擇下列選項： `GGV2` – IDT for AWS IoT Greengrass V2 ProductVersion （選用） Greengrass 核的版本。服務會針對該版本的 Greengrass 核傳回最新的相容 IDT 版本。如果您未指定此選項，服務會傳回最新版本的 IDT。 ### API 回應 API 回應的格式如下。`DownloadURL` 包含 zip 檔案。 ``` { "Success": True or False, "Message": Message, "LatestBk": { "Version": The version of the IDT binary, "TestSuiteVersion": The version of the test suite, "DownloadURL": The URL to download the IDT Bundle, valid for one hour } } ``` ### 範例 您可以參考下列範例以程式設計方式下載 IDT。這些範例使用您存放在 `AWS_ACCESS_KEY_ID`和 `AWS_SECRET_ACCESS_KEY`環境變數中的登入資料。若要遵循最佳安全實務，請勿將登入資料存放在程式碼中。 **Example 範例：使用 cURL 7.75.0 版或更新版本 (Mac 和 Linux) 下載** 如果您有 cURL 7.75.0 版或更新版本，您可以使用 `aws-sigv4`旗標簽署 API 請求。此範例使用 [jq](https://stedolan.github.io/jq/) 從回應剖析下載 URL。 `aws-sigv4` 旗標需要 curl GET 請求的查詢參數依 **HostOs/ProductVersion/TestSuiteType**或 的順序排列**HostOs/TestSuiteType**。不符合的順序會導致從 API Gateway 取得正式字串不相符簽章時發生錯誤。 如果**ProductVersion**包含選用參數，您必須使用支援的產品版本，如 [AWS IoT Device Tester for AWS IoT Greengrass V2 的支援版本](dev-test-versions.md)所述。 + 將 *us-west-2* 取代為您的 AWS 區域。如需區域代碼清單，請參閱[區域端點](https://docs.aws.amazon.com/general/latest/gr/rande.html)。 + 將 *linux* 取代為主機機器的作業系統。 + 將 *2.5.3 取代*為您的 核版本 AWS IoT Greengrass 。 ``` url=$(curl --request GET "https://download.devicetester.iotdevicesecosystem.amazonaws.com/latestidt?HostOs=linux&ProductVersion=2.5.3&TestSuiteType=GGV2" \ --user $AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY \ --aws-sigv4 "aws:amz:us-west-2:iot-device-tester" \ | jq -r '.LatestBk["DownloadURL"]') curl $url --output devicetester.zip ``` **Example 範例：使用舊版 cURL (Mac 和 Linux) 下載** 您可以使用下列 cURL 命令搭配您簽署和計算的 AWS 簽章。如需如何簽署和計算 AWS 簽章的詳細資訊，請參閱[簽署 AWS API 請求](https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html)。 + 將 *linux* 取代為主機機器的作業系統。 + 將*時間戳記*取代為日期和時間，例如 **20220210T004606Z**。 + 將*日期*取代為日期，例如 **20220210**。 + 將 *AWSRegion* 取代為 AWS 區域。如需區域代碼清單，請參閱[區域端點](https://docs.aws.amazon.com/general/latest/gr/rande.html)。 + 將 *AWSSignature* 取代為您產生的[AWS 簽章](https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html)。 ``` curl --location --request GET 'https://download.devicetester.iotdevicesecosystem.amazonaws.com/latestidt?HostOs=linux&TestSuiteType=GGV2' \ --header 'X-Amz-Date: Timestamp \ --header 'Authorization: AWS4-HMAC-SHA256 Credential=$AWS_ACCESS_KEY_ID/Date/AWSRegion/iot-device-tester/aws4_request, SignedHeaders=host;x-amz-date, Signature=AWSSignature' ``` **Example 範例：使用 Python 指令碼下載** 此範例使用 Python [請求](https://pypi.org/project/requests/)程式庫。此範例改編自 Python 範例，以在 *AWS 一般參考*中[簽署 AWS API 請求](https://docs.aws.amazon.com/general/latest/gr/sigv4-signed-request-examples.html)。 + 將 *us-west-2* 取代為您的區域。如需區域代碼清單，請參閱[區域端點](https://docs.aws.amazon.com/general/latest/gr/rande.html)。 + 將 *linux* 取代為主機機器的作業系統。 ``` # Copyright 2010-2022 Amazon.com, Inc. or its affiliates. All Rights Reserved. # # This file is licensed under the Apache License, Version 2.0 (the "License"). # You may not use this file except in compliance with the License. A copy of the #License is located at # # http://aws.amazon.com/apache2.0/ # # This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS # OF ANY KIND, either express or implied. See the License for the specific # language governing permissions and limitations under the License. # See: http://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html # This version makes a GET request and passes the signature # in the Authorization header. import sys, os, base64, datetime, hashlib, hmac import requests # pip install requests # ************* REQUEST VALUES ************* method = 'GET' service = 'iot-device-tester' host = 'download.devicetester.iotdevicesecosystem.amazonaws.com' region = 'us-west-2' endpoint = 'https://download.devicetester.iotdevicesecosystem.amazonaws.com/latestidt' request_parameters = 'HostOs=linux&TestSuiteType=GGV2' # Key derivation functions. See: # http://docs.aws.amazon.com/general/latest/gr/signature-v4-examples.html#signature-v4-examples-python def sign(key, msg): return hmac.new(key, msg.encode('utf-8'), hashlib.sha256).digest() def getSignatureKey(key, dateStamp, regionName, serviceName): kDate = sign(('AWS4' + key).encode('utf-8'), dateStamp) kRegion = sign(kDate, regionName) kService = sign(kRegion, serviceName) kSigning = sign(kService, 'aws4_request') return kSigning # Read AWS access key from env. variables or configuration file. Best practice is NOT # to embed credentials in code. access_key = os.environ.get('AWS_ACCESS_KEY_ID') secret_key = os.environ.get('AWS_SECRET_ACCESS_KEY') if access_key is None or secret_key is None: print('No access key is available.') sys.exit() # Create a date for headers and the credential string t = datetime.datetime.utcnow() amzdate = t.strftime('%Y%m%dT%H%M%SZ') datestamp = t.strftime('%Y%m%d') # Date w/o time, used in credential scope # ************* TASK 1: CREATE A CANONICAL REQUEST ************* # http://docs.aws.amazon.com/general/latest/gr/sigv4-create-canonical-request.html # Step 1 is to define the verb (GET, POST, etc.)--already done. # Step 2: Create canonical URI--the part of the URI from domain to query # string (use '/' if no path) canonical_uri = '/latestidt' # Step 3: Create the canonical query string. In this example (a GET request), # request parameters are in the query string. Query string values must # be URL-encoded (space=%20). The parameters must be sorted by name. # For this example, the query string is pre-formatted in the request_parameters variable. canonical_querystring = request_parameters # Step 4: Create the canonical headers and signed headers. Header names # must be trimmed and lowercase, and sorted in code point order from # low to high. Note that there is a trailing \n. canonical_headers = 'host:' + host + '\n' + 'x-amz-date:' + amzdate + '\n' # Step 5: Create the list of signed headers. This lists the headers # in the canonical_headers list, delimited with ";" and in alpha order. # Note: The request can include any headers; canonical_headers and # signed_headers lists those that you want to be included in the # hash of the request. "Host" and "x-amz-date" are always required. signed_headers = 'host;x-amz-date' # Step 6: Create payload hash (hash of the request body content). For GET # requests, the payload is an empty string (""). payload_hash = hashlib.sha256(('').encode('utf-8')).hexdigest() # Step 7: Combine elements to create canonical request canonical_request = method + '\n' + canonical_uri + '\n' + canonical_querystring + '\n' + canonical_headers + '\n' + signed_headers + '\n' + payload_hash # ************* TASK 2: CREATE THE STRING TO SIGN************* # Match the algorithm to the hashing algorithm you use, either SHA-1 or # SHA-256 (recommended) algorithm = 'AWS4-HMAC-SHA256' credential_scope = datestamp + '/' + region + '/' + service + '/' + 'aws4_request' string_to_sign = algorithm + '\n' + amzdate + '\n' + credential_scope + '\n' + hashlib.sha256(canonical_request.encode('utf-8')).hexdigest() # ************* TASK 3: CALCULATE THE SIGNATURE ************* # Create the signing key using the function defined above. signing_key = getSignatureKey(secret_key, datestamp, region, service) # Sign the string_to_sign using the signing_key signature = hmac.new(signing_key, (string_to_sign).encode('utf-8'), hashlib.sha256).hexdigest() # ************* TASK 4: ADD SIGNING INFORMATION TO THE REQUEST ************* # The signing information can be either in a query string value or in # a header named Authorization. This code shows how to use a header. # Create authorization header and add to request headers authorization_header = algorithm + ' ' + 'Credential=' + access_key + '/' + credential_scope + ', ' + 'SignedHeaders=' + signed_headers + ', ' + 'Signature=' + signature # The request can include any headers, but MUST include "host", "x-amz-date", # and (for this scenario) "Authorization". "host" and "x-amz-date" must # be included in the canonical_headers and signed_headers, as noted # earlier. Order here is not significant. # Python note: The 'host' header is added automatically by the Python 'requests' library. headers = {'x-amz-date':amzdate, 'Authorization':authorization_header} # ************* SEND THE REQUEST ************* request_url = endpoint + '?' + canonical_querystring print('\nBEGIN REQUEST++++++++++++++++++++++++++++++++++++') print('Request URL = ' + request_url) response = requests.get(request_url, headers=headers) print('\nRESPONSE++++++++++++++++++++++++++++++++++++') print('Response code: %d\n' % response.status_code) print(response.text) download_url = response.json()["LatestBk"]["DownloadURL"] r = requests.get(download_url) open('devicetester.zip', 'wb').write(r.content) ``` # 使用 IDT AWS IoT Greengrass 執行資格套件 您可以使用 AWS IoT Device Tester for AWS IoT Greengrass V2 驗證 AWS IoT Greengrass Core 軟體是否在您的硬體上執行，並且可以與 通訊 AWS 雲端。它也會使用 end-to-end測試 AWS IoT Core。例如，它會驗證您的裝置是否可以部署元件並進行升級。 除了測試裝置之外，IDT for AWS IoT Greengrass V2 還會在您的 中建立資源 （例如 AWS IoT 物件、群組等） AWS 帳戶 ，以促進資格程序。 為了建立這些資源，IDT for AWS IoT Greengrass V2 會使用`config.json`檔案中設定的 AWS 登入資料，代表您進行 API 呼叫。系統會在測試期間的不同時間點內佈建這些資源。 當您使用 IDT for AWS IoT Greengrass V2 AWS IoT Greengrass 執行資格套件時，它會執行下列步驟： 1. 載入並驗證您的裝置和登入資料組態。 1. 對所需的本機和雲端資源執行選取的測試。 1. 清除本機和雲端資源。 1. 產生測試報告以指出主機板是否通過符合資格所需的測試。 ## 測試套件版本 IDT for AWS IoT Greengrass V2 會將測試組織成測試套件和測試群組。 + 測試套件是一組測試群組，用來驗證裝置是否適用於特定版本的 AWS IoT Greengrass。 + 測試群組是一組與特定功能相關的個別測試，例如元件部署。 測試套件使用 `major.minor.patch` 格式進行版本控制，例如 `GGV2Q_1.0.0`。當您下載 IDT 時，套件包含最新的 Greengrass 資格套件版本。 **重要** 來自不支援的測試套件版本的測試不符合裝置資格。IDT 不會列印不支援版本的資格報告。如需詳細資訊，請參閱[適用於 AWS IoT Device Tester 的支援政策 AWS IoT Greengrass](idt-support-policy.md)。 您可以執行 `list-supported-products`來列出目前 IDT 版本支援的 AWS IoT Greengrass 和 測試套件版本。 ## 測試群組描述 **核心資格的必要測試群組** 需要這些測試群組，才能讓您的 AWS IoT Greengrass V2 裝置符合 AWS Partner Device Catalog 的資格。 核心相依性 驗證裝置是否符合 AWS IoT Greengrass Core 軟體的所有軟體和硬體需求。此測試群組包含下列測試案例： Java 版本 檢查測試下的裝置上是否安裝了所需的 Java 版本。 AWS IoT Greengrass 需要 Java 8 或更新版本。 PreTest驗證 檢查裝置是否符合執行測試的軟體需求。 + 對於以 Linux 為基礎的裝置，此測試會檢查裝置是否可以執行下列 Linux 命令： `chmod`, `cp`, `echo`, `grep`, `kill`, `ln`, `mkinfo`, `ps`, `rm`, `sh`, `uname` + 對於 Windows 型裝置，此測試會檢查裝置是否已安裝下列 Microsoft 軟體： [Powershell](https://learn.microsoft.com/en-us/powershell/?view=powershell-7.1) v5.1 或更新版本、[.NET](https://learn.microsoft.com/en-us/dotnet/) v4.6.1 或更新版本、[Visual C\$1\$1](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170) 2017 或更新版本、[PsExec 公用程式](https://learn.microsoft.com/en-us/sysinternals/downloads/psexec) 版本檢查程式 檢查 AWS IoT Greengrass 提供的 版本是否與您正在使用的 AWS IoT Device Tester 版本相容。 元件 驗證裝置是否可以部署元件並進行升級。此測試群組包含下列測試： 雲端元件 驗證雲端元件的裝置功能。 本機元件 驗證本機元件的裝置功能。 Lambda 此測試不適用於 Windows 型裝置。 驗證裝置是否可以部署使用 Java 執行時間的 Lambda 函數元件，以及 Lambda 函數可以使用 AWS IoT Core MQTT 主題做為工作訊息的事件來源。 MQTT 驗證裝置是否可以訂閱和發佈至 AWS IoT Core MQTT 主題。 **選用測試群組** 這些測試群組是選用的，僅用於合格的 Linux Greengrass 核心裝置。如果您選擇符合選用測試的資格，您的裝置會在 AWS Partner Device Catalog 中列出其他功能。 Docker 相依性 驗證裝置是否符合所有必要的技術相依性，以使用 AWS提供的 Docker 應用程式管理員 (`aws.greengrass.DockerApplicationManager`) 元件。 Docker Application Manager 資格 驗證裝置可以從 Amazon ECR 下載 Docker 容器映像。 Machine Learning相依性 只有 IDT v4.9.3 支援機器學習選用測試群組。 驗證裝置是否符合使用 AWS提供的機器學習 (ML) 元件所需的所有必要技術相依性。 Machine Learning推論測試 只有 IDT v4.9.3 支援機器學習選用測試群組。 驗證裝置是否可以使用[深度學習執行期](https://github.com/neo-ai/neo-ai-dlr)和 [TensorFlow Lite](https://www.tensorflow.org/lite/guide/python) ML 架構執行 ML 推論。 串流管理員相依性 僅在 IDT v4.9.3 中支援串流管理員選用測試群組。 驗證裝置是否可以下載、安裝和執行[AWS IoT Greengrass 串流管理員](manage-data-streams.md)。 硬體安全整合 (HSI) 此測試僅適用於 Linux 型裝置的 IDT v4.9.3 和更新版本。目前 AWS IoT Greengrass 不支援 Windows 裝置的硬體安全整合。 驗證裝置是否可以使用存放在硬體安全模組 (HSM) 中的私有金鑰和憑證來驗證 AWS IoT 和 AWS IoT Greengrass 服務的連線。此測試也會驗證 AWS提供的 [PKCS\$111 供應商元件](pkcs11-provider-component.md)是否可以使用廠商提供的 PKCS\$111 程式庫與 HSM 連接。如需詳細資訊，請參閱[硬體安全整合](hardware-security.md)。 # 執行 AWS IoT Greengrass 資格套件的先決條件 本節說明使用 AWS IoT Device Tester (IDT) 的先決條件 AWS IoT Greengrass。 ## 下載 AWS IoT Device Tester 適用於 的最新版本 AWS IoT Greengrass 下載[最新版本](idt-programmatic-download.md)的 IDT，並將軟體解壓縮到檔案系統上具有讀取/寫入許可的位置 (**)。 **注意** IDT 不支援由多位使用者從共用位置執行，例如 NFS 目錄或 Windows 網路共用資料夾。我們建議您將 IDT 套件解壓縮到本機磁碟機，並在本機工作站上執行 IDT 二進位檔。 Windows 的路徑長度限制為 260 個字元。如果您使用的是 Windows，請將 IDT 解壓縮到根目錄，例如 `C:\ ` 或 `D:\`，使路徑保持在 260 個字元的限制以下。 ## 下載 AWS IoT Greengrass 軟體 IDT for AWS IoT Greengrass V2 會測試您的裝置與特定 版本的相容性 AWS IoT Greengrass。執行下列命令，將 AWS IoT Greengrass Core 軟體下載至名為 的檔案`aws.greengrass.nucleus.zip`。將 *版本*取代為 IDT [版本的支援核元件](dev-test-versions.md)版本。 ------ #### [ Linux or Unix ] ``` curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-version.zip > aws.greengrass.nucleus.zip ``` ------ #### [ Windows Command Prompt (CMD) ] ``` curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-version.zip > aws.greengrass.nucleus.zip ``` ------ #### [ PowerShell ] ``` iwr -Uri https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-version.zip -OutFile aws.greengrass.nucleus.zip ``` ------ 將下載`aws.greengrass.nucleus.zip`的檔案放在 `/products/` 資料夾中。 **注意** 請勿將相同作業系統和架構的多個檔案放在這個目錄中。 ## 建立和設定 AWS 帳戶 您必須先執行下列步驟，才能使用 AWS IoT Device Tester for AWS IoT Greengrass V2： 1. [設定 AWS 帳戶。](#create-aws-account-for-idt)如果您已有 AWS 帳戶，請跳到步驟 2。 1. [設定 IDT 的許可。](#configure-idt-permissions) 這些帳戶許可允許 IDT 代表您存取 AWS 服務和建立 AWS 資源，例如 AWS IoT 物件和 AWS IoT Greengrass 元件。 為了建立這些資源，IDT for AWS IoT Greengrass V2 會使用`config.json`檔案中設定的 AWS 登入資料，代表您進行 API 呼叫。系統會在測試期間的不同時間點內佈建這些資源。 **注意** 雖然大多數測試都符合 [AWS 免費方案](https://aws.amazon.com/free)的資格，但您必須在註冊 時提供信用卡 AWS 帳戶。如需詳細資訊，請參閱[如果我的帳戶適用於免費方案，為何需要付款方式？](https://aws.amazon.com/premiumsupport/knowledge-center/free-tier-payment-method/)。 ### 步驟 1：設定 AWS 帳戶 在此步驟中，建立和設定 AWS 帳戶。如果您已擁有 AWS 帳戶，請跳到 [步驟 2：設定 IDT 的許可](#configure-idt-permissions)。 如果您沒有 AWS 帳戶，請完成下列步驟來建立一個。 **註冊 AWS 帳戶** 1. 開啟 [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup)。 1. 請遵循線上指示進行。 部分註冊程序需接收來電或簡訊，並在電話鍵盤輸入驗證碼。 當您註冊 時 AWS 帳戶，*AWS 帳戶根使用者*會建立 。根使用者有權存取該帳戶中的所有 AWS 服務 和資源。作為安全最佳實務，請將管理存取權指派給使用者，並且僅使用根使用者來執行[需要根使用者存取權的任務](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks)。 若要建立管理員使用者，請選擇下列其中一個選項。 **** | 選擇一種管理管理員的方式 | 到 | 根據 | 您也可以 | | --- | --- | --- | --- | | 在 IAM Identity Center (建議) | 使用短期憑證存取 AWS。這與安全性最佳實務一致。有關最佳實務的資訊，請參閱 *IAM 使用者指南*中的 [IAM 安全最佳實務](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-users-federation-idp)。 | 請遵循 AWS IAM Identity Center 使用者指南的[入門](https://docs.aws.amazon.com//singlesignon/latest/userguide/getting-started.html)中的說明。 | 在 AWS Command Line Interface 使用者指南中設定 [AWS CLI 以使用 來設定 AWS IAM Identity Center](https://docs.aws.amazon.com//cli/latest/userguide/cli-configure-sso.html)程式設計存取。 | | 在 IAM 中 (不建議使用) | 使用長期憑證存取 AWS。 | 請遵循《IAM 使用者指南》中[建立 IAM 使用者以進行緊急存取](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started-emergency-iam-user.html) 的指示。 | 請依照《IAM 使用者指南》中的[管理 IAM 使用者的存取金鑰](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_credentials_access-keys.html)設定以程式設計方式存取。 | ### 步驟 2：設定 IDT 的許可 在此步驟中，設定 IDT for AWS IoT Greengrass V2 用來執行測試和收集 IDT 用量資料的許可。您可以使用 [AWS 管理主控台](#configure-idt-permissions-console)或 [AWS Command Line Interface (AWS CLI)](#configure-idt-permissions-cli) 來建立 IAM 政策和 IDT 的測試使用者，然後將政策連接到使用者。如果您已為 IDT 建立測試使用者，請跳至 [設定您的裝置以執行 IDT 測試](device-config-setup.md)。 #### 設定 IDT (主控台) 的許可 1. 登入 [IAM 主控台](https://console.aws.amazon.com/iam)。 1. 建立客戶受管政策，該政策授與建立具有特定許可之角色的許可。 1. 在導覽窗格中，選擇**政策**，然後選擇**建立政策**。 1. 如果您不是使用 PreInstalled，請在 **JSON** 索引標籤上，將預留位置內容取代為下列政策。如果您使用的是 PreInstalled，請繼續下列步驟。 ``` { "Version":"2012-10-17", "Statement":[ { "Sid":"passRoleForResources", "Effect":"Allow", "Action":"iam:PassRole", "Resource":"arn:aws:iam::*:role/idt-*", "Condition":{ "StringEquals":{ "iam:PassedToService":[ "iot.amazonaws.com", "lambda.amazonaws.com", "greengrass.amazonaws.com" ] } } }, { "Sid":"lambdaResources", "Effect":"Allow", "Action":[ "lambda:CreateFunction", "lambda:PublishVersion", "lambda:DeleteFunction", "lambda:GetFunction" ], "Resource":[ "arn:aws:lambda:*:*:function:idt-*" ] }, { "Sid":"iotResources", "Effect":"Allow", "Action":[ "iot:CreateThing", "iot:DeleteThing", "iot:DescribeThing", "iot:CreateThingGroup", "iot:DeleteThingGroup", "iot:DescribeThingGroup", "iot:AddThingToThingGroup", "iot:RemoveThingFromThingGroup", "iot:AttachThingPrincipal", "iot:DetachThingPrincipal", "iot:UpdateCertificate", "iot:DeleteCertificate", "iot:CreatePolicy", "iot:AttachPolicy", "iot:DetachPolicy", "iot:DeletePolicy", "iot:GetPolicy", "iot:Publish", "iot:TagResource", "iot:ListThingPrincipals", "iot:ListAttachedPolicies", "iot:ListTargetsForPolicy", "iot:ListThingGroupsForThing", "iot:ListThingsInThingGroup", "iot:CreateJob", "iot:DescribeJob", "iot:DescribeJobExecution", "iot:CancelJob" ], "Resource":[ "arn:aws:iot:*:*:thing/idt-*", "arn:aws:iot:*:*:thinggroup/idt-*", "arn:aws:iot:*:*:policy/idt-*", "arn:aws:iot:*:*:cert/*", "arn:aws:iot:*:*:topic/idt-*", "arn:aws:iot:*:*:job/*" ] }, { "Sid":"s3Resources", "Effect":"Allow", "Action":[ "s3:GetObject", "s3:PutObject", "s3:DeleteObjectVersion", "s3:DeleteObject", "s3:CreateBucket", "s3:ListBucket", "s3:ListBucketVersions", "s3:DeleteBucket", "s3:PutObjectTagging", "s3:PutBucketTagging" ], "Resource":"arn:aws:s3::*:idt-*" }, { "Sid":"roleAliasResources", "Effect":"Allow", "Action":[ "iot:CreateRoleAlias", "iot:DescribeRoleAlias", "iot:DeleteRoleAlias", "iot:TagResource", "iam:GetRole" ], "Resource":[ "arn:aws:iot:*:*:rolealias/idt-*", "arn:aws:iam::*:role/idt-*" ] }, { "Sid":"idtExecuteAndCollectMetrics", "Effect":"Allow", "Action":[ "iot-device-tester:SendMetrics", "iot-device-tester:SupportedVersion", "iot-device-tester:LatestIdt", "iot-device-tester:CheckVersion", "iot-device-tester:DownloadTestSuite" ], "Resource":"*" }, { "Sid":"genericResources", "Effect":"Allow", "Action":[ "greengrass:*", "iot:GetThingShadow", "iot:UpdateThingShadow", "iot:ListThings", "iot:DescribeEndpoint", "iot:CreateKeysAndCertificate" ], "Resource":"*" }, { "Sid":"iamResourcesUpdate", "Effect":"Allow", "Action":[ "iam:CreateRole", "iam:DeleteRole", "iam:CreatePolicy", "iam:DeletePolicy", "iam:AttachRolePolicy", "iam:DetachRolePolicy", "iam:TagRole", "iam:TagPolicy", "iam:GetPolicy", "iam:ListAttachedRolePolicies", "iam:ListEntitiesForPolicy" ], "Resource":[ "arn:aws:iam::*:role/idt-*", "arn:aws:iam::*:policy/idt-*" ] } ] } ``` 1. 如果您使用的是 PreInstalled，請在 **JSON** 標籤上，將預留位置內容取代為下列政策。請確定您： + 將 `iotResources`陳述式中的 *thingName* 和 *thingGroup* 取代為測試裝置 (DUT) 上 Greengrass 安裝期間建立的物件名稱和物件群組，以新增許可。 + 將 `roleAliasResources` 陳述式和 `passRoleForResources`陳述式中的 *passRole* 和 *roleAlias* 取代為 DUT 上 Greengrass 安裝期間建立的角色。 ``` { "Version":"2012-10-17", "Statement":[ { "Sid":"passRoleForResources", "Effect":"Allow", "Action":"iam:PassRole", "Resource":"arn:aws:iam::*:role/passRole", "Condition":{ "StringEquals":{ "iam:PassedToService":[ "iot.amazonaws.com", "lambda.amazonaws.com", "greengrass.amazonaws.com" ] } } }, { "Sid":"lambdaResources", "Effect":"Allow", "Action":[ "lambda:CreateFunction", "lambda:PublishVersion", "lambda:DeleteFunction", "lambda:GetFunction" ], "Resource":[ "arn:aws:lambda:*:*:function:idt-*" ] }, { "Sid":"iotResources", "Effect":"Allow", "Action":[ "iot:CreateThing", "iot:DeleteThing", "iot:DescribeThing", "iot:CreateThingGroup", "iot:DeleteThingGroup", "iot:DescribeThingGroup", "iot:AddThingToThingGroup", "iot:RemoveThingFromThingGroup", "iot:AttachThingPrincipal", "iot:DetachThingPrincipal", "iot:UpdateCertificate", "iot:DeleteCertificate", "iot:CreatePolicy", "iot:AttachPolicy", "iot:DetachPolicy", "iot:DeletePolicy", "iot:GetPolicy", "iot:Publish", "iot:TagResource", "iot:ListThingPrincipals", "iot:ListAttachedPolicies", "iot:ListTargetsForPolicy", "iot:ListThingGroupsForThing", "iot:ListThingsInThingGroup", "iot:CreateJob", "iot:DescribeJob", "iot:DescribeJobExecution", "iot:CancelJob" ], "Resource":[ "arn:aws:iot:*:*:thing/thingName", "arn:aws:iot:*:*:thinggroup/thingGroup", "arn:aws:iot:*:*:policy/idt-*", "arn:aws:iot:*:*:cert/*", "arn:aws:iot:*:*:topic/idt-*", "arn:aws:iot:*:*:job/*" ] }, { "Sid":"s3Resources", "Effect":"Allow", "Action":[ "s3:GetObject", "s3:PutObject", "s3:DeleteObjectVersion", "s3:DeleteObject", "s3:CreateBucket", "s3:ListBucket", "s3:ListBucketVersions", "s3:DeleteBucket", "s3:PutObjectTagging", "s3:PutBucketTagging" ], "Resource":"arn:aws:s3::*:idt-*" }, { "Sid":"roleAliasResources", "Effect":"Allow", "Action":[ "iot:CreateRoleAlias", "iot:DescribeRoleAlias", "iot:DeleteRoleAlias", "iot:TagResource", "iam:GetRole" ], "Resource":[ "arn:aws:iot:*:*:rolealias/roleAlias", "arn:aws:iam::*:role/idt-*" ] }, { "Sid":"idtExecuteAndCollectMetrics", "Effect":"Allow", "Action":[ "iot-device-tester:SendMetrics", "iot-device-tester:SupportedVersion", "iot-device-tester:LatestIdt", "iot-device-tester:CheckVersion", "iot-device-tester:DownloadTestSuite" ], "Resource":"*" }, { "Sid":"genericResources", "Effect":"Allow", "Action":[ "greengrass:*", "iot:GetThingShadow", "iot:UpdateThingShadow", "iot:ListThings", "iot:DescribeEndpoint", "iot:CreateKeysAndCertificate" ], "Resource":"*" }, { "Sid":"iamResourcesUpdate", "Effect":"Allow", "Action":[ "iam:CreateRole", "iam:DeleteRole", "iam:CreatePolicy", "iam:DeletePolicy", "iam:AttachRolePolicy", "iam:DetachRolePolicy", "iam:TagRole", "iam:TagPolicy", "iam:GetPolicy", "iam:ListAttachedRolePolicies", "iam:ListEntitiesForPolicy" ], "Resource":[ "arn:aws:iam::*:role/idt-*", "arn:aws:iam::*:policy/idt-*" ] } ] } ``` **注意** 如果您想要使用[自訂 IAM 角色做為待測裝置的字符交換角色](set-config.md#custom-token-exchange-role-idt)，請務必更新政策中的 `roleAliasResources` 陳述式和 `passRoleForResources`陳述式，以允許自訂 IAM 角色資源。 1. 選擇**檢閱政策**。 1. 對於**名稱**，輸入 **IDTGreengrassIAMPermissions**。在 **Summary (摘要)** 下，檢閱您的政策所授與的許可。 1. 選擇**建立政策**。 1. 建立 IAM 使用者並連接 IDT for 所需的許可 AWS IoT Greengrass。 1. 建立 IAM 使用者。請遵循《IAM *使用者指南*》中[建立 IAM 使用者 （主控台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console) 的步驟 1 到 5。 1. 將許可連接至您的 IAM 使用者： 1. 在 **Set permissions (設定許可)** 頁面上，選擇 **Attach existing policies directly (直接連接現有的政策)**。 1. 搜尋您在上一個步驟中建立的 **IDTGreengrassIAMPermissions** 政策。選取核取方塊。 1. 選擇下**一步：標籤**。 1. 選擇 **Next: Review (下一步：檢閱)** 以檢視選擇的摘要。 1. 選擇 **Create user** (建立使用者)。 1. 若要檢視使用者的存取金鑰 (存取金鑰 ID 和私密存取金鑰)，請選擇密碼和存取金鑰旁的 **Show (顯示)**。若要儲存存取金鑰，請選擇 **Download.csv**，並將檔案儲存到安全的位置。您稍後會使用此資訊來設定您的 AWS 登入資料檔案。 1. 下一步：設定您的[實體裝置](device-config-setup.md)。 #### 步驟 2：設定 IDT (AWS CLI) 的許可 1. 如果尚未安裝 ，請在電腦上安裝和設定 AWS CLI 。請遵循*AWS Command Line Interface 《 使用者指南*》中的[安裝 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) 中的步驟。 **注意** AWS CLI 是開放原始碼工具，可用來與 AWS 命令列 Shell 中的 服務互動。 1. 建立客戶受管政策，以授予管理 IDT 和 AWS IoT Greengrass 角色的許可。 1. 如果您不是使用 PreInstalled，請開啟文字編輯器，並將下列政策內容儲存在 JSON 檔案中。如果您使用的是 PreInstalled，請繼續下列步驟。 ``` { "Version":"2012-10-17", "Statement":[ { "Sid":"passRoleForResources", "Effect":"Allow", "Action":"iam:PassRole", "Resource":"arn:aws:iam::*:role/idt-*", "Condition":{ "StringEquals":{ "iam:PassedToService":[ "iot.amazonaws.com", "lambda.amazonaws.com", "greengrass.amazonaws.com" ] } } }, { "Sid":"lambdaResources", "Effect":"Allow", "Action":[ "lambda:CreateFunction", "lambda:PublishVersion", "lambda:DeleteFunction", "lambda:GetFunction" ], "Resource":[ "arn:aws:lambda:*:*:function:idt-*" ] }, { "Sid":"iotResources", "Effect":"Allow", "Action":[ "iot:CreateThing", "iot:DeleteThing", "iot:DescribeThing", "iot:CreateThingGroup", "iot:DeleteThingGroup", "iot:DescribeThingGroup", "iot:AddThingToThingGroup", "iot:RemoveThingFromThingGroup", "iot:AttachThingPrincipal", "iot:DetachThingPrincipal", "iot:UpdateCertificate", "iot:DeleteCertificate", "iot:CreatePolicy", "iot:AttachPolicy", "iot:DetachPolicy", "iot:DeletePolicy", "iot:GetPolicy", "iot:Publish", "iot:TagResource", "iot:ListThingPrincipals", "iot:ListAttachedPolicies", "iot:ListTargetsForPolicy", "iot:ListThingGroupsForThing", "iot:ListThingsInThingGroup", "iot:CreateJob", "iot:DescribeJob", "iot:DescribeJobExecution", "iot:CancelJob" ], "Resource":[ "arn:aws:iot:*:*:thing/idt-*", "arn:aws:iot:*:*:thinggroup/idt-*", "arn:aws:iot:*:*:policy/idt-*", "arn:aws:iot:*:*:cert/*", "arn:aws:iot:*:*:topic/idt-*", "arn:aws:iot:*:*:job/*" ] }, { "Sid":"s3Resources", "Effect":"Allow", "Action":[ "s3:GetObject", "s3:PutObject", "s3:DeleteObjectVersion", "s3:DeleteObject", "s3:CreateBucket", "s3:ListBucket", "s3:ListBucketVersions", "s3:DeleteBucket", "s3:PutObjectTagging", "s3:PutBucketTagging" ], "Resource":"arn:aws:s3::*:idt-*" }, { "Sid":"roleAliasResources", "Effect":"Allow", "Action":[ "iot:CreateRoleAlias", "iot:DescribeRoleAlias", "iot:DeleteRoleAlias", "iot:TagResource", "iam:GetRole" ], "Resource":[ "arn:aws:iot:*:*:rolealias/idt-*", "arn:aws:iam::*:role/idt-*" ] }, { "Sid":"idtExecuteAndCollectMetrics", "Effect":"Allow", "Action":[ "iot-device-tester:SendMetrics", "iot-device-tester:SupportedVersion", "iot-device-tester:LatestIdt", "iot-device-tester:CheckVersion", "iot-device-tester:DownloadTestSuite" ], "Resource":"*" }, { "Sid":"genericResources", "Effect":"Allow", "Action":[ "greengrass:*", "iot:GetThingShadow", "iot:UpdateThingShadow", "iot:ListThings", "iot:DescribeEndpoint", "iot:CreateKeysAndCertificate" ], "Resource":"*" }, { "Sid":"iamResourcesUpdate", "Effect":"Allow", "Action":[ "iam:CreateRole", "iam:DeleteRole", "iam:CreatePolicy", "iam:DeletePolicy", "iam:AttachRolePolicy", "iam:DetachRolePolicy", "iam:TagRole", "iam:TagPolicy", "iam:GetPolicy", "iam:ListAttachedRolePolicies", "iam:ListEntitiesForPolicy" ], "Resource":[ "arn:aws:iam::*:role/idt-*", "arn:aws:iam::*:policy/idt-*" ] } ] } ``` 1. 如果您使用的是 PreInstalled，請開啟文字編輯器，並將下列政策內容儲存在 JSON 檔案中。請確定您： + 在測試裝置 (DUT) 的 Greengrass 安裝期間建立的`iotResources`陳述式中取代 *thingName* 和 *thingGroup*，以新增許可。 + 將 `roleAliasResources` 陳述式和 `passRoleForResources`陳述式中的 *passRole* 和 *roleAlias* 取代為 DUT 上 Greengrass 安裝期間建立的角色。 ``` { "Version":"2012-10-17", "Statement":[ { "Sid":"passRoleForResources", "Effect":"Allow", "Action":"iam:PassRole", "Resource":"arn:aws:iam::*:role/passRole", "Condition":{ "StringEquals":{ "iam:PassedToService":[ "iot.amazonaws.com", "lambda.amazonaws.com", "greengrass.amazonaws.com" ] } } }, { "Sid":"lambdaResources", "Effect":"Allow", "Action":[ "lambda:CreateFunction", "lambda:PublishVersion", "lambda:DeleteFunction", "lambda:GetFunction" ], "Resource":[ "arn:aws:lambda:*:*:function:idt-*" ] }, { "Sid":"iotResources", "Effect":"Allow", "Action":[ "iot:CreateThing", "iot:DeleteThing", "iot:DescribeThing", "iot:CreateThingGroup", "iot:DeleteThingGroup", "iot:DescribeThingGroup", "iot:AddThingToThingGroup", "iot:RemoveThingFromThingGroup", "iot:AttachThingPrincipal", "iot:DetachThingPrincipal", "iot:UpdateCertificate", "iot:DeleteCertificate", "iot:CreatePolicy", "iot:AttachPolicy", "iot:DetachPolicy", "iot:DeletePolicy", "iot:GetPolicy", "iot:Publish", "iot:TagResource", "iot:ListThingPrincipals", "iot:ListAttachedPolicies", "iot:ListTargetsForPolicy", "iot:ListThingGroupsForThing", "iot:ListThingsInThingGroup", "iot:CreateJob", "iot:DescribeJob", "iot:DescribeJobExecution", "iot:CancelJob" ], "Resource":[ "arn:aws:iot:*:*:thing/thingName", "arn:aws:iot:*:*:thinggroup/thingGroup", "arn:aws:iot:*:*:policy/idt-*", "arn:aws:iot:*:*:cert/*", "arn:aws:iot:*:*:topic/idt-*", "arn:aws:iot:*:*:job/*" ] }, { "Sid":"s3Resources", "Effect":"Allow", "Action":[ "s3:GetObject", "s3:PutObject", "s3:DeleteObjectVersion", "s3:DeleteObject", "s3:CreateBucket", "s3:ListBucket", "s3:ListBucketVersions", "s3:DeleteBucket", "s3:PutObjectTagging", "s3:PutBucketTagging" ], "Resource":"arn:aws:s3::*:idt-*" }, { "Sid":"roleAliasResources", "Effect":"Allow", "Action":[ "iot:CreateRoleAlias", "iot:DescribeRoleAlias", "iot:DeleteRoleAlias", "iot:TagResource", "iam:GetRole" ], "Resource":[ "arn:aws:iot:*:*:rolealias/roleAlias", "arn:aws:iam::*:role/idt-*" ] }, { "Sid":"idtExecuteAndCollectMetrics", "Effect":"Allow", "Action":[ "iot-device-tester:SendMetrics", "iot-device-tester:SupportedVersion", "iot-device-tester:LatestIdt", "iot-device-tester:CheckVersion", "iot-device-tester:DownloadTestSuite" ], "Resource":"*" }, { "Sid":"genericResources", "Effect":"Allow", "Action":[ "greengrass:*", "iot:GetThingShadow", "iot:UpdateThingShadow", "iot:ListThings", "iot:DescribeEndpoint", "iot:CreateKeysAndCertificate" ], "Resource":"*" }, { "Sid":"iamResourcesUpdate", "Effect":"Allow", "Action":[ "iam:CreateRole", "iam:DeleteRole", "iam:CreatePolicy", "iam:DeletePolicy", "iam:AttachRolePolicy", "iam:DetachRolePolicy", "iam:TagRole", "iam:TagPolicy", "iam:GetPolicy", "iam:ListAttachedRolePolicies", "iam:ListEntitiesForPolicy" ], "Resource":[ "arn:aws:iam::*:role/idt-*", "arn:aws:iam::*:policy/idt-*" ] } ] } ``` **注意** 如果您想要使用[自訂 IAM 角色做為待測裝置的字符交換角色](set-config.md#custom-token-exchange-role-idt)，請務必更新政策中的 `roleAliasResources` 陳述式和 `passRoleForResources`陳述式，以允許自訂 IAM 角色資源。 1. 執行下列命令來建立名為 的客戶受管政策`IDTGreengrassIAMPermissions`。`policy.json` 以您在上一個步驟中建立的 JSON 檔案的完整路徑取代 。 ``` aws iam create-policy --policy-name IDTGreengrassIAMPermissions --policy-document file://policy.json ``` 1. 建立 IAM 使用者並連接 IDT for 所需的許可 AWS IoT Greengrass。 1. 建立 IAM 使用者。在此範例設定中，使用者命名為 `IDTGreengrassUser`。 ``` aws iam create-user --user-name IDTGreengrassUser ``` 1. 將您在步驟 2 中建立`IDTGreengrassIAMPermissions`的政策連接到您的 IAM 使用者。使用 的 ID 取代 命令中的 ** AWS 帳戶。 ``` aws iam attach-user-policy --user-name IDTGreengrassUser --policy-arn arn:aws:iam:::policy/IDTGreengrassIAMPermissions ``` 1. 為使用者建立私密存取金鑰。 ``` aws iam create-access-key --user-name IDTGreengrassUser ``` 將輸出儲存在安全的位置。您稍後會使用此資訊來設定您的 AWS 登入資料檔案。 1. 下一步：設定您的[實體裝置](device-config-setup.md)。 ### AWS IoT Device Tester 許可 下列政策說明 AWS IoT Device Tester 許可。 AWS IoT Device Tester 需要這些許可才能進行版本檢查和自動更新功能。 + `iot-device-tester:SupportedVersion` AWS IoT Device Tester 准許擷取支援的產品、測試套件和 IDT 版本清單。 + `iot-device-tester:LatestIdt` AWS IoT Device Tester 准許擷取可供下載的最新 IDT 版本。 + `iot-device-tester:CheckVersion` AWS IoT Device Tester 准許檢查 IDT、測試套件和產品的版本相容性。 + `iot-device-tester:DownloadTestSuite` AWS IoT Device Tester 准許下載測試套件更新。 AWS IoT Device Tester 也會針對選用指標報告使用下列許可： + `iot-device-tester:SendMetrics` 准許 AWS 收集有關 AWS IoT Device Tester 內部使用的指標。如果省略此許可，則不會收集這些指標。 # 設定您的裝置以執行 IDT 測試 若要讓 IDT 執行裝置資格測試，您必須設定主機電腦以存取您的裝置，並在裝置上設定使用者許可。 ## 在主機電腦上安裝 Java 從 IDT v4.2.0 開始， 的選用資格測試 AWS IoT Greengrass 需要執行 Java。 您可以使用 Java 第 8 版或更新版本。我們建議您使用 [Amazon Corretto](https://aws.amazon.com/corretto/) 或 [OpenJDK](https://openjdk.java.net/) 長期支援版本。第 8 版或更新版本為必要項目。 ## 設定主機電腦以存取待測裝置 IDT 是在您的主機電腦上執行，而且必須能夠使用 SSH 連線到您的裝置。有兩個選項允許 IDT 取得待測裝置的 SSH 存取權： 1. 依照此處的指示來建立 SSH 金鑰對，並授權您的金鑰可以登入待測裝置，無需指定密碼。 1. 提供 `device.json` 檔案中每個裝置的使用者名稱和密碼。如需詳細資訊，請參閱[設定 device.json](set-config.md#device-config)。 您可以使用任何 SSL 實作來建立 SSH 金鑰。以下指示展示如何使用 [SSH-KEYGEN](https://www.ssh.com/ssh/keygen/) 或 [ PuTTYgen](https://www.ssh.com/ssh/putty/windows/puttygen) (適用於 Windows)。如果您使用的是另一個 SSL 實作，請參閱該實作的文件。 IDT 使用 SSH 金鑰向待測裝置進行驗證。 **使用 SSH-KEYGEN 建立 SSH 金鑰** 1. 建立 SSH 金鑰。 您可以使用 Open SSH **ssh-keygen** 命令建立 SSH 金鑰對。如果您的主機電腦上已有 SSH 金鑰對，則最佳實務是特別為 IDT 建立 SSH 金鑰對。如此一來，在您完成測試之後，若沒有輸入密碼，主機電腦再也無法連接至您的裝置。它還可讓您限制只有需要遠端裝置的人，才能存取該裝置。 **注意** Windows 沒有安裝的 SSH 用戶端。如需在 Windows 上安裝 SSH 用戶端的詳細資訊，請參閱[下載 SSH 用戶端軟體](https://www.ssh.com/ssh/#sec-Download-client-software)。 **ssh-keygen** 命令會提示您提供金鑰對的存放名稱和路徑。根據預設，該金鑰對檔案會命名為 `id_rsa` (私有金鑰) 和 `id_rsa.pub` (公有金鑰)。在 macOS 和 Linux 上，這些檔案的預設位置是 `~/.ssh/`。在 Windows 上，預設位置為 `C:\Users\\.ssh`。 出現提示時，請輸入金鑰字詞來保護您的 SSH 金鑰。如需詳細資訊，請參閱[產生新的 SSH 金鑰](https://www.ssh.com/ssh/keygen/)。 1. 將授權的 SSH 金鑰新增至待測裝置。 IDT 必須使用您的 SSH 私有金鑰登入待測裝置。請從您的主機電腦使用 **ssh-copy-id** 命令，授權您的 SSH 私有金鑰登入待測裝置。此命令會將您的公有金鑰新增至待測裝置上的 `~/.ssh/authorized_keys` 檔案。例如： **\$1 ssh-copy-id **@**** *remote-ssh-user* 是用來登入測試裝置的使用者名稱，而 *remote-device-ip* 是要執行測試的測試裝置 IP 地址。例如： **ssh-copy-id pi@192.168.1.5** 出現提示時，請輸入您在 **ssh-copy-id** 命令中指定的使用者名稱密碼。 **ssh-copy-id** 假設公有金鑰名為 `id_rsa.pub`，並存放在預設位置 (macOS 和 Linux 為 `~/.ssh/`，Windows 為 `C:\Users\\.ssh`)。如果您給公有金鑰不同的名稱，或將其存放在不同的位置中，則必須在 **ssh-copy-id** 中使用 **-i** 選項，以指定 SSH 公有金鑰的完整路徑 (例如，**ssh-copy-id -i \$1/my/path/myKey.pub**)。如需有關建立 SSH 金鑰和複製公有金鑰的詳細資訊，請參閱 [SSH-COPY-ID](https://www.ssh.com/ssh/copy-id)。 **使用 PuTTYgen 建立 SSH 金鑰 (僅限 Windows)** 1. 確定您的待測裝置上已安裝 OpenSSH 伺服器和用戶端。如需詳細資訊，請參閱 [OpenSSH](https://www.openssh.com/)。 1. 在您的待測裝置上安裝 [PuTTYgen](https://www.puttygen.com/)。 1. 開啟 PuTTYgen。 1. 選擇 **Generate (產生)**，並將滑鼠游標移到方塊內以產生私有金鑰。 1. 從 **Conversions (轉換)** 功能表中，選擇 **Export OpenSSH key (匯出 OpenSSH 金鑰)**，然後以 `.pem` 副檔名儲存私有金鑰。 1. 將公有金鑰新增至待測裝置上的 `/home//.ssh/authorized_keys` 檔案。 1. 從 PuTTYgen 視窗複製公有金鑰文字。 1. 使用 PuTTY 在您的待測裝置上建立工作階段。 1. 從命令提示字元或 Windows Powershell 視窗中，執行下列命令： **C:/**/putty.exe -ssh **@** ** 1. 出現提示時，請輸入您裝置的密碼。 1. 使用 vi 或其他文字編輯器，將公有金鑰附加到待測裝置上的 `/home//.ssh/authorized_keys` 檔案。 1. 使用您的使用者名稱、IP 地址，以及私有金鑰檔案的路徑 (您剛針對待測裝置將該檔案儲存在主機電腦上) 來更新 `device.json` 檔案。如需詳細資訊，請參閱[設定 device.json](set-config.md#device-config)。請務必提供私有金鑰的完整路徑和檔案名稱，並使用正斜線 ('/')。例如，若為 Windows 路徑 `C:\DT\privatekey.pem`，請在 `device.json` 檔案中使用 `C:/DT/privatekey.pem`。 ## 設定 Windows 裝置的使用者登入資料 若要符合 Windows 型裝置的資格，您必須在測試裝置上的 LocalSystem 帳戶中為下列使用者設定使用者憑證： + 預設 Greengrass 使用者 (`ggc_user`)。 + 您用來連線至待測裝置的使用者。您可以在 [`device.json` 檔案中](set-config.md#device-config)設定此使用者。 您必須在待測裝置的 LocalSystem 帳戶中建立每個使用者，然後將使用者的使用者名稱和密碼存放在 LocalSystem 帳戶的 Credential Manager 執行個體中。 **在 Windows 裝置上設定使用者** 1. 以管理員身分開啟 Windows 命令提示字元 (`cmd.exe`)。 1. 在 Windows 裝置的 LocalSystem 帳戶中建立使用者。針對您要建立的每個使用者執行下列命令。對於預設 Greengrass 使用者，請以 取代 *user-name*`ggc_user`。將*密碼*取代為安全密碼。 ``` net user /add user-name password ``` 1. 從 Microsoft 在裝置上下載並安裝 [PsExec 公用程式](https://docs.microsoft.com/en-us/sysinternals/downloads/psexec)。 1. 使用 PsExec 公用程式，將預設使用者的使用者名稱和密碼存放在 LocalSystem 帳戶的 Credential Manager 執行個體中。 針對您要在 Credential Manager 中設定的每個使用者執行下列命令。對於預設 Greengrass 使用者，請以 取代 *user-name*`ggc_user`。將*密碼*取代為您先前設定的使用者密碼。 ``` psexec -s cmd /c cmdkey /generic:user-name /user:user-name /pass:password ``` 如果 **PsExec License Agreement** 開啟，請選擇 以**Accept**同意授權並執行 命令。 **注意** 在 Windows 裝置上，LocalSystem 帳戶會執行 Greengrass 核，而且您必須使用 PsExec 公用程式將使用者資訊存放在 LocalSystem 帳戶中。使用 Credential Manager 應用程式會將此資訊存放在目前登入使用者的 Windows 帳戶中，而不是 LocalSystem 帳戶。 ## 在您的裝置上設定使用者許可 IDT 會在待測裝置的各種目錄和檔案上執行操作。其中某些操作需要較高的許可 (使用 **sudo**)。若要自動化這些操作，IDT for AWS IoT Greengrass V2 必須能夠使用 sudo 執行命令，而不會提示您輸入密碼。 在待測裝置上依照以下步驟，在不提示輸入密碼的情況下允許 sudo 存取。 **注意** `username` 是指 IDT 存取待測裝置時所使用的 SSH 使用者。 **將使用者新增至 sudo 群組** 1. 在待測裝置上，執行 `sudo usermod -aG sudo `。 1. 登出後再重新登入，以使變更生效。 1. 若要驗證是否已成功新增您的使用者名稱，請執行 **sudo echo test**。如果未提示您輸入密碼，表示已正確設定您的使用者。 1. 開啟 `/etc/sudoers` 檔案，然後在檔案結尾處新增以下一行： ` ALL=(ALL) NOPASSWD: ALL` ## 設定自訂權杖交換角色 您可以選擇使用自訂 IAM 角色做為待測裝置與 AWS 資源互動時所擔任的權杖交換角色。如需建立 IAM 角色的資訊，請參閱《[IAM 使用者指南》中的建立 IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html)。 ** 您必須符合下列要求，才能允許 IDT 使用您的自訂 IAM 角色。我們強烈建議您只將最低必要政策動作新增至此角色。 + [userdata.json](set-config.md#custom-token-exchange-role-idt) 組態檔案必須更新，才能將 `GreengrassV2TokenExchangeRole` 參數設定為 `true`。 + 自訂 IAM 角色必須使用下列最低信任政策設定： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Principal":{ "Service":[ "credentials.iot.amazonaws.com", "lambda.amazonaws.com", "sagemaker.amazonaws.com" ] }, "Action":"sts:AssumeRole" } ] } ``` ------ + 自訂 IAM 角色必須使用下列最低許可政策設定： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "iot:DescribeCertificate", "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:DescribeLogStreams", "iot:Connect", "iot:Publish", "iot:Subscribe", "iot:Receive", "iot:ListThingPrincipals", "iot:GetThingShadow", "iot:UpdateThingShadow", "s3:GetBucketLocation", "s3:GetObject", "s3:PutObject", "s3:AbortMultipartUpload", "s3:ListMultipartUploadParts" ], "Resource":"*" } ] } ``` ------ + 自訂 IAM 角色的名稱必須符合您在測試使用者的 IAM 許可中指定的 IAM 角色資源。根據預設，[測試使用者政策](dev-tst-prereqs.md#configure-idt-permissions)允許存取在其角色名稱中具有 `idt-`字首的 IAM 角色。如果您的 IAM 角色名稱不使用此字首，請將 `arn:aws:iam::*:role/custom-iam-role-name` 資源新增至 `roleAliasResources`陳述式和測試使用者政策中的 `passRoleForResources`陳述式，如下列範例所示： **Example `passRoleForResources` 陳述式** ``` { "Sid":"passRoleForResources", "Effect":"Allow", "Action":"iam:PassRole", "Resource":"arn:aws:iam::*:role/custom-iam-role-name", "Condition":{ "StringEquals":{ "iam:PassedToService":[ "iot.amazonaws.com", "lambda.amazonaws.com", "greengrass.amazonaws.com" ] } } } ``` **Example `roleAliasResources` 陳述式** ``` { "Sid":"roleAliasResources", "Effect":"Allow", "Action":[ "iot:CreateRoleAlias", "iot:DescribeRoleAlias", "iot:DeleteRoleAlias", "iot:TagResource", "iam:GetRole" ], "Resource":[ "arn:aws:iot:*:*:rolealias/idt-*", "arn:aws:iam::*:role/custom-iam-role-name" ] } ``` ## 設定您的裝置以測試選用功能 本節說明針對選用的 Docker 和機器學習 (ML) 功能執行 IDT 測試的裝置需求。ML 功能僅在 IDT v4.9.3 中受支援。只有當您想要測試這些功能時，才必須確定您的裝置符合這些要求。否則，請繼續進行[設定 IDT AWS IoT Greengrass 設定以執行資格套件](set-config.md)。 **Topics** + [Docker 資格要求](#idt-config-docker-components) + [ML 資格要求](#idt-config-ml-components) + [HSM 資格要求](#idt-config-hsm-components) ### Docker 資格要求 IDT for AWS IoT Greengrass V2 提供 Docker 資格測試，以驗證您的裝置是否可以使用 AWS提供的 [Docker 應用程式管理員](docker-application-manager-component.md)元件來下載您可以使用自訂 Docker 容器元件執行的 Docker 容器映像。如需建立自訂 Docker 元件的詳細資訊，請參閱 [執行 Docker 容器](run-docker-container.md)。 若要執行 Docker 資格測試，待測裝置必須符合下列需求，才能部署 Docker 應用程式管理員元件。 + [Docker 引擎](https://docs.docker.com/engine/) 1.9.1 或更新版本安裝在 Greengrass 核心裝置上。20.10 版是經過驗證可與 AWS IoT Greengrass Core 軟體搭配使用的最新版本。您必須先直接在核心裝置上安裝 Docker，才能部署執行 Docker 容器的元件。 + 在部署此元件之前，Docker 協助程式會在核心裝置上啟動和執行。 + 執行 Docker 容器元件的系統使用者必須具有根或管理員許可，或者您必須將 Docker 設定為以非根或非註冊使用者身分執行。 + 在 Linux 裝置上，您可以將使用者新增至 `docker`群組，在沒有 的情況下呼叫`docker`命令`sudo`。 + 在 Windows 裝置上，您可以將使用者新增至 `docker-users`群組，在沒有管理員權限的情況下呼叫`docker`命令。 ------ #### [ Linux or Unix ] 若要將 `ggc_user`或您用來執行 Docker 容器元件的非根使用者新增至 `docker`群組，請執行下列命令。 ``` sudo usermod -aG docker ggc_user ``` 如需詳細資訊，請參閱[以非根使用者的身分管理 Docker](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)。 ------ #### [ Windows Command Prompt (CMD) ] 若要將 `ggc_user`或您用來執行 Docker 容器元件的使用者新增至 `docker-users`群組，請以管理員身分執行下列命令。 ``` net localgroup docker-users ggc_user /add ``` ------ #### [ Windows PowerShell ] 若要將 `ggc_user`或您用來執行 Docker 容器元件的使用者新增至 `docker-users`群組，請以管理員身分執行下列命令。 ``` Add-LocalGroupMember -Group docker-users -Member ggc_user ``` ------ ### ML 資格要求 **注意** 機器學習功能僅在 IDT v4.9.3 中受支援。 IDT for AWS IoT Greengrass V2 提供 ML 資格測試，以驗證您的裝置是否可以使用 AWS提供的[機器學習元件](machine-learning-components.md)，使用[深度學習執行期](https://github.com/neo-ai/neo-ai-dlr)或 [TensorFlow Lite](https://www.tensorflow.org/lite/guide/python) ML 架構在本機執行 ML 推論。如需在 Greengrass 裝置上執行 ML 推論的詳細資訊，請參閱 [執行機器學習推論](perform-machine-learning-inference.md)。 若要執行 ML 資格測試，受測裝置必須符合下列要求，才能部署機器學習元件。 + 在執行 Amazon Linux 2 或 Ubuntu 18.04 的 Greengrass 核心裝置上，[GNU C Library](https://www.gnu.org/software/libc/) (glibc) 2.27 版或更新版本安裝在裝置上。 + 在 Armv7l 裝置上，例如 Raspberry Pi，安裝在裝置上的 OpenCV-Python 相依性。執行下列命令來安裝相依性。 ``` sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev ``` + 執行 Raspberry Pi OS Bullseye 的 Raspberry Pi 裝置必須符合下列要求： + 裝置上已安裝 NumPy 1.22.4 或更新版本。Raspberry Pi OS Bullseye 包含舊版的 NumPy，因此您可以執行下列命令以在裝置上升級 NumPy。 ``` pip3 install --upgrade numpy ``` + 在裝置上啟用的舊版攝影機堆疊。Raspberry Pi OS Bullseye 包含預設啟用且不相容的新攝影機堆疊，因此您必須啟用舊版攝影機堆疊。 **啟用舊版攝影機堆疊** 1. 執行下列命令以開啟 Raspberry Pi 組態工具。 ``` sudo raspi-config ``` 1. 選取**界面選項**。 1. 選取**舊版攝影機**以啟用舊版攝影機堆疊。 1. 重新啟動 Raspberry Pi。 ### HSM 資格要求 AWS IoT Greengrass 提供 [PKCS\$111 提供者元件](pkcs11-provider-component.md)，可與裝置上的 PKCS 硬體安全模組 (HSM) 整合。HSM 設定取決於您的裝置和您選擇的 HSM 模組。只要提供 [IDT 組態設定](set-config.md)中記錄的預期 HSM 組態，IDT 就會擁有執行此選用功能資格測試所需的資訊。 # 設定 IDT AWS IoT Greengrass 設定以執行資格套件 執行測試之前，您必須在主機電腦上設定 AWS 登入資料和裝置的設定。 ## 在 config.json 中設定 AWS 登入資料 您必須在 `/configs/config.json` 檔案中設定 IAM 使用者登入資料。使用在 中建立的 IDT for AWS IoT Greengrass V2 使用者的登入資料[建立和設定 AWS 帳戶](dev-tst-prereqs.md#config-aws-account-for-idt)。您可以使用下列兩種方式的其中之一指定登入資料： + 在登入資料檔案中 + 做為環境變數 ### 使用 AWS 登入資料檔案設定登入資料 IDT 會使用與 AWS CLI相同的登入資料檔案。如需詳細資訊，請參閱[組態與登入資料檔案](https://docs.aws.amazon.com/cli/latest/userguide/cli-config-files.html)。 登入資料檔案的位置會有所不同，取決於您使用的作業系統： + macOS, Linux: `~/.aws/credentials` + Windows：`C:\Users\UserName\.aws\credentials` 以下列格式將您的 AWS 登入資料新增至 `credentials` 檔案： ``` [default] aws_access_key_id = aws_secret_access_key = ``` 若要將 IDT for AWS IoT Greengrass V2 設定為使用 `credentials` 檔案中的 AWS 登入資料，請編輯 `config.json` 檔案，如下所示： ``` { "awsRegion": "region", "auth": { "method": "file", "credentials": { "profile": "default" } } } ``` **注意** 如果您不使用`default` AWS 設定檔，請務必變更`config.json`檔案中的設定檔名稱。如需詳細資訊，請參閱[具名描述檔](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html)。 ### 使用環境變數設定 AWS 登入資料 環境變數是由作業系統維護且由系統命令使用的變數。如果您關閉 SSH 工作階段，則不會儲存它們。IDT for AWS IoT Greengrass V2 可以使用 `AWS_ACCESS_KEY_ID`和 `AWS_SECRET_ACCESS_KEY` 環境變數來存放您的 AWS 登入資料。 若要在 Linux、macOS 或 Unix 上設定這些變數，請使用 **export**： ``` export AWS_ACCESS_KEY_ID= export AWS_SECRET_ACCESS_KEY= ``` 若要在 Windows 上設定這些變數，請使用 **set**： ``` set AWS_ACCESS_KEY_ID= set AWS_SECRET_ACCESS_KEY= ``` 若要設定 IDT 來使用環境變數，請在 `config.json` 檔案中編輯 `auth` 區段。請見此處範例： ``` { "awsRegion": "region", "auth": { "method": "environment" } } ``` ## 設定 device.json **注意** IDT v4.9.3 支援測試 `ml`、 `docker`和 `streamManagement`功能。IDT v4.9.4 和更新版本支援測試 。 `docker`如果您不想測試這些功能，請將對應的值設定為 `no`。 除了 AWS 登入資料之外，IDT for AWS IoT Greengrass V2 還需要執行測試之裝置的相關資訊。範例資訊包括 IP 地址、登入資訊、作業系統和 CPU 架構。 您必須使用位於 ` /configs/device.json` 中的 `device.json` 範本提供此資訊： ------ #### [ IDT v4.9.3 ] ``` [ { "id": "", "sku": "", "features": [ { "name": "arch", "value": "x86_64 | armv6l | armv7l | aarch64" }, { "name": "ml", "value": "dlr | tensorflowlite | dlr,tensorflowlite | no" }, { "name": "docker", "value": "yes | no" }, { "name": "streamManagement", "value": "yes | no" }, { "name": "hsi", "value": "hsm | no" } ], "devices": [ { "id": "", "operatingSystem": "Linux | Windows", "connectivity": { "protocol": "ssh", "ip": "", "port": 22, "publicKeyPath": "", "auth": { "method": "pki | password", "credentials": { "user": "", "privKeyPath": "/path/to/private/key", "password": "" } } } } ] } ] ``` **注意** 如果 `method` 是設定為 `pki`，則指定 `privKeyPath` 如果 `method` 是設定為 `password`，則指定 `password` 所有包含值的屬性都是必要的，如下所述： `id` 使用者定義的英數字元 ID，可唯一識別裝置的集合，稱為「裝置集區」**。屬於同一個集區的裝置必須有相同的硬體。當您執行測試套件，集區中的裝置會用來將工作負載平行化。多個裝置用來執行不同的測試。 `sku` 可唯一識別測試裝置的英數字元值。SKU 用來追蹤合格的主機板。 如果您想要在 Device AWS Partner Catalog 中列出您的裝置，您在此處指定的 SKU 必須符合您在列出程序中使用的 SKU。 `features` 包含裝置支援功能的陣列。所有功能都是必要的。 `arch` 測試執行驗證的支援作業系統架構。有效的值如下： + `x86_64` + `armv6l` + `armv7l` + `aarch64` `ml` 驗證裝置是否符合使用 AWS提供的機器學習 (ML) 元件所需的所有必要技術相依性。 啟用此功能也會驗證裝置是否可以使用[深度學習執行期](https://github.com/neo-ai/neo-ai-dlr)和 [TensorFlow Lite](https://www.tensorflow.org/lite/guide/python) ML 架構來執行 ML 推論。 有效值是 `dlr`和 `tensorflowlite`、 或 的任意組合`no`。 `docker` 驗證裝置是否符合所有必要的技術相依性，以使用 AWS提供的 Docker 應用程式管理員 (`aws.greengrass.DockerApplicationManager`) 元件。 啟用此功能也會驗證裝置是否可以從 Amazon ECR 下載 Docker 容器映像。 有效值是 `yes`或 的任意組合`no`。 `streamManagement` 驗證裝置是否可以下載、安裝和執行[AWS IoT Greengrass 串流管理員](manage-data-streams.md)。 有效值是 `yes`或 的任意組合`no`。 `hsi` 驗證裝置是否可以使用存放在硬體安全模組 (HSM) 中的私有金鑰和憑證來驗證 AWS IoT 和 AWS IoT Greengrass 服務的連線。此測試也會驗證 AWS提供的 [PKCS\$111 供應商元件](pkcs11-provider-component.md)是否可以使用廠商提供的 PKCS\$111 程式庫與 HSM 連接。如需詳細資訊，請參閱[硬體安全整合](hardware-security.md)。 有效值為 `hsm` 或 `no`。 測試 `hsi` 僅適用於 IDT v4.9.3 和更新版本。 `devices.id` 使用者定義的唯一識別符，用於識別要測試的裝置。 `devices.operatingSystem` 裝置作業系統。支援的值為 `Linux` 和 `Windows`。 `connectivity.protocol` 用來與此裝置通訊的通訊協定。目前，唯一支援的值是`ssh`用於實體裝置。 `connectivity.ip` 要測試之裝置的 IP 位址。 只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。 `connectivity.port` 選用。用於 SSH 連線的連接埠號碼。 預設值為 22。 只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。 `connectivity.publicKeyPath` 選用。用來驗證待測裝置連線之公有金鑰的完整路徑。 當您指定 時`publicKeyPath`，IDT 會在建立與待測裝置的 SSH 連線時驗證裝置的公有金鑰。如果未指定此值，IDT 會建立 SSH 連線，但不會驗證裝置的公有金鑰。 我們強烈建議您指定公有金鑰的路徑，並使用安全方法來擷取此公有金鑰。對於標準命令列型 SSH 用戶端， `known_hosts`檔案中會提供公有金鑰。如果您指定單獨的公有金鑰檔案，此檔案必須使用與 `known_hosts` 檔案相同的格式，也就是 ` ip-address key-type public-key`。如果有多個項目具有相同的 ip-address，則 IDT 所使用的金鑰類型項目必須早於檔案中的其他項目。 `connectivity.auth` 連線的驗證資訊。 只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。 `connectivity.auth.method` 用來透過指定的連線通訊協定存取裝置的驗證方法。 支援的值如下： + `pki` + `password` `connectivity.auth.credentials` 用於驗證的燈入資料。 `connectivity.auth.credentials.password` 用於登入要測試裝置的密碼。 只有當 `connectivity.auth.method` 設為 `password` 時，才會套用此值。 `connectivity.auth.credentials.privKeyPath` 用來登入待測裝置之私有金鑰的完整路徑。 只有當 `connectivity.auth.method` 設為 `pki` 時，才會套用此值。 `connectivity.auth.credentials.user` 登入要測試之裝置的使用者名稱。 ------ #### [ IDT v4.9.4 ] ``` [ { "id": "", "sku": "", "features": [ { "name": "arch", "value": "x86_64 | armv6l | armv7l | aarch64" }, { "name": "docker", "value": "yes | no" }, { "name": "hsi", "value": "hsm | no" } ], "devices": [ { "id": "", "operatingSystem": "Linux | Windows", "connectivity": { "protocol": "ssh", "ip": "", "port": 22, "publicKeyPath": "", "auth": { "method": "pki | password", "credentials": { "user": "", "privKeyPath": "/path/to/private/key", "password": "" } } } } ] } ] ``` **注意** 如果 `method` 是設定為 `pki`，則指定 `privKeyPath` 如果 `method` 是設定為 `password`，則指定 `password` 所有包含值的屬性都是必要的，如下所述： `id` 使用者定義的英數字元 ID，可唯一識別裝置的集合，稱為「裝置集區」**。屬於同一個集區的裝置必須有相同的硬體。當您執行測試套件，集區中的裝置會用來將工作負載平行化。多個裝置用來執行不同的測試。 `sku` 可唯一識別測試裝置的英數字元值。SKU 用來追蹤合格的主機板。 如果您想要在 Device AWS Partner Catalog 中列出您的裝置，您在此處指定的 SKU 必須符合您在列出程序中使用的 SKU。 `features` 包含裝置支援功能的陣列。所有功能都是必要的。 `arch` 測試執行驗證的支援作業系統架構。有效的值如下： + `x86_64` + `armv6l` + `armv7l` + `aarch64` `docker` 驗證裝置是否符合所有必要的技術相依性，以使用 AWS提供的 Docker 應用程式管理員 (`aws.greengrass.DockerApplicationManager`) 元件。 啟用此功能也會驗證裝置是否可以從 Amazon ECR 下載 Docker 容器映像。 有效值是 `yes`或 的任意組合`no`。 `hsi` 驗證裝置是否可以使用存放在硬體安全模組 (HSM) 中的私有金鑰和憑證來驗證 AWS IoT 和 AWS IoT Greengrass 服務的連線。此測試也會驗證 AWS提供的 [PKCS\$111 供應商元件](pkcs11-provider-component.md)是否可以使用廠商提供的 PKCS\$111 程式庫與 HSM 連接。如需詳細資訊，請參閱[硬體安全整合](hardware-security.md)。 有效值為 `hsm` 或 `no`。 測試 `hsi` 僅適用於 IDT v4.9.3 和更新版本。 `devices.id` 使用者定義的唯一識別符，用於識別要測試的裝置。 `devices.operatingSystem` 裝置作業系統。支援的值為 `Linux` 和 `Windows`。 `connectivity.protocol` 用來與此裝置通訊的通訊協定。目前，唯一支援的值是`ssh`用於實體裝置。 `connectivity.ip` 要測試之裝置的 IP 位址。 只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。 `connectivity.port` 選用。用於 SSH 連線的連接埠號碼。 預設值為 22。 只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。 `connectivity.publicKeyPath` 選用。用來驗證待測裝置連線之公有金鑰的完整路徑。 當您指定 時`publicKeyPath`，IDT 會在建立與待測裝置的 SSH 連線時驗證裝置的公有金鑰。如果未指定此值，IDT 會建立 SSH 連線，但不會驗證裝置的公有金鑰。 我們強烈建議您指定公有金鑰的路徑，並使用安全方法來擷取此公有金鑰。對於標準命令列型 SSH 用戶端， `known_hosts`檔案中會提供公有金鑰。如果您指定單獨的公有金鑰檔案，此檔案必須使用與 `known_hosts` 檔案相同的格式，也就是 ` ip-address key-type public-key`。如果有多個項目具有相同的 ip-address，則 IDT 所使用的金鑰類型項目必須早於檔案中的其他項目。 `connectivity.auth` 連線的驗證資訊。 只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。 `connectivity.auth.method` 用來透過指定的連線通訊協定存取裝置的驗證方法。 支援的值如下： + `pki` + `password` `connectivity.auth.credentials` 用於驗證的燈入資料。 `connectivity.auth.credentials.password` 用於登入要測試裝置的密碼。 只有當 `connectivity.auth.method` 設為 `password` 時，才會套用此值。 `connectivity.auth.credentials.privKeyPath` 用來登入待測裝置之私有金鑰的完整路徑。 只有當 `connectivity.auth.method` 設為 `pki` 時，才會套用此值。 `connectivity.auth.credentials.user` 登入要測試之裝置的使用者名稱。 ------ ## 設定 userdata.json IDT for AWS IoT Greengrass V2 也需要有關測試成品和 AWS IoT Greengrass 軟體位置的其他資訊。 您必須使用位於 ` /configs/userdata.json` 中的 `userdata.json` 範本提供此資訊： ``` { "TempResourcesDirOnDevice": "/path/to/temp/folder", "InstallationDirRootOnDevice": "/path/to/installation/folder", "GreengrassNucleusZip": "/path/to/aws.greengrass.nucleus.zip", "PreInstalled": "yes/no", "GreengrassV2TokenExchangeRole": "custom-iam-role-name", "hsm": { "greengrassPkcsPluginJar": "/path/to/aws.greengrass.crypto.Pkcs11Provider-latest.jar", "pkcs11ProviderLibrary": "/path/to/pkcs11-vendor-library", "slotId": "slot-id", "slotLabel": "slot-label", "slotUserPin": "slot-pin", "keyLabel": "key-label", "preloadedCertificateArn": "certificate-arn" "rootCA": "path/to/root-ca" } } ``` 所有包含值的屬性都需要，如下所述： `TempResourcesDirOnDevice` 待測裝置上要存放測試成品之暫存資料夾的完整路徑。確定寫入此目錄不需要 sudo 許可。 IDT 會在完成執行測試時刪除此資料夾的內容。 `InstallationDirRootOnDevice` 要安裝之裝置上資料夾的完整路徑 AWS IoT Greengrass。對於 PreInstalled Greengrass，這是 Greengrass 安裝目錄的路徑。 您必須為此資料夾設定必要的檔案許可。對安裝路徑中的每個資料夾執行下列命令。 ``` sudo chmod 755 folder-name ``` `GreengrassNucleusZip` 主機電腦上 Greengrass 核 ZIP (`greengrass-nucleus-latest.zip`) 檔案的完整路徑。使用 PreInstalled Greengrass 進行測試時，不需要此欄位。 如需 IDT for 的 Greengrass 核支援版本的相關資訊 AWS IoT Greengrass，請參閱 [最新版 IDT for AWS IoT Greengrass V2](dev-test-versions.md#idt-latest-version)。若要下載最新的 Greengrass 軟體，請參閱[下載 AWS IoT Greengrass 軟體](https://docs.aws.amazon.com/greengrass/v2/developerguide/dev-tst-prereqs.html#config-gg)。 `PreInstalled` 此功能僅適用於 Linux 裝置上的 IDT v4.5.8 和更新版本。 （選用） 當值為*是*時，IDT 會假設 中提到的路徑`InstallationDirRootOnDevice`是安裝 Greengrass 的目錄。 如需如何在裝置上安裝 Greengrass 的詳細資訊，請參閱 [使用自動資源佈建安裝 AWS IoT Greengrass 核心軟體](quick-installation.md)。如果[使用手動佈建安裝 ](https://docs.aws.amazon.com/greengrass/v2/developerguide/manual-installation.html)，請在手動建立 AWS IoT 物件時包含「將[AWS IoT 物件](https://docs.aws.amazon.com/greengrass/v2/developerguide/manual-installation.html#create-iot-thing)新增至新的或現有的物件群組」步驟。IDT 假設物件和物件群組是在安裝設定期間建立的。請確定這些值反映在 `effectiveConfig.yaml` 檔案中。IDT 會在 `effectiveConfig.yaml`下檢查 檔案`/config/effectiveConfig.yaml`。 對於使用 HSM 執行測試，請確定 `aws.greengrass.crypto.Pkcs11Provider` 欄位已在 中更新`effectiveConfig.yaml`。 `GreengrassV2TokenExchangeRole` （選用） 您想要用作待測裝置假設與 AWS 資源互動之字符交換角色的自訂 IAM 角色。 IDT 會使用此自訂 IAM 角色，而不是在測試執行期間建立預設權杖交換角色。如果您使用自訂角色，您可以更新[測試使用者的 IAM 許可](dev-tst-prereqs.md#configure-idt-permissions)，以排除允許使用者建立和刪除 IAM 角色和政策的 `iamResourcesUpdate` 陳述式。 如需建立自訂 IAM 角色做為權杖交換角色的詳細資訊，請參閱 [設定自訂權杖交換角色](device-config-setup.md#configure-custom-tes-role-for-idt)。 `hsm` 此功能適用於 IDT v4.5.1 和更新版本。 （選用） 使用硬體安全模組 (HSM) 進行測試的 AWS IoT Greengrass 組態資訊。否則，應省略 `hsm` 屬性。如需詳細資訊，請參閱[硬體安全整合](hardware-security.md)。 只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。 如果 IDT 和另一個系統共用硬體安全模組，HSM 組態可能會被視為敏感資料。在這種情況下，您可以將這些組態值儲存在 參數存放區 SecureString 參數中 AWS ，並設定 IDT 在測試執行期間擷取，以避免以純文字形式保護這些組態值。如需詳細資訊，請參閱[從 AWS 參數存放區擷取組態](#fetch-config) `hsm.greengrassPkcsPluginJar` 您下載至 IDT 主機機器之 [PKCS\$111 提供者元件](pkcs11-provider-component.md)的完整路徑。 AWS IoT Greengrass 提供此元件做為 JAR 檔案，您可以在安裝期間下載此元件以指定為佈建外掛程式。您可以將元件 JAR 檔案的最新版本下載為下列 URL：https：//[https://d2s8p88vqu9w66.cloudfront.net/releases/Pkcs11Provider/aws.greengrass.crypto.Pkcs11Provider-latest.jar](https://d2s8p88vqu9w66.cloudfront.net/releases/Pkcs11Provider/aws.greengrass.crypto.Pkcs11Provider-latest.jar)。 `hsm.pkcs11ProviderLibrary` 由硬體安全模組 (HSM) 供應商提供與 HSM 互動之 PKCS\$111 程式庫的完整路徑。 `hsm.slotId` 用於識別您載入金鑰和憑證之 HSM 插槽的插槽 ID。 `hsm.slotLabel` 用於識別您載入金鑰和憑證之 HSM 插槽的插槽標籤。 `hsm.slotUserPin` IDT 用來向 HSM 驗證 AWS IoT Greengrass Core 軟體的使用者 PIN 碼。 基於安全最佳實務，請勿在生產裝置上使用相同的使用者 PIN 碼。 `hsm.keyLabel` 用於識別硬體模組中之金鑰的標籤。金鑰和憑證都必須使用相同的金鑰標籤。 `hsm.preloadedCertificateArn` AWS IoT 雲端中上傳裝置憑證的 Amazon Resource Name (ARN)。 您先前必須使用 HSM 中的 金鑰產生此憑證，將其匯入 HSM，並將其上傳至 AWS IoT 雲端。如需有關產生和匯入憑證的資訊，請參閱 HSM 的文件。 您必須將憑證上傳到您在 [config.json 中提供的相同帳戶和區域](#cfg-aws-gg)。如需將憑證上傳至 的詳細資訊 AWS IoT，請參閱《 *AWS IoT 開發人員指南*》中的[手動註冊用戶端憑證](https://docs.aws.amazon.com/iot/latest/developerguide/manual-cert-registration.html)。 `hsm.rootCAPath` （選用） IDT 主機機器上簽署憑證的根憑證授權機構 (CA) 的完整路徑。如果您建立的 HSM 中的憑證不是由 Amazon 根 CA 簽署，則此為必要項目。 ## 從 AWS 參數存放區擷取組態 AWS IoT Device Tester (IDT) 包含從 [AWS Systems Manager 參數存放區](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)擷取組態值的選用功能。 AWS 參數存放區允許安全且加密的組態儲存。設定後，IDT 可以從 AWS 參數存放區擷取參數，取代將參數以純文字形式儲存在 `userdata.json` 檔案內。這對於應加密儲存的任何敏感資料很有用，例如：密碼、接腳和其他秘密。 1. 若要使用此功能，您必須更新建立 [IDT 使用者](https://docs.aws.amazon.com/greengrass/v2/developerguide/dev-tst-prereqs.html)所用的許可，以允許對 IDT 設定為使用的參數執行 GetParameter 動作。以下是可新增至 IDT 使用者的許可陳述式範例。如需詳細資訊，請參閱 [AWS Systems Manager 使用者指南](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-access.html)。 ``` { "Sid":"parameterStoreResources", "Effect": "Allow", "Action": [ "ssm:GetParameter" ], "Resource": "arn:aws:ssm:*:*:parameter/IDT*" } ``` 上述許可設定為允許`IDT`使用萬用字元 擷取名稱開頭為 的所有參數`*`。您應該根據您的需求自訂此項目，以便 IDT 能夠根據您正在使用的參數命名來擷取任何設定的參數。 1. 您需要將組態值存放在 Paramater Store AWS 中。這可以從 AWS 主控台或 CLI AWS 完成。 AWS 參數存放區可讓您選擇加密或未加密的儲存。對於儲存機密、密碼和 PIN 等敏感值，您應該使用加密選項，這是 SecureString 的參數類型。若要使用 CLI AWS 上傳參數，您可以使用下列命令： ``` aws ssm put-parameter --name IDT-example-name --value IDT-example-value --type SecureString ``` 您可以使用下列命令來驗證參數是否已存放。（選用） 使用 `--with-decryption`旗標來擷取解密的 SecureString 參數。 ``` aws ssm get-parameter --name IDT-example-name ``` 使用 AWS CLI 將上傳目前 CLI 使用者 AWS 區域中的 參數，IDT 將從 中設定的區域擷取參數`config.json`。若要從 AWS CLI 檢查您的區域，請使用下列項目： ``` aws configure get region ``` 1. 一旦您在 AWS 雲端中有組態值，您就可以更新 IDT 組態內的任何值，以從 AWS 雲端擷取。若要這樣做，請在表單的 IDT 組態中使用預留位置`{{AWS.Parameter.parameter_name}}`，以該名稱從參數存放區擷取 AWS 參數。 例如，假設您想要使用步驟 2 中的 `IDT-example-name` 參數做為 HSM 組態中的 HSM keyLabel。若要這樣做，您可以更新 `userdata.json` ，如下所示： ``` "hsm": { "keyLabel": "{{AWS.Parameter.IDT-example-name}}", [...] } ``` IDT 將在步驟 2 `IDT-example-value`中設定為 的執行時間擷取此參數的值。此組態類似於設定，`"keyLabel": "IDT-example-value"`但該值會以加密方式儲存在 AWS 雲端中。 # 執行 AWS IoT Greengrass 資格套件 在您[設定必要組態](set-config.md)之後，便可開始測試。完整測試套件的執行時間取決於您的硬體。做為參考，在 Raspberry Pi 3B 上完成整個測試套件約需 30 分鐘。 使用下列`run-suite`命令來執行一組測試。 ``` devicetester_[linux | mac | win]_x86-64 run-suite \\ --suite-id suite-id \\ --group-id group-id \\ --pool-id your-device-pool \\ --test-id test-id \\ --update-idt y|n \\ --userdata userdata.json ``` 所有選項都是選用的。例如，`pool-id`如果您只有一個裝置集區，這是一組相同的裝置，在您的 `device.json` 檔案中定義，您可以省略 。或者，如果您想要執行 `tests` 資料夾中最新的測試套件版本，則可以省略 `suite-id`。 **注意** 如果線上有較新的測試套件版本，IDT 會提示您。如需詳細資訊，請參閱[測試套件版本](idt-greengrass-qualification.md#idt-test-suite-versions)。 ## 執行資格套件的範例命令 下列命令列範例示範如何執行裝置集區的資格測試。如需 `run-suite` 和其他 IDT 命令的詳細資訊，請參閱 [IDT for AWS IoT Greengrass V2 命令](#bk-cli)。 使用下列命令，在指定的測試套件中執行所有測試群組。`list-suites` 命令會列出 `tests` 資料夾中的測試套件。 ``` devicetester_[linux | mac | win]_x86-64 run-suite \ --suite-id GGV2Q_1.0.0 \ --pool-id \ --userdata userdata.json ``` 使用以下命令在測試套件中執行特定測試群組。`list-groups` 命令會列出測試套件中的測試群組。 ``` devicetester_[linux | mac | win]_x86-64 run-suite \ --suite-id GGV2Q_1.0.0 \ --group-id \ --pool-id \ --userdata userdata.json ``` 使用下列命令在測試群組中執行特定測試案例。 ``` devicetester_[linux | mac | win]_x86-64 run-suite \ --group-id \ --test-id \ --userdata userdata.json ``` 使用以下命令在測試群組中執行多個測試案例。 ``` devicetester_[linux | mac | win]_x86-64 run-suite \ --group-id \ --test-id , --userdata userdata.json ``` 使用下列命令列出測試群組中的所有測試案例。 ``` devicetester_[linux | mac | win]_x86-64 list-test-cases --group-id ``` 我們建議您執行完整的資格測試套件，以正確的順序執行測試群組相依性。如果您選擇執行特定測試群組，建議您先執行相依性檢查程式測試群組，以確保在執行相關測試群組之前已安裝所有 Greengrass 相依性。例如： + 在執行核心資格測試組之前執行 `coredependencies`。 ## IDT for AWS IoT Greengrass V2 命令 IDT 命令位於 `/bin` 目錄中。若要執行測試套件，請以下列格式提供 命令： `help` 列出所指定命令的相關資訊。 `list-groups` 列出指定測試套件中的群組。 `list-suites` 列出可用的測試套件。 `list-supported-products` 在此情況下，列出支援的 產品 AWS IoT Greengrass 版本，以及目前 IDT 版本的測試套件版本。 `list-test-cases` 列出特定測試群組中的測試案例。支援下列選項： + `group-id`。 要搜尋的測試群組。此選項為必要選項，且必須指定單一群組。 `run-suite` 在裝置集區上執行測試套件。以下是一些支援的選項： + `suite-id`。 要執行的測試套件版本。如果未指定，IDT 會使用 `tests` 資料夾中的最新版本。 + `group-id`。 要執行的測試群組，以逗號分隔的清單。如果未指定，IDT 會根據 中的設定，在測試套件中執行所有適當的測試群組`device.json`。IDT 不會根據您設定的設定執行裝置不支援的任何測試群組，即使這些測試群組是在`group-id`清單中指定。 + `test-id`。 要執行的測試案例，以逗號分隔的清單。指定時，`group-id` 必須指定單一群組。 + `pool-id`。 要測試的裝置集區。如果 `device.json` 檔案中已定義多個裝置集區，則必須指定集區。 + `stop-on-first-failure`。 設定 IDT 在第一次失敗時停止執行。當您想要偵錯指定的測試群組`group-id`時，請使用此選項搭配 。執行完整測試套件產生資格報告時，請勿使用此選項。 + `update-idt`。 設定提示更新 IDT 的回應。如果 IDT 偵測到有較新的版本，`Y`回應會停止測試執行。`N` 回應會繼續測試執行。 + `userdata`。 `userdata.json` 檔案的完整路徑，其中包含測試成品路徑的相關資訊。該`run-suite`命令需要此選項。`userdata.json` 檔案必須位於 *devicetester\$1extract\$1location*/devicetester\$1ggv2\$1*【win\$1mac\$1linux】*/configs/ 目錄中。 如需 `run-suite` 選項的詳細資訊，請使用下列 `help` 選項： ``` devicetester_[linux | mac | win]_x86-64 run-suite -h ``` # 了解結果和日誌 本節說明如何檢視和解譯 IDT 結果報告與日誌。 若要對錯誤進行故障診斷，請參閱 [對 IDT for AWS IoT Greengrass V2 進行故障診斷](idt-troubleshooting.md)。 ## 檢視結果 執行期間，IDT 會將錯誤寫入主控台、日誌檔和測試報告。IDT 完成資格測試套件後會產生兩份測試報告。這些報告位於 中`/results//`。兩個報告都會擷取執行資格測試套件的結果。 `awsiotdevicetester_report.xml` 是您提交給 AWS 以在 Device AWS Partner Catalog 中列出裝置的資格測試報告。該報告包含下列元素： + IDT 版本。 + 已測試的 AWS IoT Greengrass 版本。 + `device.json` 檔案中指定的 SKU 和裝置集區名稱。 + `device.json` 檔案中指定的裝置集區的功能。 + 測試結果的彙總摘要。 + 根據裝置功能進行測試的程式庫測試結果明細，例如本機資源存取、陰影和 MQTT。 `GGV2Q_Result.xml` 報告採用 [JUnit XML 格式](https://llg.cubic.org/docs/junit/)。您可以將它整合到持續整合和部署平台，例如 [Jenkins](https://jenkins.io/)、[Bamboo](https://www.atlassian.com/software/bamboo) 等。該報告包含下列元素： + 測試結果的彙總摘要。 + 已測試 AWS IoT Greengrass 功能對測試結果進行分解。 ## 解譯 AWS IoT Device Tester 結果 `awsiotdevicetester_report.xml` 或 `awsiotdevicetester_report.xml` 的報告區段會列出已執行的測試及結果。 第一個 XML 標籤``包含測試執行的摘要。例如： ``` ````` 標籤中使用的屬性 `name` 測試套件的名稱。 `time` 執行資格套件所需的時間，以秒為單位。 `tests` 執行的測試數量。 `failures` 已執行但未通過的測試次數。 `errors` IDT 無法執行的測試數量。 `disabled` 忽略此屬性。不會使用。 `awsiotdevicetester_report.xml` 檔案包含 `` 標籤，其中包含關於受測產品和經過一系列測試驗證後之產品功能的資訊。`` 標籤中使用的屬性 `name` 受測產品名稱。 `version` 受測產品版本。 `features` 驗證的功能。標記為 `required` 的功能為提交主機板獲得資格時所需。以下片段顯示此資訊如何出現在 `awsiotdevicetester_report.xml` 檔案中。 ``` ``` 如果必要功能沒有測試失敗或錯誤，您的裝置會符合執行的技術需求， AWS IoT Greengrass 並且可以與 AWS IoT 服務互通。如果您想要在 Device AWS Partner Catalog 中列出您的裝置，您可以使用此報告做為資格證據。 如果測試發生失敗或錯誤，您可以檢閱 `` XML 標籤來識別失敗的測試。`` 標籤內的 `` XML 標籤會顯示測試群組的測試結果摘要。例如： ``` ``` 其格式類似於 `` 標籤，但有不使用且可忽略的 `skipped` 屬性。在每個 `` XML 標籤中，每個為測試群組執行的測試都有``標籤。例如： ``` > ````` 標籤中使用的屬性 `name` 測試的名稱。 `attempts` IDT 執行測試案例的次數。 當測試案例失敗或發生錯誤時，系統就會將 `` 或 `` 標籤新增至 `` 標籤，其中附有相關資訊以利故障診斷。例如： ``` Reason for the test failure Reason for the test execution error ``` ## 檢視日誌 IDT 會從 中的測試執行產生日誌`/results//logs`。該工具會產生兩組日誌： `test_manager.log` 從 的測試管理員元件產生的日誌 AWS IoT Device Tester （例如，與組態、測試排序和報告產生相關的日誌）。 `.log (for example, lambdaDeploymentTest.log)` 測試群組內的測試案例日誌，包括測試中裝置的日誌。從 IDT v4.2.0 開始，IDT 會將每個測試案例的測試日誌分組到 `/results//logs//`目錄中的個別 ** 資料夾。 # 使用 IDT 來開發和執行您自己的測試套件 從 IDT v4.0.1 開始，IDT for AWS IoT Greengrass V2 結合了標準化的組態設定和結果格式，以及測試套件環境，可讓您為裝置和裝置軟體開發自訂測試套件。您可以為自己的內部驗證新增自訂測試，或將其提供給客戶進行裝置驗證。 使用 IDT 來開發和執行自訂測試套件，如下所示： **開發自訂測試套件** + 為您要測試的 Greengrass 裝置建立具有自訂測試邏輯的測試套件。 + 提供 IDT 您的自訂測試套件來測試執行器。包含測試套件特定設定組態的相關資訊。 **執行自訂測試套件** + 設定您要測試的裝置。 + 實作您想要使用的測試套件所需的設定組態。 + 使用 IDT 執行您的自訂測試套件。 + 檢視 IDT 所執行測試的測試結果和執行日誌。 ## 下載 AWS IoT Device Tester 適用於 的最新版本 AWS IoT Greengrass 下載[最新版本](idt-programmatic-download.md)的 IDT，並將軟體解壓縮到檔案系統上具有讀取/寫入許可的位置 (**)。 **注意** IDT 不支援由多位使用者從共用位置執行，例如 NFS 目錄或 Windows 網路共用資料夾。我們建議您將 IDT 套件解壓縮到本機磁碟機，並在本機工作站上執行 IDT 二進位檔。 Windows 的路徑長度限制為 260 個字元。如果您使用的是 Windows，請將 IDT 解壓縮到根目錄，例如 `C:\ ` 或 `D:\`，使路徑保持在 260 個字元的限制以下。 ## 測試套件建立工作流程 測試套件由三種類型的檔案組成： + 為 IDT 提供如何執行測試套件相關資訊的組態檔案。 + 測試 IDT 用來執行測試案例的可執行檔。 + 執行測試所需的其他檔案。 完成下列基本步驟以建立自訂 IDT 測試： 1. 為您的測試套件[建立組態檔案](idt-json-config.md)。 1. [建立包含測試套件測試邏輯的測試案例可執行檔](create-test-executables.md)。 1. 驗證並記錄[測試執行器執行測試套件所需的組態資訊](set-custom-idt-config.md)。 1. 確認 IDT 可以執行您的測試套件，並如預期產生[測試結果](run-debug-custom-tests.md)。 若要快速建置範例自訂套件並進行執行，請遵循 中的指示[教學課程：建置並執行範例 IDT 測試套件](build-sample-suite.md)。 若要開始在 Python 中建立自訂測試套件，請參閱 [教學課程：開發簡單的 IDT 測試套件](create-custom-tests.md)。 # 教學課程：建置並執行範例 IDT 測試套件 AWS IoT Device Tester 下載包含範例測試套件的原始程式碼。您可以完成此教學課程來建置和執行範例測試套件，以了解如何使用 IDT for AWS IoT Greengrass 來執行自訂測試套件。 在本教學課程中，您將完成下列步驟： 1. [建置範例測試套件](#build-sample) 1. [使用 IDT 執行範例測試套件](#run-sample) ## 先決條件 為了完成本教學，您需要以下項目： + **主機電腦需求** + 的最新版本 AWS IoT Device Tester + [Python](https://www.python.org/downloads/) 3.7 或更新版本 若要檢查安裝在電腦上的 Python 版本，請執行下列命令： ``` python3 --version ``` 在 Windows 上，如果使用此命令傳回錯誤，請`python --version`改用 。如果傳回的版本編號為 3.7 或更新版本，請在 Powershell 終端機中執行下列命令，將 `python3`設定為`python`命令的別名。 ``` Set-Alias -Name "python3" -Value "python" ``` 如果未傳回版本資訊或版本編號小於 3.7，請遵循[下載 Python](https://wiki.python.org/moin/BeginnersGuide/Download) 中的指示安裝 Python 3.7\$1。如需詳細資訊，請參閱 [Python 文件](https://docs.python.org)。 + [urllib3](https://urllib3.readthedocs.io/en/latest/) 若要驗證 `urllib3` 是否正確安裝，請執行下列命令： ``` python3 -c 'import urllib3' ``` 如果`urllib3`未安裝 ，請執行下列命令來安裝它： ``` python3 -m pip install urllib3 ``` + **裝置要求** + 具有 Linux 作業系統和與主機電腦相同網路連線的裝置。 我們建議您將 [Raspberry Pi](https://www.raspberrypi.org/) 與 Raspberry Pi 作業系統搭配使用。請務必在 Raspberry Pi 上設定 [SSH](https://www.raspberrypi.org/documentation/remote-access/ssh/) 以遠端連線到它。 ## 設定 IDT 的裝置資訊 設定您的裝置資訊，讓 IDT 執行測試。您必須使用下列資訊更新位於 `/configs` 資料夾的 `device.json` 範本。 ``` [ { "id": "pool", "sku": "N/A", "devices": [ { "id": "", "connectivity": { "protocol": "ssh", "ip": "", "port": "", "auth": { "method": "pki | password", "credentials": { "user": "", "privKeyPath": "/path/to/private/key", "password": "" } } } } ] } ] ``` 在 `devices` 物件中，提供下列資訊： `id` 您裝置的使用者定義唯一識別符。 `connectivity.ip` 您裝置的 IP 地址。 `connectivity.port` 選用。用於 SSH 連線至您裝置的連接埠號碼。 `connectivity.auth` 連線的驗證資訊。 只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。 `connectivity.auth.method` 用來透過指定的連線通訊協定存取裝置的驗證方法。 支援的值如下： + `pki` + `password` `connectivity.auth.credentials` 用於驗證的燈入資料。 `connectivity.auth.credentials.user` 用來登入裝置的使用者名稱。 `connectivity.auth.credentials.privKeyPath` 用來登入您裝置之私有金鑰的完整路徑。 只有當 `connectivity.auth.method` 設為 `pki` 時，才會套用此值。 `devices.connectivity.auth.credentials.password` 用於登入您裝置的密碼。 只有當 `connectivity.auth.method` 設為 `password` 時，才會套用此值。 **注意** 如果 `method` 是設定為 `pki`，則指定 `privKeyPath` 如果 `method` 是設定為 `password`，則指定 `password` ## 建置範例測試套件 `/samples/python` 資料夾包含範例組態檔案、原始程式碼和 IDT 用戶端 SDK，您可以使用提供的建置指令碼將其合併為測試套件。下列目錄樹狀目錄顯示這些範例檔案的位置： ``` ├── ... ├── tests ├── samples │ ├── ... │ └── python │ ├── configuration │ ├── src │ └── build-scripts │ ├── build.sh │ └── build.ps1 └── sdks ├── ... └── python └── idt_client ``` 若要建置測試套件，請在主機電腦上執行下列命令： ------ #### [ Windows ] ``` cd /samples/python/build-scripts ./build.ps1 ``` ------ #### [ Linux, macOS, or UNIX ] ``` cd /samples/python/build-scripts ./build.sh ``` ------ 這會在 `IDTSampleSuitePython_1.0.0` 資料夾內的 `/tests` 資料夾中建立範例測試套件。檢閱 `IDTSampleSuitePython_1.0.0` 資料夾中的檔案，以了解範例測試套件的結構，並查看各種測試案例可執行檔和測試組態 JSON 檔案的範例。 **注意** 範例測試套件包含 python 原始程式碼。請勿在測試套件程式碼中包含敏感資訊。 下一步：使用 IDT 執行[您建立的範例測試套件](#run-sample)。 ## 使用 IDT 執行範例測試套件 若要執行範例測試套件，請在主機電腦上執行下列命令： ``` cd /bin ./devicetester_[linux | mac | win_x86-64] run-suite --suite-id IDTSampleSuitePython ``` IDT 會執行範例測試套件，並將結果串流至主控台。當測試完成執行時，您會看到下列資訊： ``` ========== Test Summary ========== Execution Time: 5s Tests Completed: 4 Tests Passed: 4 Tests Failed: 0 Tests Skipped: 0 ---------------------------------- Test Groups: sample_group: PASSED ---------------------------------- Path to IoT Device Tester Report: /path/to/devicetester/results/87e673c6-1226-11eb-9269-8c8590419f30/awsiotdevicetester_report.xml Path to Test Execution Logs: /path/to/devicetester/results/87e673c6-1226-11eb-9269-8c8590419f30/logs Path to Aggregated JUnit Report: /path/to/devicetester/results/87e673c6-1226-11eb-9269-8c8590419f30/IDTSampleSuitePython_Report.xml ``` ## 疑難排解 使用以下資訊來協助解決完成教學課程的任何問題。 **測試案例未成功執行** 如果測試未成功執行，IDT 會將錯誤日誌串流至主控台，以協助您對測試執行進行疑難排解。請確定您符合本教學課程的所有[先決條件](#prereqs-tutorial-sample)。 **無法連線至待測裝置** 請確認下列內容： + 您的 `device.json` 檔案包含正確的 IP 地址、連接埠和身分驗證資訊。 + 您可以從主機電腦透過 SSH 連線至裝置。 # 教學課程：開發簡單的 IDT 測試套件 測試套件結合了下列項目： + 包含測試邏輯的測試可執行檔 + 描述測試套件的組態檔案 本教學課程說明如何使用 IDT for AWS IoT Greengrass 來開發包含單一測試案例的 Python 測試套件。在本教學課程中，您將完成下列步驟： 1. [建立測試套件目錄](#test-suite-dir) 1. [建立組態檔案](#test-suite-json) 1. [建立測試案例可執行檔](#test-suite-exe) 1. [執行測試套件](#run-test-suite) ## 先決條件 為了完成本教學，您需要以下項目： + **主機電腦需求** + 的最新版本 AWS IoT Device Tester + [Python](https://www.python.org/downloads/) 3.7 或更新版本 若要檢查安裝在電腦上的 Python 版本，請執行下列命令： ``` python3 --version ``` 在 Windows 上，如果使用此命令傳回錯誤，請`python --version`改用 。如果傳回的版本編號為 3.7 或更新版本，請在 Powershell 終端機中執行下列命令，將 `python3`設定為`python`命令的別名。 ``` Set-Alias -Name "python3" -Value "python" ``` 如果未傳回版本資訊或版本編號小於 3.7，請遵循[下載 Python](https://wiki.python.org/moin/BeginnersGuide/Download) 中的指示安裝 Python 3.7\$1。如需詳細資訊，請參閱 [Python 文件](https://docs.python.org)。 + [urllib3](https://urllib3.readthedocs.io/en/latest/) 若要驗證 `urllib3` 是否正確安裝，請執行下列命令： ``` python3 -c 'import urllib3' ``` 如果`urllib3`未安裝 ，請執行下列命令來安裝它： ``` python3 -m pip install urllib3 ``` + **裝置要求** + 具有 Linux 作業系統和與主機電腦相同網路連線的裝置。 我們建議您將 [Raspberry Pi](https://www.raspberrypi.org/) 與 Raspberry Pi 作業系統搭配使用。請確定您在 Raspberry Pi 上設定 [SSH](https://www.raspberrypi.org/documentation/remote-access/ssh/) 以遠端連線到它。 ## 建立測試套件目錄 IDT 會在邏輯上將測試案例分成每個測試套件內的測試群組。每個測試案例都必須位於測試群組內。在本教學課程中，請建立名為 的資料夾，`MyTestSuite_1.0.0`並在此資料夾中建立下列目錄樹狀目錄： ``` MyTestSuite_1.0.0 └── suite └── myTestGroup └── myTestCase ``` ## 建立組態檔案 您的測試套件必須包含下列必要的[組態檔案](idt-json-config.md)：必要的組態檔案 `suite.json` 包含測試套件的相關資訊。請參閱 [設定 suite.json](idt-json-config.md#suite-json)。 `group.json` 包含測試群組的相關資訊。您必須為測試套件中的每個測試群組建立`group.json`檔案。請參閱 [設定 group.json](idt-json-config.md#group-json)。 `test.json` 包含測試案例的相關資訊。您必須為測試套件中的每個測試案例建立`test.json`檔案。請參閱 [設定 test.json](idt-json-config.md#test-json)。 1. 在 `MyTestSuite_1.0.0/suite`資料夾中，建立具有下列結構`suite.json`的檔案： ``` { "id": "MyTestSuite_1.0.0", "title": "My Test Suite", "details": "This is my test suite.", "userDataRequired": false } ``` 1. 在 `MyTestSuite_1.0.0/myTestGroup`資料夾中，建立具有下列結構`group.json`的檔案： ``` { "id": "MyTestGroup", "title": "My Test Group", "details": "This is my test group.", "optional": false } ``` 1. 在 `MyTestSuite_1.0.0/myTestGroup/myTestCase`資料夾中，建立具有下列結構`test.json`的檔案： ``` { "id": "MyTestCase", "title": "My Test Case", "details": "This is my test case.", "execution": { "timeout": 300000, "linux": { "cmd": "python3", "args": [ "myTestCase.py" ] }, "mac": { "cmd": "python3", "args": [ "myTestCase.py" ] }, "win": { "cmd": "python3", "args": [ "myTestCase.py" ] } } } ``` 資料夾的目錄樹狀目錄現在`MyTestSuite_1.0.0`看起來應該如下所示： ``` MyTestSuite_1.0.0 └── suite ├── suite.json └── myTestGroup ├── group.json └── myTestCase └── test.json ``` ## 取得 IDT 用戶端 SDK 您可以使用 [IDT 用戶端 SDK](create-test-executables.md#idt-client-sdk) 讓 IDT 與待測裝置互動，並報告測試結果。在本教學課程中，您將使用 開發套件的 Python 版本。 從 `/sdks/python/` 資料夾，將 `idt_client` 資料夾複製到您的 `MyTestSuite_1.0.0/suite/myTestGroup/myTestCase` 資料夾。 若要確認軟體開發套件已成功複製，請執行下列命令。 ``` cd MyTestSuite_1.0.0/suite/myTestGroup/myTestCase python3 -c 'import idt_client' ``` ## 建立測試案例可執行檔 測試案例可執行檔包含您要執行的測試邏輯。測試套件可以包含多個測試案例可執行檔。在本教學課程中，您只會建立一個測試案例可執行檔。 1. 建立測試套件檔案。 在 `MyTestSuite_1.0.0/suite/myTestGroup/myTestCase`資料夾中，建立具有下列內容`myTestCase.py`的檔案： ``` from idt_client import * def main(): # Use the client SDK to communicate with IDT client = Client() if __name__ == "__main__": main() ``` 1. 使用用戶端 SDK 函數將下列測試邏輯新增至您的 `myTestCase.py` 檔案： 1. 在待測裝置上執行 SSH 命令。 ``` from idt_client import * def main(): # Use the client SDK to communicate with IDT client = Client() # Create an execute on device request exec_req = ExecuteOnDeviceRequest(ExecuteOnDeviceCommand("echo 'hello world'")) # Run the command exec_resp = client.execute_on_device(exec_req) # Print the standard output print(exec_resp.stdout) if __name__ == "__main__": main() ``` 1. 將測試結果傳送至 IDT。 ``` from idt_client import * def main(): # Use the client SDK to communicate with IDT client = Client() # Create an execute on device request exec_req = ExecuteOnDeviceRequest(ExecuteOnDeviceCommand("echo 'hello world'")) # Run the command exec_resp = client.execute_on_device(exec_req) # Print the standard output print(exec_resp.stdout) # Create a send result request sr_req = SendResultRequest(TestResult(passed=True)) # Send the result client.send_result(sr_req) if __name__ == "__main__": main() ``` ## 設定 IDT 的裝置資訊 設定您的裝置資訊，讓 IDT 執行測試。您必須使用下列資訊更新位於 `/configs` 資料夾的 `device.json` 範本。 ``` [ { "id": "pool", "sku": "N/A", "devices": [ { "id": "", "connectivity": { "protocol": "ssh", "ip": "", "port": "", "auth": { "method": "pki | password", "credentials": { "user": "", "privKeyPath": "/path/to/private/key", "password": "" } } } } ] } ] ``` 在 `devices` 物件中，提供下列資訊： `id` 您裝置的使用者定義唯一識別符。 `connectivity.ip` 您裝置的 IP 地址。 `connectivity.port` 選用。用於裝置 SSH 連線的連接埠號碼。 `connectivity.auth` 連線的驗證資訊。 只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。 `connectivity.auth.method` 用來透過指定的連線通訊協定存取裝置的驗證方法。 支援的值如下： + `pki` + `password` `connectivity.auth.credentials` 用於驗證的燈入資料。 `connectivity.auth.credentials.user` 用來登入裝置的使用者名稱。 `connectivity.auth.credentials.privKeyPath` 用來登入您裝置之私有金鑰的完整路徑。 只有當 `connectivity.auth.method` 設為 `pki` 時，才會套用此值。 `devices.connectivity.auth.credentials.password` 用於登入您裝置的密碼。 只有當 `connectivity.auth.method` 設為 `password` 時，才會套用此值。 **注意** 如果 `method` 是設定為 `pki`，則指定 `privKeyPath` 如果 `method` 是設定為 `password`，則指定 `password` ## 執行測試套件 建立測試套件之後，您想要確保其如預期般運作。完成下列步驟，以使用您現有的裝置集區執行測試套件。 1. 將您的`MyTestSuite_1.0.0`資料夾複製到 `/tests`。 1. 執行下列命令： ``` cd /bin ./devicetester_[linux | mac | win_x86-64] run-suite --suite-id MyTestSuite ``` IDT 會執行您的測試套件，並將結果串流至主控台。當測試完成執行時，您會看到下列資訊： ``` time="2020-10-19T09:24:47-07:00" level=info msg=Using pool: pool time="2020-10-19T09:24:47-07:00" level=info msg=Using test suite "MyTestSuite_1.0.0" for execution time="2020-10-19T09:24:47-07:00" level=info msg=b'hello world\n' suiteId=MyTestSuite groupId=myTestGroup testCaseId=myTestCase deviceId=my-device executionId=9a52f362-1227-11eb-86c9-8c8590419f30 time="2020-10-19T09:24:47-07:00" level=info msg=All tests finished. executionId=9a52f362-1227-11eb-86c9-8c8590419f30 time="2020-10-19T09:24:48-07:00" level=info msg= ========== Test Summary ========== Execution Time: 1s Tests Completed: 1 Tests Passed: 1 Tests Failed: 0 Tests Skipped: 0 ---------------------------------- Test Groups: myTestGroup: PASSED ---------------------------------- Path to IoT Device Tester Report: /path/to/devicetester/results/9a52f362-1227-11eb-86c9-8c8590419f30/awsiotdevicetester_report.xml Path to Test Execution Logs: /path/to/devicetester/results/9a52f362-1227-11eb-86c9-8c8590419f30/logs Path to Aggregated JUnit Report: /path/to/devicetester/results/9a52f362-1227-11eb-86c9-8c8590419f30/MyTestSuite_Report.xml ``` ## 疑難排解 使用以下資訊來協助解決完成教學課程的任何問題。 **測試案例未成功執行** 如果測試未成功執行，IDT 會將錯誤日誌串流至主控台，以協助您對測試執行進行疑難排解。檢查錯誤日誌之前，請確認下列事項： + IDT 用戶端 SDK 位於正確的資料夾中，如[此步驟](#add-idt-sdk)所述。 + 您符合本教學課程的所有[先決條件](#prereqs-tutorial-custom)。 **無法連線至待測裝置** 請確認下列內容： + 您的 `device.json` 檔案包含正確的 IP 地址、連接埠和身分驗證資訊。 + 您可以從主機電腦透過 SSH 連線至裝置。 # 建立 IDT 測試套件組態檔案 本節說明當您撰寫自訂測試套件時，建立組態檔案的格式。必要的組態檔案 `suite.json` 包含測試套件的相關資訊。請參閱 [設定 suite.json](#suite-json)。 `group.json` 包含測試群組的相關資訊。您必須為測試套件中的每個測試群組建立`group.json`檔案。請參閱 [設定 group.json](#group-json)。 `test.json` 包含測試案例的相關資訊。您必須為測試套件中的每個測試案例建立`test.json`檔案。請參閱 [設定 test.json](#test-json)。選用組態檔案 `test_orchestrator.yaml` 或 `state_machine.json` 定義 IDT 執行測試套件時如何執行測試。SSe [設定 test\$1orchestrator.yaml](#test-orchestrator-config)。 從 IDT v4.5.1 開始，您可以使用 `test_orchestrator.yaml` 檔案來定義測試工作流程。在舊版的 IDT 中，您會使用 `state_machine.json` 檔案。如需狀態機器的相關資訊，請參閱 [設定 IDT 狀態機器](idt-state-machine.md)。 `userdata_schema.json` 定義測試執行器可以包含在其設定組態中的[`userdata.json`檔案](set-custom-idt-config.md#userdata-config-custom)結構描述。此`userdata.json`檔案用於執行測試所需的任何其他組態資訊，但不會出現在`device.json`檔案中。請參閱 [設定 userdata\$1schema.json](#userdata-schema-json)。 組態檔案會放在您的 中``，如下所示。 ``` └── suite ├── suite.json ├── test_orchestrator.yaml ├── userdata_schema.json ├── ├── group.json ├── └── test.json ``` ## 設定 suite.json `suite.json` 檔案會設定環境變數，並判斷是否需要使用者資料才能執行測試套件。使用下列範本來設定您的`/suite/suite.json`檔案： ``` { "id": "_", "title": "", "details": "", "userDataRequired": true | false, "environmentVariables": [ { "key": "", "value": "", }, ... { "key": "", "value": "", } ] } ``` 如下所述，包含值的所有欄位皆為必要： `id` 測試套件的唯一使用者定義 ID。的值`id`必須符合 `suite.json` 檔案所在的測試套件資料夾名稱。套件名稱和套件版本也必須符合下列要求： + `` 不能包含底線。 + `` 表示為 `x.x.x`，其中 `x` 是數字。 ID 會顯示在 IDT 產生的測試報告中。 `title` 此測試套件所測試之產品或功能的使用者定義名稱。名稱會顯示在測試執行器的 IDT CLI 中。 `details` 測試套件用途的簡短描述。 `userDataRequired` 定義測試執行器是否需要在`userdata.json`檔案中包含自訂資訊。如果您將此值設定為 `true`，您還必須在測試套件資料夾中包含 [`userdata_schema.json` 檔案](#userdata-schema-json)。 `environmentVariables` 選用。要為此測試套件設定的環境變數陣列。 `environmentVariables.key` 環境變數的名稱。 `environmentVariables.value` 環境變數的值。 ## 設定 group.json `group.json` 檔案會定義測試群組為必要或選用。使用下列範本來設定您的`/suite//group.json`檔案： ``` { "id": "", "title": "", "details": "", "optional": true | false, } ``` 如下所述，包含值的所有欄位皆為必要： `id` 測試群組的唯一使用者定義 ID。的值`id`必須符合`group.json`檔案所在的測試群組資料夾名稱，且不能包含底線 (`_`)。ID 用於 IDT 產生的測試報告。 `title` 測試群組的描述性名稱。名稱會顯示在測試執行器的 IDT CLI 中。 `details` 測試群組用途的簡短描述。 `optional` 選用。設定為 `true`，在 IDT 完成執行必要的測試後，將此測試群組顯示為選用群組。預設值為 `false`。 ## 設定 test.json `test.json` 檔案會決定測試案例可執行檔和測試案例所使用的環境變數。如需建立測試案例可執行檔的詳細資訊，請參閱 [建立 IDT 測試案例可執行檔](create-test-executables.md)。 使用下列範本來設定您的`/suite///test.json`檔案： ``` { "id": "", "title": "", "details": "", "requireDUT": true | false, "requiredResources": [ { "name": "", "features": [ { "name": "", "version": "", "jobSlots": } ] } ], "execution": { "timeout": , "mac": { "cmd": "/path/to/executable", "args": [ "" ], }, "linux": { "cmd": "/path/to/executable", "args": [ "" ], }, "win": { "cmd": "/path/to/executable", "args": [ "" ] } }, "environmentVariables": [ { "key": "", "value": "", } ] } ``` 如下所述，包含值的所有欄位皆為必要： `id` 測試案例的唯一使用者定義 ID。的值`id`必須符合`test.json`檔案所在的測試案例資料夾名稱，且不能包含底線 (`_`)。ID 用於 IDT 產生的測試報告。。 `title` 測試案例的描述性名稱。名稱會顯示在測試執行器的 IDT CLI 中。 `details` 測試案例用途的簡短描述。 `requireDUT` 選用。`true` 如果需要裝置執行此測試，請將 設定為 ，否則將 設定為 `false`。預設值為 `true`。測試執行器會設定其用來在`device.json`檔案中執行測試的裝置。 `requiredResources` 選用。陣列，提供執行此測試所需的資源裝置相關資訊。 `requiredResources.name` 執行此測試時為資源裝置提供的唯一名稱。 `requiredResources.features` 使用者定義資源裝置功能的陣列。 `requiredResources.features.name` 功能的名稱。您想要使用此裝置的裝置功能。此名稱會與 `resource.json` 檔案中測試執行器所提供的功能名稱相符。 `requiredResources.features.version` 選用。功能的版本。此值會與 `resource.json` 檔案中測試執行器所提供的功能版本相符。如果未提供版本，則不會檢查此功能。如果功能不需要版本號碼，請將此欄位保留空白。 `requiredResources.features.jobSlots` 選用。此功能可支援的同時測試數量。預設值為 `1`。如果您希望 IDT 對個別功能使用不同的裝置，建議您將此值設定為 `1`。 `execution.timeout` IDT 等待測試完成執行的時間量 （以毫秒為單位）。如需設定此值的詳細資訊，請參閱 [建立 IDT 測試案例可執行檔](create-test-executables.md)。 `execution.os` 根據執行 IDT 之主機電腦的作業系統執行的測試案例可執行檔。支援的值為 `linux`、`mac` 和 `win`。 `execution.os.cmd` 您想要在指定作業系統上執行的測試案例可執行檔路徑。此位置必須位於系統路徑中。 `execution.os.args` 選用。要用來執行測試案例可執行檔的引數。 `environmentVariables` 選用。此測試案例設定的環境變數陣列。 `environmentVariables.key` 環境變數的名稱。 `environmentVariables.value` 環境變數的值。 如果您在 `test.json` 檔案和 `suite.json` 檔案中指定相同的環境變數，則`test.json`檔案的值優先。 ## 設定 test\$1orchestrator.yaml 測試協調器是一種控制測試套件執行流程的建構。它決定測試套件的開始狀態、根據使用者定義的規則管理狀態轉換，並繼續轉換這些狀態，直到達到結束狀態為止。 如果您的測試套件不包含使用者定義的測試協調程式，IDT 會為您產生測試協調程式。 預設測試協調器會執行下列函數： + 讓測試執行器能夠選取和執行特定測試群組，而不是整個測試套件。 + 如果未選取特定測試群組， 會以隨機順序在測試套件中執行每個測試群組。 + 產生報告並列印主控台摘要，以顯示每個測試群組和測試案例的測試結果。 如需有關 IDT 測試協調器如何運作的詳細資訊，請參閱 [設定 IDT 測試協調器](idt-test-orchestrator.md)。 ## 設定 userdata\$1schema.json `userdata_schema.json` 檔案會決定測試執行器提供使用者資料的結構描述。如果您的測試套件需要`device.json`檔案中不存在的資訊，則需要使用者資料。例如，您的測試可能需要 Wi-Fi 網路登入資料、特定開放連接埠或使用者必須提供的憑證。此資訊可以做為名為 的輸入參數提供給 IDT，這是使用者在其`/config`資料夾中建立`userdata.json`的檔案`userdata`值。檔案的格式`userdata.json`是根據您在測試套件中包含的 `userdata_schema.json` 檔案。 若要指出測試執行器必須提供`userdata.json`檔案： 1. 在 `suite.json`檔案中，將 `userDataRequired` 設定為 `true`。 1. 在您的 中``，建立 `userdata_schema.json` 檔案。 1. 編輯 `userdata_schema.json` 檔案以建立有效的 [IETF 草稿 v4 JSON 結構描述](https://json-schema.org/specification-links.html#draft-4)。 當 IDT 執行您的測試套件時，其會自動讀取結構描述，並使用它來驗證測試執行器所提供的`userdata.json`檔案。如果有效，`userdata.json`檔案的內容可在 [IDT 內容](idt-context.md)和[測試協調器內容](idt-state-machine.md#state-machine-context)中使用。 # 設定 IDT 測試協調器 從 IDT v4.5.1 開始，IDT 包含新的*測試協調器*元件。測試協調器是一種 IDT 元件，可控制測試套件執行流程，並在 IDT 完成執行所有測試後產生測試報告。測試協調器會根據使用者定義的規則，決定測試選擇和執行測試的順序。 如果您的測試套件不包含使用者定義的測試協調程式，IDT 會為您產生測試協調程式。 預設測試協調器會執行下列函數： + 讓測試執行器能夠選取和執行特定測試群組，而不是整個測試套件。 + 如果未選取特定測試群組， 會以隨機順序在測試套件中執行每個測試群組。 + 產生報告並列印主控台摘要，以顯示每個測試群組和測試案例的測試結果。 測試協調器會取代 IDT 測試協調器。我們強烈建議您使用測試協調器來開發測試套件，而不是 IDT 測試協調器。測試協調器提供下列改進功能： + 相較於 IDT 狀態機器使用的強制性格式， 會使用宣告格式。這可讓您指定要執行哪些測試，以及何時要執行這些測試。 + 管理特定群組處理、報告產生、錯誤處理和結果追蹤，因此您不需要手動管理這些動作。 + 使用 YAML 格式，預設支援註解。 + 需要比測試協調器少 80% 的磁碟空間，才能定義相同的工作流程。 + 新增測試前驗證，以確認您的工作流程定義不包含不正確的測試 IDs或循環相依性。 ## 測試協調器格式 您可以使用下列範本來設定自己的`/suite/test_orchestrator.yaml`檔案： ``` Aliases: string: context-expression ConditionalTests: - Condition: context-expression Tests: - test-descriptor Order: - - group-descriptor - group-descriptor Features: - Name: feature-name Value: support-description Condition: context-expression Tests: - test-descriptor OneOfTests: - test-descriptor IsRequired: boolean ``` 如下所述，包含值的所有欄位皆為必要： `Aliases` 選用。映射到內容表達式的使用者定義字串。別名可讓您產生易記的名稱，以識別測試協調器組態中的內容表達式。如果您要建立複雜內容表達式或您在多個位置使用的表達式，這特別有用。 您可以使用內容表達式來存放內容查詢，讓您從其他 IDT 組態存取資料。如需詳細資訊，請參閱[存取內容中的資料](idt-context.md#accessing-context-data)。 **Example 範例** ``` Aliases: FizzChosen: "'{{$pool.features[?(@.name == 'Fizz')].value[0]}}' == 'yes'" BuzzChosen: "'{{$pool.features[?(@.name == 'Buzz')].value[0]}}' == 'yes'" FizzBuzzChosen: "'{{$aliases.FizzChosen}}' && '{{$aliases.BuzzChosen}}'" ``` `ConditionalTests` 選用。條件清單，以及在滿足每個條件時執行的對應測試案例。每個條件可以有多個測試案例；不過，您可以將指定的測試案例指派給一個條件。 根據預設，IDT 會執行未指派給此清單中條件的任何測試案例。如果您未指定本節，IDT 會在測試套件中執行所有測試群組。 `ConditionalTests` 清單中的每個項目都包含下列參數： `Condition` 評估為布林值的內容表達式。如果評估的值為 true，IDT 會執行 `Tests` 參數中指定的測試案例。 `Tests` 測試描述項的清單。 每個測試描述項都使用測試群組 ID 和一或多個測試案例 IDs，來識別要從特定測試群組執行的個別測試。測試描述項使用下列格式： ``` GroupId: group-id CaseIds: [test-id, test-id] # optional ``` **Example 範例** 下列範例使用您可以定義為 的一般內容表達式`Aliases`。 ``` ConditionalTests: - Condition: "{{$aliases.Condition1}}" Tests: - GroupId: A - GroupId: B - Condition: "{{$aliases.Condition2}}" Tests: - GroupId: D - Condition: "{{$aliases.Condition1}} || {{$aliases.Condition2}}" Tests: - GroupId: C ``` 根據定義的條件，IDT 會選取測試群組，如下所示： + 如果 `Condition1` 為 true，IDT 會在測試群組 A、B 和 C 中執行測試。 + 如果 `Condition2` 為 true，IDT 會在測試群組 C 和 D 中執行測試。 `Order` 選用。執行測試的順序。您可以在測試群組層級指定測試順序。如果您未指定本節，IDT 會以隨機順序執行所有適用的測試群組。的值`Order`是群組描述項清單的清單。您在 中未列出的任何測試群組`Order`，都可以與任何其他列出的測試群組平行執行。 每個群組描述項清單都包含多個群組描述項的其中一個，並識別執行每個描述項中指定群組的順序。您可以使用下列格式來定義個別群組描述項： + `group-id`- 現有測試群組的群組 ID。 + `[group-id, group-id]`- 可以相對於彼此以任何順序執行的測試群組清單。 + `"*"`—Wildcard。這相當於目前群組描述項清單中尚未指定的所有測試群組清單。 的 值`Order`也必須符合下列要求： + 您在群組描述項中指定的測試群組 IDs，必須存在於您的測試套件中。 + 每個群組描述項清單必須至少包含一個測試群組。 + 每個群組描述項清單必須包含唯一的群組 IDs。您無法在個別群組描述項中重複測試群組 ID。 + 群組描述項清單最多可以有一個萬用字元群組描述項。萬用字元群組描述項必須是清單中的第一個或最後一個項目。 **Example 範例** 對於包含測試群組 A、B、C、D 和 E 的測試套件，以下範例清單顯示指定 IDT 應先執行測試群組 A、接著執行測試群組 B，然後以任何順序執行測試群組 C、D 和 E 的不同方式。 + ``` Order: - - A - B - [C, D, E] ``` + ``` Order: - - A - B - "*" ``` + ``` Order: - - A - B - - B - C - - B - D - - B - E ``` `Features` 選用。您希望 IDT 新增至 `awsiotdevicetester_report.xml` 檔案的產品功能清單。如果您未指定此區段，IDT 不會將任何產品功能新增至報告。 產品功能是有關裝置可能符合的特定條件的使用者定義資訊。例如，MQTT 產品功能可以指定裝置正確發佈 MQTT 訊息。在 中`awsiotdevicetester_report.xml`，產品功能會根據是否通過指定的測試，設定為 `supported`、 `not-supported`或自訂使用者定義值。 `Features` 清單中的每個項目都包含下列參數： `Name` 功能的名稱。 `Value` 選用。您想要在報告中使用的自訂值，而不是 `supported`。如果未指定此值，則根據 IDT `not-supported`會根據測試結果，將功能值設定為 `supported`或 。如果您使用不同的條件來測試相同的功能，您可以針對`Features`清單中該功能的每個執行個體使用自訂值，IDT 會串連支援條件的功能值。如需詳細資訊，請參閱 `Condition` 評估為布林值的內容表達式。如果評估的值為 true，IDT 會在測試報告完成執行測試套件後，將功能新增至測試報告。如果評估的值為 false，則測試不會包含在報告中。 `Tests` 選用。測試描述項的清單。此清單中指定的所有測試都必須通過，才能支援此功能。 此清單中的每個測試描述項都使用測試群組 ID 和一或多個測試案例 IDs，來識別要從特定測試群組執行的個別測試。測試描述項使用下列格式： ``` GroupId: group-id CaseIds: [test-id, test-id] # optional ``` 您必須`OneOfTests`為`Features`清單中的每個功能指定 `Tests`或 。 `OneOfTests` 選用。測試描述項的清單。此清單中指定的至少一個測試必須通過，才能支援此功能。 此清單中的每個測試描述項都使用測試群組 ID 和一或多個測試案例 IDs，來識別要從特定測試群組執行的個別測試。測試描述項使用下列格式： ``` GroupId: group-id CaseIds: [test-id, test-id] # optional ``` 您必須`OneOfTests`為`Features`清單中的每個功能指定 `Tests`或 。 `IsRequired` 布林值，定義測試報告中是否需要此功能。預設值為 `false`。 **Example** ## 測試協調器內容 測試協調程式內容是唯讀 JSON 文件，其中包含在執行期間可供測試協調器使用的資料。測試協調器內容只能從測試協調器存取，並包含決定測試流程的資訊。例如，您可以使用 `userdata.json` 檔案中測試執行器設定的資訊來判斷是否需要執行特定測試。 測試協調器內容使用下列格式： ``` { "pool": { }, "userData": { }, "config": { } } ``` `pool` 為測試執行選取的裝置集區資訊。對於選取的裝置集區，此資訊會從`device.json`檔案中定義的對應頂層裝置集區陣列元素擷取。 `userData` `userdata.json` 檔案中的資訊。 `config` `config.json` 檔案中的資訊。 您可以使用 JSONPath 表示法查詢內容。狀態定義中 JSONPath 查詢的語法為 `{{query}}`。當您從測試協調器內容存取資料時，請確定每個值評估為字串、數字或布林值。 如需使用 JSONPath 表示法從內容存取資料的詳細資訊，請參閱 [使用 IDT 內容](idt-context.md)。 # 設定 IDT 狀態機器 **重要** 從 IDT v4.5.1 開始，此狀態機器已棄用。我們強烈建議您使用新的測試協調器。如需詳細資訊，請參閱[設定 IDT 測試協調器](idt-test-orchestrator.md)。 狀態機器是一種控制測試套件執行流程的建構。它決定測試套件的開始狀態、根據使用者定義的規則管理狀態轉換，並繼續轉換這些狀態，直到達到結束狀態為止。 如果您的測試套件不包含使用者定義的狀態機器，IDT 會為您產生狀態機器。預設狀態機器會執行下列函數： + 讓測試執行器能夠選取和執行特定測試群組，而不是整個測試套件。 + 如果未選取特定測試群組， 會以隨機順序執行測試套件中的每個測試群組。 + 產生報告並列印主控台摘要，顯示每個測試群組和測試案例的測試結果。 IDT 測試套件的狀態機器必須符合下列條件： + 每個狀態對應於 IDT 要採取的動作，例如執行測試群組或製作報告檔案的產品。 + 轉換為 狀態會執行與 狀態相關聯的動作。 + 每個狀態都會定義下一個狀態的轉換規則。 + 結束狀態必須為 `Succeed`或 `Fail`。 ## 狀態機器格式 您可以使用下列範本來設定自己的`/suite/state_machine.json`檔案： ``` { "Comment": "", "StartAt": "", "States": { "": { "Type": "", // Additional state configuration } // Required states "Succeed": { "Type": "Succeed" }, "Fail": { "Type": "Fail" } } } ``` 如下所述，包含值的所有欄位皆為必要： `Comment` 狀態機器的描述。 `StartAt` IDT 開始執行測試套件的狀態名稱。的值`StartAt`必須設定為 `States` 物件中列出的其中一個狀態。 `States` 將使用者定義狀態名稱映射至有效 IDT 狀態的物件。每個 States.*state-name* 物件都包含映射至 *state-name* 的有效狀態定義。 `States` 物件必須包含 `Succeed`和 `Fail` 狀態。如需有效狀態的資訊，請參閱 [有效狀態和狀態定義](#valid-states)。 ## 有效狀態和狀態定義 本節說明可在 IDT 狀態機器中使用的所有有效狀態的狀態定義。下列某些狀態支援測試案例層級的組態。不過，建議您在測試群組層級設定狀態轉換規則，而非測試案例層級，除非絕對必要。 **Topics** + [RunTask](#state-runtask) + [Choice](#state-choice) + [平行](#state-parallel) + [AddProductFeatures](#state-addproductfeatures) + [報告](#state-report) + [LogMessage](#state-logmessage) + [SelectGroup](#state-selectgroup) + [失敗](#state-fail) + [Succeed](#state-succeed) ### RunTask `RunTask` 狀態會從測試套件中定義的測試群組執行測試案例。 ``` { "Type": "RunTask", "Next": "", "TestGroup": "", "TestCases": [ "" ], "ResultVar": "" } ``` 如下所述，包含值的所有欄位皆為必要： `Next` 在目前狀態下執行動作後，要轉換為的狀態名稱。 `TestGroup` 選用。要執行的測試群組 ID。如果未指定此值，IDT 會執行測試執行器選取的測試群組。 `TestCases` 選用。來自 中指定群組的測試案例 IDs 陣列`TestGroup`。根據 `TestGroup`和 的值`TestCases`，IDT 會決定測試執行行為，如下所示： + 同時指定 `TestCases` `TestGroup`和 時，IDT 會從測試群組執行指定的測試案例。 + `TestCases` 指定`TestGroup`但未指定 時，IDT 會執行指定的測試案例。 + 指定 `TestCases` 但未指定 `TestGroup` 時，IDT 會執行指定測試群組中的所有測試案例。 + 未指定 `TestCases` `TestGroup`或 時，IDT 會從測試執行器從 IDT CLI 中選取的測試群組執行所有測試案例。若要啟用測試執行器的群組選擇，您必須在 `state_machine.json` 檔案中同時包含 `RunTask`和 `Choice` 狀態。如需如何運作的範例，請參閱[範例狀態機器：執行使用者選取的測試群組](#allow-specific-groups)。 如需為測試執行器啟用 IDT CLI 命令的詳細資訊，請參閱 [啟用 IDT CLI 命令](create-test-executables.md#idt-cli-coop)。 `ResultVar` 使用測試執行結果設定的內容變數名稱。如果您未指定 的值，請勿指定此值`TestGroup`。IDT `false`會根據下列項目，將您在 中定義的變數值設定為 `ResultVar``true`或 ： + 如果變數名稱的格式為 `text_text_passed`，則值會設定為是否通過或略過第一個測試群組中的所有測試。 + 在所有其他情況下，該值會設定為是否通過或略過所有測試群組中的所有測試。 一般而言，您將使用 `RunTask` 狀態來指定測試群組 ID，而不指定個別測試案例 IDs，以便 IDT 執行指定測試群組中的所有測試案例。此狀態執行的所有測試案例都會以隨機順序平行執行。不過，如果所有測試案例都需要裝置才能執行，而且只有單一裝置可用，則測試案例將改為依序執行。 **錯誤處理** 如果任何指定的測試群組或測試案例 IDs 無效，則此狀態會發出`RunTaskError`執行錯誤。如果狀態遇到執行錯誤，則也會將狀態機器內容中的`hasExecutionError`變數設定為 `true`。 ### Choice `Choice` 狀態可讓您動態設定下一個狀態，以根據使用者定義的條件轉換為 。 ``` { "Type": "Choice", "Default": "", "FallthroughOnError": true | false, "Choices": [ { "Expression": "", "Next": "" } ] } ``` 如下所述，包含值的所有欄位皆為必要： `Default` 如果 中定義的任何表達式`Choices`都無法評估為 ，則要轉換為的預設狀態`true`。 `FallthroughOnError` 選用。指定狀態在評估表達式時發生錯誤時的行為。`true` 如果您想要在評估導致錯誤時略過表達式，請將 設定為 。如果沒有相符的表達式，則狀態機器會轉換為 `Default` 狀態。如果未指定`FallthroughOnError`值，則預設為 `false`。 `Choices` 運算式和狀態的陣列，用於判斷在目前狀態下執行動作後要轉換到哪個狀態。 `Choices.Expression` 評估為布林值的表達式字串。如果表達式評估為 `true`，則狀態機器會轉換為 中定義的狀態`Choices.Next`。表達式字串會從狀態機器內容擷取值，然後對其執行操作以到達布林值。如需存取狀態機器內容的資訊，請參閱 [狀態機器內容](#state-machine-context)。 `Choices.Next` 如果 中定義的表達式`Choices.Expression`評估為 ，則要轉換為的狀態名稱`true`。 **錯誤處理** 在下列情況下， `Choice` 狀態可能需要錯誤處理： + 選擇表達式中的某些變數不存在於狀態機器內容中。 + 表達式的結果不是布林值。 + JSON 查詢的結果不是字串、數字或布林值。 您無法使用`Catch`區塊來處理此狀態的錯誤。如果您想要在遇到錯誤時停止執行狀態機器，您必須將 `FallthroughOnError`設定為 `false`。不過，我們建議您將 `FallthroughOnError`設定為 `true`，並根據您的使用案例執行下列其中一項操作： + 如果您存取的變數預期在某些情況下不存在，請使用 值`Default`和其他`Choices`區塊來指定下一個狀態。 + 如果您存取的變數應一律存在，請將`Default`狀態設定為 `Fail`。 ### 平行 `Parallel` 狀態可讓您彼此平行定義和執行新的狀態機器。 ``` { "Type": "Parallel", "Next": "", "Branches": [ ] } ``` 如下所述，包含值的所有欄位皆為必要： `Next` 在目前狀態下執行動作後，要轉換為的狀態名稱。 `Branches` 要執行的狀態機器定義陣列。每個狀態機器定義都必須包含自己的 `StartAt`、 `Succeed`和 `Fail` 狀態。此陣列中的狀態機器定義無法參考其定義以外的狀態。 由於每個分支狀態機器共用相同的狀態機器內容，因此在一個分支中設定變數，然後從另一個分支讀取這些變數可能會導致意外行為。 `Parallel` 狀態只有在執行所有分支狀態機器之後才會移至下一個狀態。需要裝置的每個狀態都會等待執行，直到裝置可用為止。如果有多個裝置可用，此狀態會從多個群組平行執行測試案例。如果沒有足夠的裝置可用，則測試案例將依序執行。由於測試案例在平行執行時以隨機順序執行，因此可能會使用不同的裝置從相同的測試群組執行測試。 **錯誤處理** 請確定分支狀態機器和父系狀態機器都會轉換為 `Fail` 狀態，以處理執行錯誤。 由於分支狀態機器不會將執行錯誤傳輸至父系狀態機器，因此您無法使用`Catch`區塊來處理分支狀態機器中的執行錯誤。反之，請在共用狀態機器內容中使用 `hasExecutionErrors`值。如需如何運作的範例，請參閱 [狀態機器範例：平行執行兩個測試群組](#run-in-parallel)。 ### AddProductFeatures `AddProductFeatures` 狀態可讓您將產品功能新增至 IDT 產生的`awsiotdevicetester_report.xml`檔案。 產品功能是有關裝置可能符合的特定條件的使用者定義資訊。例如，`MQTT`產品功能可以指定裝置正確發佈 MQTT 訊息。在報告中，產品功能會根據是否通過指定的測試，設定為 `supported`、 `not-supported`或自訂值。 **注意** `AddProductFeatures` 狀態本身不會產生報告。此狀態必須轉換為 [`Report` 狀態](#state-report)才能產生報告。 ``` { "Type": "Parallel", "Next": "", "Features": [ { "Feature": "", "Groups": [ "" ], "OneOfGroups": [ "" ], "TestCases": [ "" ], "IsRequired": true | false, "ExecutionMethods": [ "" ] } ] } ``` 如下所述，包含值的所有欄位皆為必要： `Next` 在目前狀態下執行動作後，要轉換為的狀態名稱。 `Features` 要在 `awsiotdevicetester_report.xml` 檔案中顯示的產品功能陣列。 `Feature` 功能的名稱 `FeatureValue` 選用。要在報告中使用的自訂值，而非 `supported`。如果未指定此值，則根據測試結果，功能值會設為 `supported`或 `not-supported`。 如果您使用 的自訂值`FeatureValue`，則可以使用不同的條件測試相同的功能，IDT 會串連支援條件的功能值。例如，以下摘錄顯示具有兩個不同`MyFeature`特徵值的功能： ``` ... { "Feature": "MyFeature", "FeatureValue": "first-feature-supported", "Groups": ["first-feature-group"] }, { "Feature": "MyFeature", "FeatureValue": "second-feature-supported", "Groups": ["second-feature-group"] }, ... ``` 如果兩個測試群組都通過，則功能值會設為 `first-feature-supported, second-feature-supported`。 `Groups` 選用。測試群組 IDs的陣列。每個指定測試群組中的所有測試都必須通過，才能支援此功能。 `OneOfGroups` 選用。測試群組 IDs的陣列。至少一個指定測試群組內的所有測試都必須通過，才能支援此功能。 `TestCases` 選用。測試案例 IDs的陣列。如果您指定此值，則適用下列條件： + 所有指定的測試案例都必須通過，才能支援此功能。 + `Groups` 只能包含一個測試群組 ID。 + `OneOfGroups` 不得指定。 `IsRequired` 選用。設定為 `false` 以在報告中將此功能標記為選用功能。預設值為 `true`。 `ExecutionMethods` 選用。符合 `device.json` 檔案中指定`protocol`值的執行方法陣列。如果指定此值，則測試執行器必須指定`protocol`符合此陣列中其中一個值的值，以在報告中包含 功能。如果未指定此值，則功能一律會包含在報告中。 若要使用 `AddProductFeatures` 狀態，您必須將 `RunTask` 狀態`ResultVar`中的 值設定為下列其中一個值： + 如果您指定個別測試案例 IDs，請將 `ResultVar`設定為 `group-id_test-id_passed`。 + 如果您未指定個別測試案例 IDs，請將 `ResultVar`設定為 `group-id_passed`。 `AddProductFeatures` 狀態會以下列方式檢查測試結果： + 如果您未指定任何測試案例 IDs，則每個測試群組的結果取決於狀態機器內容中的 `group-id_passed`變數值。 + 如果您確實指定測試案例 IDs，則每個測試的結果取決於狀態機器內容中的 `group-id_test-id_passed`變數值。 **錯誤處理** 如果在此狀態下提供的群組 ID 不是有效的群組 ID，則此狀態會導致`AddProductFeaturesError`執行錯誤。如果狀態遇到執行錯誤，則也會將狀態機器內容中的`hasExecutionErrors`變數設定為 `true`。 ### 報告 `Report` 狀態會產生 `suite-name_Report.xml`和 `awsiotdevicetester_report.xml` 檔案。此狀態也會將報告串流至 主控台。 ``` { "Type": "Report", "Next": "" } ``` 如下所述，包含值的所有欄位皆為必要： `Next` 在目前狀態下執行動作後，要轉換為的狀態名稱。 您應該一律在測試執行流程結束時轉換為 `Report` 狀態，以便測試執行器可以檢視測試結果。一般而言，此狀態之後的下一個狀態為 `Succeed`。 **錯誤處理** 如果此狀態在產生報告時遇到問題，則會發出`ReportError`執行錯誤。 ### LogMessage `LogMessage` 狀態會產生 `test_manager.log` 檔案，並將日誌訊息串流至 主控台。 ``` { "Type": "LogMessage", "Next": "" "Level": "info | warn | error" "Message": "" } ``` 如下所述，包含值的所有欄位皆為必要： `Next` 在目前狀態下執行動作後，要轉換為的狀態名稱。 `Level` 建立日誌訊息的錯誤層級。如果您指定的關卡無效，此狀態會產生錯誤訊息並予以捨棄。 `Message` 要記錄的訊息。 ### SelectGroup `SelectGroup` 狀態會更新狀態機器內容，以指出已選取哪些群組。此狀態設定的值會由任何後續`Choice`狀態使用。 ``` { "Type": "SelectGroup", "Next": "" "TestGroups": [ " ] } ``` 如下所述，包含值的所有欄位皆為必要： `Next` 在目前狀態下執行動作後，要轉換為的狀態名稱。 `TestGroups` 將標記為選取的測試群組陣列。對於此陣列中的每個測試群組 ID，`group-id_selected`變數會在內容`true`中設定為 。請務必提供有效的測試群組 IDs因為 IDT 不會驗證指定的群組是否存在。 ### 失敗 `Fail` 狀態表示狀態機器未正確執行。這是狀態機器的結束狀態，每個狀態機器定義都必須包含此狀態。 ``` { "Type": "Fail" } ``` ### Succeed `Succeed` 狀態表示狀態機器已正確執行。這是狀態機器的結束狀態，每個狀態機器定義都必須包含此狀態。 ``` { "Type": "Succeed" } ``` ## 狀態機器內容 狀態機器內容是唯讀 JSON 文件，其中包含可在執行期間提供給狀態機器的資料。狀態機器內容只能從狀態機器存取，並包含決定測試流程的資訊。例如，您可以使用 `userdata.json` 檔案中測試執行器設定的資訊來判斷是否需要執行特定測試。 狀態機器內容使用下列格式： ``` { "pool": { }, "userData": { }, "config": { }, "suiteFailed": true | false, "specificTestGroups": [ "" ], "specificTestCases": [ "" ], "hasExecutionErrors": true } ``` `pool` 為測試執行選取之裝置集區的相關資訊。對於選取的裝置集區，此資訊會從 `device.json`檔案中定義的對應頂層裝置集區陣列元素擷取。 `userData` `userdata.json` 檔案中的資訊。 `config` 資訊鎖定`config.json`檔案。 `suiteFailed` 狀態機器啟動`false`時，此值會設為 。如果測試群組在 `RunTask` 狀態失敗，則此值會在狀態機器執行的剩餘持續時間內設定為 `true` 。 `specificTestGroups` 如果測試執行器選取要執行的特定測試群組，而不是整個測試套件，則會建立此金鑰並包含特定測試群組 IDs的清單。 `specificTestCases` 如果測試執行器選取要執行的特定測試案例，而不是整個測試套件，則會建立此金鑰並包含特定測試案例 IDs的清單。 `hasExecutionErrors` 狀態機器啟動時不會結束。如果任何狀態遇到執行錯誤，則會建立此變數`true`，並在狀態機器執行的剩餘持續時間內設定為 。 您可以使用 JSONPath 表示法查詢內容。狀態定義中 JSONPath 查詢的語法為 `{{$.query}}`。您可以在某些狀態下使用 JSONPath 查詢做為預留位置字串。IDT 會將預留位置字串取代為內容中評估 JSONPath 查詢的值。您可以針對下列值使用預留位置： + 狀態`TestCases`的值`RunTask`。 + `Expression` 值`Choice`狀態。 當您從狀態機器內容存取資料時，請確定符合下列條件： + 您的 JSON 路徑必須以 開頭 `$.` + 每個值都必須評估為字串、數字或布林值。 如需使用 JSONPath 表示法從內容存取資料的詳細資訊，請參閱 [使用 IDT 內容](idt-context.md)。 ## 執行錯誤 執行錯誤是狀態機器在執行狀態時遇到的狀態機器定義錯誤。IDT 會記錄`test_manager.log`檔案中每個錯誤的相關資訊，並將日誌訊息串流至主控台。 您可以使用下列方法來處理執行錯誤： + 在狀態定義中新增[`Catch`區塊](#catch)。 + 在狀態機器內容中檢查[`hasExecutionErrors`值](#context)的值。 ### 擷取 若要使用 `Catch`，請將下列項目新增至您的狀態定義： ``` "Catch": [ { "ErrorEquals": [ "" ] "Next": "" } ] ``` 如下所述，包含值的所有欄位皆為必要： `Catch.ErrorEquals` 要擷取的錯誤類型陣列。如果執行錯誤符合其中一個指定的值，則狀態機器會轉換為 中指定的狀態`Catch.Next`。如需其產生的錯誤類型的相關資訊，請參閱每個狀態定義。 `Catch.Next` 如果目前狀態遇到符合 中指定其中一個值的執行錯誤，則會轉換為下一個狀態`Catch.ErrorEquals`。 擷取區塊會依序處理，直到一個相符為止。如果沒有錯誤符合 Catch 區塊中列出的錯誤，則狀態機器會繼續執行。由於執行錯誤是不正確狀態定義的結果，我們建議您在狀態遇到執行錯誤時轉換為失敗狀態。 ### hasExecutionError 當某些狀態遇到執行錯誤時，除了發出錯誤之外，也會在狀態機器內容`true`中將 `hasExecutionError` 值設定為 。您可以使用此值來偵測何時發生錯誤，然後使用 `Choice` 狀態將狀態機器轉換為 `Fail` 狀態。 此方法具有下列特性。 + 狀態機器不會以指派給 的任何值開始`hasExecutionError`，且此值在特定狀態設定之前無法使用。這表示您必須`false`針對存取此值`Choice`的狀態，明確`FallthroughOnError`將 設定為 ，以防止狀態機器在未發生執行錯誤時停止。 + 一旦設定為 `true`， `hasExecutionError` 永遠不會設定為 false 或從內容中移除。這表示此值只有在第一次設定為 時才有用`true`，而且對於所有後續狀態，它不提供有意義的值。 + 該`hasExecutionError`值會與 `Parallel` 狀態的所有分支狀態機器共用，這可能會導致非預期的結果，具體取決於存取它的順序。 由於這些特性，如果您可以改用 Catch 區塊，我們不建議您使用此方法。 ## 狀態機器範例 本節提供一些範例狀態機器組態。 **Topics** + [狀態機器範例：執行單一測試群組](#single-test-group) + [狀態機器範例：執行使用者選取的測試群組](#allow-specific-groups) + [狀態機器範例：使用產品功能執行單一測試群組](#run-with-product-features) + [狀態機器範例：平行執行兩個測試群組](#run-in-parallel) ### 狀態機器範例：執行單一測試群組 此狀態機器： + 執行 ID 為 的測試群組`GroupA`，其必須存在於 `group.json` 檔案的 套件中。 + 檢查執行錯誤，並在發現任何 `Fail` 時轉換為 。 + `Succeed` 如果沒有錯誤，則產生報告並轉換為 ，`Fail`否則。 ``` { "Comment": "Runs a single group and then generates a report.", "StartAt": "RunGroupA", "States": { "RunGroupA": { "Type": "RunTask", "Next": "Report", "TestGroup": "GroupA", "Catch": [ { "ErrorEquals": [ "RunTaskError" ], "Next": "Fail" } ] }, "Report": { "Type": "Report", "Next": "Succeed", "Catch": [ { "ErrorEquals": [ "ReportError" ], "Next": "Fail" } ] }, "Succeed": { "Type": "Succeed" }, "Fail": { "Type": "Fail" } } } ``` ### 狀態機器範例：執行使用者選取的測試群組 此狀態機器： + 檢查測試執行器是否已選取特定測試群組。狀態機器不會檢查特定測試案例，因為測試執行器無法在未同時選取測試群組的情況下選取測試案例。 + 如果選取測試群組： + 在選取的測試群組中執行測試案例。若要這樣做，狀態機器不會明確指定 `RunTask` 狀態中的任何測試群組或測試案例。 + 執行所有測試並結束之後產生報告。 + 如果未選取測試群組： + 在測試群組 中執行測試`GroupA`。 + 產生報告並結束。 ``` { "Comment": "Runs specific groups if the test runner chose to do that, otherwise runs GroupA.", "StartAt": "SpecificGroupsCheck", "States": { "SpecificGroupsCheck": { "Type": "Choice", "Default": "RunGroupA", "FallthroughOnError": true, "Choices": [ { "Expression": "{{$.specificTestGroups[0]}} != ''", "Next": "RunSpecificGroups" } ] }, "RunSpecificGroups": { "Type": "RunTask", "Next": "Report", "Catch": [ { "ErrorEquals": [ "RunTaskError" ], "Next": "Fail" } ] }, "RunGroupA": { "Type": "RunTask", "Next": "Report", "TestGroup": "GroupA", "Catch": [ { "ErrorEquals": [ "RunTaskError" ], "Next": "Fail" } ] }, "Report": { "Type": "Report", "Next": "Succeed", "Catch": [ { "ErrorEquals": [ "ReportError" ], "Next": "Fail" } ] }, "Succeed": { "Type": "Succeed" }, "Fail": { "Type": "Fail" } } } ``` ### 狀態機器範例：使用產品功能執行單一測試群組 此狀態機器： + 執行測試群組 `GroupA`。 + 檢查執行錯誤，並在發現任何 `Fail` 時轉換為 。 + 將 `FeatureThatDependsOnGroupA`功能新增至 `awsiotdevicetester_report.xml` 檔案： + 如果`GroupA`通過，則功能會設定為 `supported`。 + 該功能在報告中不會標記為選用。 + `Succeed` 如果沒有錯誤，則產生報告並轉換為 ，`Fail`否則 ``` { "Comment": "Runs GroupA and adds product features based on GroupA", "StartAt": "RunGroupA", "States": { "RunGroupA": { "Type": "RunTask", "Next": "AddProductFeatures", "TestGroup": "GroupA", "ResultVar": "GroupA_passed", "Catch": [ { "ErrorEquals": [ "RunTaskError" ], "Next": "Fail" } ] }, "AddProductFeatures": { "Type": "AddProductFeatures", "Next": "Report", "Features": [ { "Feature": "FeatureThatDependsOnGroupA", "Groups": [ "GroupA" ], "IsRequired": true } ] }, "Report": { "Type": "Report", "Next": "Succeed", "Catch": [ { "ErrorEquals": [ "ReportError" ], "Next": "Fail" } ] }, "Succeed": { "Type": "Succeed" }, "Fail": { "Type": "Fail" } } } ``` ### 狀態機器範例：平行執行兩個測試群組 此狀態機器： + 平行執行 `GroupA`和 `GroupB` 測試群組。分支狀態機器中`RunTask`狀態存放在內容中的`ResultVar`變數可供 `AddProductFeatures` 狀態使用。 + 檢查執行錯誤，並在發現任何 `Fail` 時轉換為 。此狀態機器不會使用`Catch`區塊，因為該方法不會偵測分支狀態機器中的執行錯誤。 + 根據傳遞的群組，將功能新增至 `awsiotdevicetester_report.xml` 檔案 + 如果`GroupA`通過，則功能會設定為 `supported`。 + 該功能在報告中不會標記為選用。 + `Succeed` 如果沒有錯誤，則產生報告並轉換為 ，`Fail`否則 如果在裝置集區中設定了兩個裝置，則 `GroupA`和 `GroupB` 可以同時執行。不過，如果 `GroupA`或 有`GroupB`多個測試，則兩個裝置可能會配置到這些測試。如果只設定一個裝置，測試群組將依序執行。 ``` { "Comment": "Runs GroupA and GroupB in parallel", "StartAt": "RunGroupAAndB", "States": { "RunGroupAAndB": { "Type": "Parallel", "Next": "CheckForErrors", "Branches": [ { "Comment": "Run GroupA state machine", "StartAt": "RunGroupA", "States": { "RunGroupA": { "Type": "RunTask", "Next": "Succeed", "TestGroup": "GroupA", "ResultVar": "GroupA_passed", "Catch": [ { "ErrorEquals": [ "RunTaskError" ], "Next": "Fail" } ] }, "Succeed": { "Type": "Succeed" }, "Fail": { "Type": "Fail" } } }, { "Comment": "Run GroupB state machine", "StartAt": "RunGroupB", "States": { "RunGroupA": { "Type": "RunTask", "Next": "Succeed", "TestGroup": "GroupB", "ResultVar": "GroupB_passed", "Catch": [ { "ErrorEquals": [ "RunTaskError" ], "Next": "Fail" } ] }, "Succeed": { "Type": "Succeed" }, "Fail": { "Type": "Fail" } } } ] }, "CheckForErrors": { "Type": "Choice", "Default": "AddProductFeatures", "FallthroughOnError": true, "Choices": [ { "Expression": "{{$.hasExecutionErrors}} == true", "Next": "Fail" } ] }, "AddProductFeatures": { "Type": "AddProductFeatures", "Next": "Report", "Features": [ { "Feature": "FeatureThatDependsOnGroupA", "Groups": [ "GroupA" ], "IsRequired": true }, { "Feature": "FeatureThatDependsOnGroupB", "Groups": [ "GroupB" ], "IsRequired": true } ] }, "Report": { "Type": "Report", "Next": "Succeed", "Catch": [ { "ErrorEquals": [ "ReportError" ], "Next": "Fail" } ] }, "Succeed": { "Type": "Succeed" }, "Fail": { "Type": "Fail" } } } ``` # 建立 IDT 測試案例可執行檔 您可以透過下列方式，在測試套件資料夾中建立和放置測試案例可執行檔： + 對於使用 `test.json` 檔案中的引數或環境變數來判斷要執行哪些測試的測試套件，您可以建立整個測試套件的單一測試案例可執行檔，或測試套件中每個測試群組的測試可執行檔。 + 對於您想要根據指定命令執行特定測試的測試套件，您可以在測試套件中為每個測試案例建立一個可執行的測試案例。 身為測試寫入器，您可以判斷哪種方法適合您的使用案例，並據以建構您的測試案例可執行檔。請確定您在每個`test.json`檔案中提供正確的測試案例可執行路徑，且指定的可執行檔正確執行。 當所有裝置準備好執行測試案例時，IDT 會讀取下列檔案： + 所選測試案例`test.json`的 會決定要啟動的程序，以及要設定的環境變數。 + 測試套件`suite.json`的 決定要設定的環境變數。 IDT 會根據 `test.json` 檔案中指定的命令和引數啟動必要的測試可執行程序，並將所需的環境變數傳遞給程序。 ## 使用 IDT 用戶端 SDK IDT 用戶端SDKs可讓您使用 API 命令，簡化在測試可執行檔中編寫測試邏輯的方式，您可以使用該命令與 IDT 和受測裝置互動。IDT 目前提供下列 SDKs： + 適用於 Python 的 IDT 用戶端 SDK + IDT Client SDK for Go + 適用於 Java 的 IDT 用戶端 SDK 這些 SDKs位於 `/sdks` 資料夾中。建立新的測試案例可執行檔時，您必須將要使用的 SDK 複製到包含測試案例可執行檔的資料夾，並在程式碼中參考 SDK。本節提供可在測試案例可執行檔中使用的可用 API 命令的簡短描述。 **Topics** + [裝置互動](#api-device-interaction) + [IDT 互動](#api-idt-interaction) + [主機互動](#api-host-interaction) ### 裝置互動 下列命令可讓您與受測裝置通訊，而不必實作任何其他裝置互動和連線管理功能。 `ExecuteOnDevice` 允許測試套件在支援 SSH 或 Docker shell 連線的裝置上執行 Shell 命令。 `CopyToDevice` 允許測試套件將本機檔案從執行 IDT 的主機機器複製到支援 SSH 或 Docker shell 連線之裝置上的指定位置。 `ReadFromDevice` 允許測試套件從支援 UART 連線的裝置序列連接埠讀取。 **注意** 由於 IDT 不會管理使用內容中的裝置存取資訊所建立之裝置的直接連線，我們建議您在測試案例可執行檔中使用這些裝置互動 API 命令。不過，如果這些命令不符合您的測試案例要求，則您可以從 IDT 內容擷取裝置存取資訊，並使用它從測試套件直接連線至裝置。 若要進行直接連線，請分別擷取 中的資訊，`device.connectivity`以及受測裝置和資源裝置`resource.devices.connectivity`的欄位。如需使用 IDT 內容的詳細資訊，請參閱 [使用 IDT 內容](idt-context.md)。 ### IDT 互動 下列命令可讓您的測試套件與 IDT 通訊。 `PollForNotifications` 允許測試套件檢查來自 IDT 的通知。 `GetContextValue ` 和 `GetContextString` 允許測試套件從 IDT 內容擷取值。如需詳細資訊，請參閱[使用 IDT 內容](idt-context.md)。 `SendResult` 允許測試套件向 IDT 報告測試案例結果。此命令必須在測試套件中每個測試案例的結尾呼叫。 ### 主機互動 下列命令可讓您的測試套件與主機機器通訊。 `PollForNotifications` 允許測試套件檢查來自 IDT 的通知。 `GetContextValue ` 和 `GetContextString` 允許測試套件從 IDT 內容擷取值。如需詳細資訊，請參閱[使用 IDT 內容](idt-context.md)。 `ExecuteOnHost` 允許測試套件在本機機器上執行命令，並讓 IDT 管理測試案例可執行生命週期。 ## 啟用 IDT CLI 命令 `run-suite` 命令 IDT CLI 提供多種選項，可讓測試執行器自訂測試執行。若要允許測試執行器使用這些選項來執行自訂測試套件，請實作對 IDT CLI 的支援。如果您未實作支援，測試執行器仍然可以執行測試，但某些 CLI 選項將無法正常運作。為了提供理想的客戶體驗，建議您在 IDT CLI 中為 `run-suite`命令實作下列引數的支援： `timeout-multiplier` 指定大於 1.0 的值，該值將在執行測試時套用至所有逾時。 測試執行器可以使用此引數來增加他們想要執行的測試案例的逾時。當測試執行器在其`run-suite`命令中指定此引數時，IDT 會使用它來計算 IDT\$1TEST\$1TIMEOUT 環境變數的值，並在 IDT 內容中設定 `config.timeoutMultiplier` 欄位。若要支援此引數，您必須執行下列動作： + 讀取 IDT\$1TEST\$1TIMEOUT 環境變數以取得正確計算的逾時值，而不是直接使用 `test.json` 檔案的逾時值。 + 從 IDT 內容擷取`config.timeoutMultiplier`值，並將其套用至長時間執行的逾時。 如需因逾時事件而提早結束的詳細資訊，請參閱[指定結束行為](#test-exec-exiting)。 `stop-on-first-failure` 指定如果 IDT 遇到失敗，應停止執行所有測試。 當測試執行器在其`run-suite`命令中指定此引數時，IDT 會在遇到失敗時立即停止執行測試。不過，如果測試案例平行執行，則這可能會導致非預期的結果。若要實作支援，請確定如果 IDT 遇到此事件，您的測試邏輯會指示所有執行中的測試案例停止、清除臨時資源，並向 IDT 報告測試結果。如需在故障時提早結束的詳細資訊，請參閱 [指定結束行為](#test-exec-exiting)。 `group-id` 和 `test-id` 指定 IDT 應僅執行選取的測試群組或測試案例。 測試執行器可以將這些引數與其`run-suite`命令搭配使用，以指定下列測試執行行為： + 在指定的測試群組內執行所有測試。 + 在指定的測試群組內執行一系列的測試。 若要支援這些引數，測試套件的測試協調器必須在測試協調器中包含一組特定的 `RunTask`和 `Choice` 狀態。如果您不使用自訂狀態機器，則預設的 IDT 測試協調器會包含您所需的狀態，而且您不需要採取其他動作。不過，如果您使用的是自訂測試協調器，則使用 [狀態機器範例：執行使用者選取的測試群組](idt-state-machine.md#allow-specific-groups)做為範例，在您的測試協調器中新增所需的狀態。 如需 IDT CLI 命令的詳細資訊，請參閱 [偵錯並執行自訂測試套件](run-debug-custom-tests.md)。 ## 寫入事件日誌 測試執行時，您可以將資料傳送至 `stdout`和 `stderr`，以將事件日誌和錯誤訊息寫入主控台。如需主控台訊息格式的相關資訊，請參閱[主控台訊息格式](idt-review-results-logs.md#idt-console-format)。 當 IDT 完成執行測試套件時，此資訊也可在 資料夾的 `test_manager.log` 檔案中取得`/results//logs`。 您可以設定每個測試案例，將日誌從其測試執行寫入至位於 `/results/execution-id/logs` 資料夾中`_`的檔案，包括測試中裝置的日誌。若要執行此操作，請從 IDT 內容中擷取日誌檔案的路徑`testData.logFilePath`，在該路徑建立檔案，然後寫入您想要的內容。IDT 會根據正在執行的測試案例自動更新路徑。如果您選擇不建立測試案例的日誌檔案，則不會產生該測試案例的檔案。 您也可以設定文字可執行檔，視需要在 `/logs` 資料夾中建立其他日誌檔案。建議您為日誌檔案名稱指定唯一的字首，以免您的檔案遭到覆寫。 ## 向 IDT 報告結果 IDT 會將測試結果寫入 `awsiotdevicetester_report.xml`和 `suite-name_report.xml` 檔案。這些報告檔案位於 。 `/results//`兩個報告都會擷取測試套件執行的結果。如需 IDT 用於這些報告之結構描述的詳細資訊，請參閱 [檢閱 IDT 測試結果和日誌](idt-review-results-logs.md) 若要填入`suite-name_report.xml`檔案的內容，您必須在測試執行完成之前使用 `SendResult`命令向 IDT 報告測試結果。如果 IDT 找不到測試的結果，則會發出測試案例的錯誤。下列 Python 摘錄顯示將測試結果傳送至 IDT 的命令： ``` request-variable = SendResultRequest(TestResult(result)) client.send_result(request-variable) ``` 如果您未透過 API 報告結果，IDT 會在測試成品資料夾中尋找測試結果。此資料夾的路徑會存放在 IDT 內容中`testData.testArtifactsPath`存檔的 中。在此資料夾中，IDT 會使用第一個依字母順序排序的 XML 檔案做為測試結果。 如果您的測試邏輯產生 JUnit XML 結果，您可以將測試結果寫入成品資料夾中的 XML 檔案，以直接將結果提供給 IDT，而不是剖析結果，然後使用 API 將結果提交給 IDT。 如果您使用此方法，請確定您的測試邏輯準確摘要測試結果，並以與檔案相同的格式格式化結果`suite-name_report.xml`檔案。IDT 不會對您提供的資料執行任何驗證，但以下情況除外： + IDT 會忽略`testsuites`標籤的所有屬性。反之，它會從其他報告的測試群組結果計算標籤屬性。 + 必須至少有一個`testsuite`標籤存在於 中`testsuites`。 由於 IDT 在所有測試案例使用相同的成品資料夾，且不會在測試執行之間刪除結果檔案，因此如果 IDT 讀取不正確的檔案，此方法也可能會導致錯誤報告。建議您在所有測試案例使用與產生 XML 結果檔案相同的名稱，以覆寫每個測試案例的結果，並確保 IDT 可以使用正確的結果。雖然您可以使用混合方法在測試套件中報告，也就是說，對於某些測試案例使用 XML 結果檔案，並透過 API 為其他人提交結果，但不建議使用此方法。 ## 指定結束行為 將您的文字可執行檔設定為一律以結束碼 0 結束，即使測試案例報告失敗或錯誤結果亦然。僅使用非零結束碼來表示測試案例未執行，或測試案例可執行檔無法將任何結果傳達給 IDT。當 IDT 收到非零結束碼時，它會標記測試案例發生錯誤，導致無法執行。 IDT 可能會請求或預期測試案例在下列事件完成之前停止執行。使用此資訊來設定您的測試案例可執行檔，以偵測測試案例中的每個事件： **Timeout (逾時)** 當測試案例執行的時間超過`test.json`檔案中指定的逾時值時，便會發生。如果測試執行器使用`timeout-multiplier`引數指定逾時乘數，則 IDT 會使用乘數計算逾時值。 若要偵測此事件，請使用 IDT\$1TEST\$1TIMEOUT 環境變數。當測試執行器啟動測試時，IDT 會將 IDT\$1TEST\$1TIMEOUT 環境變數的值設定為計算的逾時值 （以秒為單位），並將變數傳遞至測試案例可執行檔。您可以讀取變數值來設定適當的計時器。 **中斷** 當測試執行器中斷 IDT 時發生。例如，按 Ctrl\$1C。 由於終端機會將訊號傳播到所有子程序，因此您只需在測試案例中設定訊號處理常式，即可偵測中斷訊號。 或者，您可以定期輪詢 API，以檢查 `PollForNotifications` API `CancellationRequested` 回應中的布林值。當 IDT `CancellationRequested` 收到中斷訊號時，它會將布林值設定為 `true`。 **第一次失敗時停止** 當與目前測試案例平行執行的測試案例失敗，且測試執行器使用`stop-on-first-failure`引數指定 IDT 應在遇到任何失敗時停止時，便會發生。 若要偵測此事件，您可以定期輪詢 API，以檢查 `PollForNotifications` API `CancellationRequested` 回應中的布林值。當 IDT 遇到故障，且設定為在第一次故障時停止時，它會將`CancellationRequested`布林值設定為 `true`。 當這些事件發生時，IDT 會等待 5 分鐘，讓任何目前正在執行的測試案例完成執行。如果所有執行中的測試案例未在 5 分鐘內結束，IDT 會強制其每個程序停止。如果 IDT 未在程序結束前收到測試結果，則會將測試案例標記為已逾時。最佳實務是，您應該確保測試案例在遇到其中一個事件時執行下列動作： 1. 停止執行正常測試邏輯。 1. 清除任何臨時資源，例如受測裝置上的測試成品。 1. 向 IDT 報告測試結果，例如測試失敗或錯誤。 1. 結束。 # 使用 IDT 內容 當 IDT 執行測試套件時，測試套件可以存取一組資料，用於判斷每個測試的執行方式。此資料稱為 IDT 內容。例如，由 `userdata.json` 檔案中的測試執行器提供的使用者資料組態，可用於在 IDT 內容中測試套件。 IDT 內容可以視為唯讀 JSON 文件。測試套件可以使用標準 JSON 資料類型，例如物件、陣列、數字等，從 擷取資料並將資料寫入內容。 ## 內容結構描述 IDT 內容使用下列格式： ``` { "config": { "timeoutMultiplier": timeout-multiplier }, "device": { }, "devicePool": { }, "resource": { "devices": [ { "name": "" } ] }, "testData": { "awsCredentials": { "awsAccessKeyId": "", "awsSecretAccessKey": "", "awsSessionToken": "" }, "logFilePath": "/path/to/log/file" }, "userData": { } } ``` `config` 來自 [`config.json` 檔案](set-custom-idt-config.md#config-json-custom)的資訊。`config` 欄位也包含下列其他欄位： `config.timeoutMultiplier` 測試套件所使用的任何逾時值的乘數。此值由 IDT CLI 的測試執行器指定。預設值為 `1`。 `device` 為測試執行選取的裝置的相關資訊。此資訊等同於所選裝置[`device.json`檔案中](set-custom-idt-config.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-custom-idt-config.md#userdata-config-custom)測試執行器提供的資訊。 ## 存取內容中的資料 您可以使用 JSON 檔案的 JSONPath 表示法，以及使用 `GetContextValue`和 `GetContextString` APIs 的可執行文字來查詢內容。用於存取 IDT 內容的 JSONPath 字串語法會有所不同，如下所示： + 在 `suite.json`和 中`test.json`，您可以使用 `{{query}}`。也就是說，請勿使用根元素`$.`來啟動表達式。 + 在 中`test_orchestrator.yaml`，您使用 `{{query}}`。 如果您使用已棄用的狀態機器，則在 中`state_machine.json`，您可以使用 `{{$.query}}`。 + 在 API 命令中，您可以使用 `query`或 `{{$.query}}`，視命令而定。如需詳細資訊，請參閱 SDKs中的內嵌文件。 下表說明典型 JSONPath 表達式中的運算子： | Operator | Description | | --- |--- | | \$1 | The root element. Because the top-level context value for IDT is an object, you will typically use \$1. to start your queries. | | .childName | Accesses the child element with name childName from an object. If applied to an array, yields a new array with this operator applied to each element. The element name is case sensitive. For example, the query to access the awsRegion value in the config object is \$1.config.awsRegion. | | 【開始：結束】 | Filters elements from an array, retrieving items beginning from the 入門 index and going up to the end index, both inclusive. | | 【index1、 index2、...、 indexN】 | Filters elements from an array, retrieving items from only the specified indices. | | 【？(expr)】 | Filters elements from an array using the expr expression. This expression must evaluate to a boolean value. | 若要建立篩選條件表達式，請使用下列語法： ``` | operator | ``` 在此語法中： + `jsonpath` 是使用標準 JSON 語法的 JSONPath。 + `value` 是使用標準 JSON 語法的任何自訂值。 + `operator` 是下列其中一個運算子： + `<` （小於） + `<=` （小於或等於） + `==` （等於） 如果表達式中的 JSONPath 或 值是陣列、布林值或物件值，則這是您唯一可以使用的支援二進位運算子。 + `>=` （大於或等於） + `>` （大於） + `=~` （規則表達式比對）。若要在篩選條件表達式中使用此運算子，表達式左側的 JSONPath 或值必須評估為字串，而右側必須是遵循 [RE2 語法](https://github.com/google/re2/wiki/Syntax)的模式值。 您可以使用格式為 \$1\$1*query*\$1\$1 的 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 預留位置來擷取單一字串以設定為環境變數可能會更方便。 # 設定測試執行器的設定 若要執行自訂測試套件，測試執行器必須根據他們想要執行的測試套件來設定其設定。根據位於 `/configs/` 資料夾中的組態檔案範本來指定設定。如有需要，測試執行器也必須設定 IDT 用來連線至 AWS 雲端的 AWS 登入資料。 身為測試寫入器，您需要設定這些檔案來[偵錯測試套件](run-debug-custom-tests.md)。您必須提供測試執行器的說明，以便他們可以視需要設定下列設定來執行您的測試套件。 ## 設定 device.json `device.json` 檔案包含執行測試之裝置的相關資訊 （例如 IP 地址、登入資訊、作業系統和 CPU 架構）。 測試執行器可以使用位於 `/configs/` 資料夾的下列範本`device.json`檔案提供此資訊。 ``` [ { "id": "", "sku": "", "features": [ { "name": "", "value": "", "configs": [ { "name": "", "value": "" } ], } ], "devices": [ { "id": "", "connectivity": { "protocol": "ssh | uart | docker", // ssh "ip": "", "port": , "auth": { "method": "pki | password", "credentials": { "user": "", // pki "privKeyPath": "/path/to/private/key", // password "password": "", } }, // uart "serialPort": "", // docker "containerId": "", "containerUser": "", } } ] } ] ``` 如下所述，包含值的所有欄位皆為必要： `id` 使用者定義的英數字元 ID，可唯一識別裝置的集合，稱為「裝置集區」**。屬於同一個集區的裝置必須有相同的硬體。當您執行測試套件，集區中的裝置會用來將工作負載平行化。多個裝置用來執行不同的測試。 `sku` 可唯一識別測試裝置的英數字元值。SKU 用於追蹤合格裝置。 如果您想要在 AWS Partner Device Catalog 中列出您的電路板，您在此處指定的 SKU 必須符合您在列出程序中使用的 SKU。 `features` 選用。包含裝置支援功能的陣列。裝置功能是您在測試套件中設定的使用者定義值。您必須提供測試執行器有關要包含在 `device.json` 檔案中的功能名稱和值的資訊。例如，如果您想要測試可做為其他裝置的 MQTT 伺服器運作的裝置，則可以設定測試邏輯來驗證名為 之功能的特定支援層級`MQTT_QOS`。測試執行器提供此功能名稱，並將功能值設定為其裝置支援的 QOS 層級。您可以從具有`devicePool.features`查詢的 [IDT 內容](idt-context.md)，或從具有`pool.features`查詢[的測試協調器內容](idt-state-machine.md#state-machine-context)擷取提供的資訊。 `features.name` 功能的名稱。 `features.value` 支援的功能值。 `features.configs` 如有需要，此功能的組態設定。 `features.config.name` 組態設定的名稱。 `features.config.value` 支援的設定值。 `devices` 要測試之集區中的裝置陣列。至少需要一個裝置。 `devices.id` 使用者定義的唯一識別符，用於識別要測試的裝置。 `connectivity.protocol` 用來與此裝置通訊的通訊協定。集區中的每個裝置都必須使用相同的通訊協定。 目前，唯一支援的值是實體裝置的 `ssh`和 ，以及 `uart` Docker 容器`docker`的 和 。 `connectivity.ip` 要測試之裝置的 IP 位址。 只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。 `connectivity.port` 選用。用於 SSH 連線的連接埠號碼。 預設值為 22。 只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。 `connectivity.auth` 連線的驗證資訊。 只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。 `connectivity.auth.method` 用來透過指定的連線通訊協定存取裝置的驗證方法。 支援的值如下： + `pki` + `password` `connectivity.auth.credentials` 用於驗證的燈入資料。 `connectivity.auth.credentials.password` 用於登入要測試裝置的密碼。 只有當 `connectivity.auth.method` 設為 `password` 時，才會套用此值。 `connectivity.auth.credentials.privKeyPath` 用來登入待測裝置之私有金鑰的完整路徑。 只有當 `connectivity.auth.method` 設為 `pki` 時，才會套用此值。 `connectivity.auth.credentials.user` 登入要測試之裝置的使用者名稱。 `connectivity.serialPort` 選用。裝置所連接的序列連接埠。 只有當 `connectivity.protocol` 設為 `uart` 時，才會套用此屬性。 `connectivity.containerId` 要測試之 Docker 容器的容器 ID 或名稱。 只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。 `connectivity.containerUser` 選用。容器內使用者的名稱。預設值是 Dockerfile 中提供的使用者。 預設值為 22。 只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。 若要檢查測試執行器是否設定不正確的測試裝置連線，您可以從測試協調器內容`pool.Devices[0].Connectivity.Protocol`擷取，並將其與`Choice`狀態中的預期值進行比較。如果使用不正確的通訊協定，則使用 `LogMessage` 狀態列印訊息並轉換為 `Fail` 狀態。 或者，您可以使用錯誤處理程式碼來報告不正確裝置類型的測試失敗。 ## （選用） 設定 userdata.json `userdata.json` 檔案包含測試套件所需的任何其他資訊，但未在`device.json`檔案中指定。此檔案的格式取決於測試套件中定義的[`userdata_scheme.json`檔案](idt-json-config.md#userdata-schema-json)。如果您是測試寫入器，請務必將此資訊提供給將執行您所寫入測試套件的使用者。 ## （選用） 設定 resource.json `resource.json` 檔案包含將用作資源裝置的任何裝置的相關資訊。資源裝置是測試待測裝置的特定功能所需的裝置。例如，若要測試裝置的 Bluetooth 功能，您可以使用資源裝置來測試您的裝置是否能夠成功連線。資源裝置是選用的，您可以視需要要求任意數量的資源裝置。身為測試寫入器，您可以使用 [test.json 檔案](idt-json-config.md#test-json)來定義測試所需的資源裝置功能。然後，測試執行器會使用 `resource.json` 檔案來提供具有所需功能的資源裝置集區。請務必將此資訊提供給將執行您寫入之測試套件的使用者。 測試執行器可以使用位於 `/configs/` 資料夾的下列範本`resource.json`檔案提供此資訊。 ``` [ { "id": "", "features": [ { "name": "", "version": "", "jobSlots": } ], "devices": [ { "id": "", "connectivity": { "protocol": "ssh | uart | docker", // ssh "ip": "", "port": , "auth": { "method": "pki | password", "credentials": { "user": "", // pki "privKeyPath": "/path/to/private/key", // password "password": "", } }, // uart "serialPort": "", // docker "containerId": "", "containerUser": "", } } ] } ] ``` 如下所述，包含值的所有欄位皆為必要： `id` 使用者定義的英數字元 ID，可唯一識別裝置的集合，稱為「裝置集區」**。屬於同一個集區的裝置必須有相同的硬體。當您執行測試套件，集區中的裝置會用來將工作負載平行化。多個裝置用來執行不同的測試。 `features` 選用。包含裝置支援功能的陣列。此欄位所需的資訊會在測試套件的 [test.json 檔案中](idt-json-config.md#test-json)定義，並決定要執行哪些測試，以及如何執行這些測試。如果測試套件不需要任何功能，則不需要此欄位。 `features.name` 功能的名稱。 `features.version` 功能版本。 `features.jobSlots` 設定 以指示可以同時使用裝置的測試數量。預設值為 `1`。 `devices` 要測試之集區中的裝置陣列。至少需要一個裝置。 `devices.id` 使用者定義的唯一識別符，用於識別要測試的裝置。 `connectivity.protocol` 用來與此裝置通訊的通訊協定。集區中的每個裝置都必須使用相同的通訊協定。 目前，唯一支援的值是實體裝置的 `ssh`和 ，以及 `uart` Docker 容器`docker`的 和 。 `connectivity.ip` 要測試之裝置的 IP 位址。 只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。 `connectivity.port` 選用。用於 SSH 連線的連接埠號碼。 預設值為 22。 只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。 `connectivity.auth` 連線的驗證資訊。 只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。 `connectivity.auth.method` 用來透過指定的連線通訊協定存取裝置的驗證方法。 支援的值如下： + `pki` + `password` `connectivity.auth.credentials` 用於驗證的燈入資料。 `connectivity.auth.credentials.password` 用於登入要測試裝置的密碼。 只有當 `connectivity.auth.method` 設為 `password` 時，才會套用此值。 `connectivity.auth.credentials.privKeyPath` 用來登入待測裝置之私有金鑰的完整路徑。 只有當 `connectivity.auth.method` 設為 `pki` 時，才會套用此值。 `connectivity.auth.credentials.user` 登入要測試之裝置的使用者名稱。 `connectivity.serialPort` 選用。裝置所連接的序列連接埠。 只有當 `connectivity.protocol` 設為 `uart` 時，才會套用此屬性。 `connectivity.containerId` 要測試之 Docker 容器的容器 ID 或名稱。 只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。 `connectivity.containerUser` 選用。容器內使用者的名稱。預設值是 Dockerfile 中提供的使用者。 預設值為 22。 只有當 `connectivity.protocol` 設為 `ssh` 時，才會套用此屬性。 ## （選用） 設定 config.json `config.json` 檔案包含 IDT 的組態資訊。一般而言，除了提供 IDT AWS 的使用者登入資料，以及選擇性 AWS 的區域之外，測試執行器不需要修改此檔案。如果 AWS 提供具有必要許可的登入資料， 會 AWS IoT Device Tester 收集並提交用量指標給 AWS。這是選擇加入功能，用於改善 IDT 功能。如需詳細資訊，請參閱[IDT 用量指標](idt-usage-metrics.md)。 測試執行器可以透過下列其中一種方式設定其 AWS 登入資料： + **憑證檔案** IDT 會使用與 AWS CLI相同的登入資料檔案。如需詳細資訊，請參閱[組態與登入資料檔案](https://docs.aws.amazon.com/cli/latest/userguide/cli-config-files.html)。 登入資料檔案的位置會有所不同，取決於您使用的作業系統： + macOS, Linux: `~/.aws/credentials` + Windows：`C:\Users\UserName\.aws\credentials` + **環境變數** 環境變數是由作業系統維護且由系統命令使用的變數。在 SSH 工作階段期間定義的變數在該工作階段關閉後無法使用。IDT 可以使用 `AWS_ACCESS_KEY_ID`和 `AWS_SECRET_ACCESS_KEY` 環境變數來存放 AWS 登入資料 若要在 Linux、macOS 或 Unix 上設定這些變數，請使用 **export**： ``` export AWS_ACCESS_KEY_ID= export AWS_SECRET_ACCESS_KEY= ``` 若要在 Windows 上設定這些變數，請使用 **set**： ``` set AWS_ACCESS_KEY_ID= set AWS_SECRET_ACCESS_KEY= ``` 若要設定 IDT 的 AWS 登入資料，測試執行器會編輯位於 `/configs/` 資料夾之 `config.json` 檔案中的 `auth`區段。 ``` { "log": { "location": "logs" }, "configFiles": { "root": "configs", "device": "configs/device.json" }, "testPath": "tests", "reportPath": "results", "awsRegion": "", "auth": { "method": "file | environment", "credentials": { "profile": "" } } } ] ``` 如下所述，包含值的所有欄位皆為必要： **注意** 此檔案中的所有路徑都是相對於 ** 定義。 `log.location` ＜*device-tester-extract-location> *中日誌資料夾的路徑。 `configFiles.root` 包含組態檔案的資料夾路徑。 `configFiles.device` `device.json` 檔案的路徑。 `testPath` 包含測試套件的資料夾路徑。 `reportPath` IDT 執行測試套件後，將包含測試結果的資料夾路徑。 `awsRegion` 選用。測試套件將使用 AWS 的區域。如果未設定，則測試套件將使用每個測試套件中指定的預設區域。 `auth.method` IDT 用來擷取 AWS 登入資料的方法。支援的值`file`是從登入資料檔案擷取登入資料，以及使用環境變數`environment`擷取登入資料。 `auth.credentials.profile` 從登入資料檔案使用的登入資料設定檔。只有當 `auth.method` 設為 `file` 時，才會套用此屬性。 # 偵錯並執行自訂測試套件 設定[必要的組態](set-custom-idt-config.md)後，IDT 可以執行您的測試套件。完整測試套件的執行時間取決於硬體和測試套件的組成。如需參考，在 Raspberry Pi 3B AWS IoT Greengrass 上完成完整資格測試套件約需 30 分鐘。 3B 當您撰寫測試套件時，您可以使用 IDT 在除錯模式下執行測試套件，在執行程式碼之前先檢查程式碼，或將其提供給測試執行器。 ## 在除錯模式下執行 IDT 由於測試套件依賴 IDT 與裝置互動、提供內容和接收結果，因此如果沒有任何 IDT 互動，您就無法在 IDE 中對測試套件進行偵錯。若要這樣做，IDT CLI 會提供 `debug-test-suite`命令，可讓您在偵錯模式下執行 IDT。執行下列命令以檢視 的可用選項`debug-test-suite`： ``` devicetester_[linux | mac | win_x86-64] debug-test-suite -h ``` 當您在偵錯模式下執行 IDT 時，IDT 實際上不會啟動測試套件或執行測試協調器；而是與您的 IDE 互動，以回應在 IDE 中執行的測試套件發出的請求，並將日誌列印到主控台。IDT 不會逾時，並等待結束，直到手動中斷為止。在偵錯模式中，IDT 也不會執行測試協調器，也不會產生任何報告檔案。若要偵錯測試套件，您必須使用 IDE 來提供 IDT 通常從組態 JSON 檔案取得的一些資訊。請務必提供下列資訊： + 每個測試的環境變數和引數。IDT 不會從 `test.json`或 讀取此資訊`suite.json`。 + 選取資源裝置的引數。IDT 不會從 讀取此資訊`test.json`。 若要偵錯您的測試套件，請完成下列步驟： 1. 建立執行測試套件所需的設定組態檔案。例如，如果您的測試套件需要 `device.json`、 `resource.json`和 `user data.json`，請務必視需要設定所有測試套件。 1. 執行下列命令，將 IDT 置於偵錯模式，然後選取執行測試所需的任何裝置。 ``` devicetester_[linux | mac | win_x86-64] debug-test-suite [options] ``` 在您執行此命令之後，IDT 會等待測試套件的請求，然後回應這些請求。IDT 也會產生 IDT 用戶端 SDK 案例程序所需的環境變數。 1. 在您的 IDE 中，使用 `run`或 `debug`組態來執行下列動作： 1. 設定 IDT 產生環境變數的值。 1. 設定您在 `test.json`和 `suite.json` 檔案中指定的任何環境變數或引數的值。 1. 視需要設定中斷點。 1. 在 IDE 中執行測試套件。 您可以視需要多次偵錯並重新執行測試套件。IDT 不會在偵錯模式下逾時。 1. 完成偵錯後，請中斷 IDT 以結束偵錯模式。 ## 執行測試的 IDT CLI 命令 下節說明 IDT CLI 命令： ------ #### [ IDT v4.0.0 ] `help` 列出所指定命令的相關資訊。 `list-groups` 列出指定測試套件中的群組。 `list-suites` 列出可用的測試套件。 `list-supported-products` 在此情況下，列出 IDT 版本支援的 產品 AWS IoT Greengrass ，以及適用於目前 AWS IoT Greengrass IDT 版本的資格測試套件版本。 `list-test-cases` 列出特定測試群組中的測試案例。支援下列選項： + `group-id`。 要搜尋的測試群組。此選項為必要選項，且必須指定單一群組。 `run-suite` 在裝置集區上執行測試套件。以下是一些常用的選項： + `suite-id`。 要執行的測試套件版本。如果未指定，IDT 會使用 `tests` 資料夾中的最新版本。 + `group-id`。 要執行的測試群組，以逗號分隔的清單形式呈現。如果未指定，IDT 會執行測試套件中的所有測試群組。 + `test-id`。 要執行的測試案例，以逗號分隔的清單形式呈現。指定時，`group-id` 必須指定單一群組。 + `pool-id`。 要測試的裝置集區。如果測試執行器在您的`device.json`檔案中定義了多個裝置集區，則必須指定集區。 + `timeout-multiplier`。 設定 IDT 修改具有使用者定義乘數之測試的`test.json`檔案中指定的測試執行逾時。 + `stop-on-first-failure`。 設定 IDT 在第一次失敗時停止執行。此選項應與 `group-id` 搭配使用以偵錯指定的測試群組。 + `userdata`。 設定檔案，其中包含執行測試套件所需的使用者資料資訊。只有在測試套件的 `suite.json` 檔案中`userdataRequired`設定為 true 時，才需要這樣做。 如需 `run-suite` 選項的詳細資訊，請使用下列 `help` 選項： ``` devicetester_[linux | mac | win_x86-64] run-suite -h ``` `debug-test-suite` 在除錯模式下執行測試套件。如需詳細資訊，請參閱[在除錯模式下執行 IDT](#idt-debug-mode)。 ------ # 檢閱 IDT 測試結果和日誌 本節說明 IDT 產生主控台日誌和測試報告的格式。 ## 主控台訊息格式 AWS IoT Device Tester 使用標準格式，在 主控台啟動測試套件時，將訊息列印到 主控台。以下摘錄顯示 IDT 產生的主控台訊息範例。 ``` time="2000-01-02T03:04:05-07:00" level=info msg=Using suite: MyTestSuite_1.0.0 executionId=9a52f362-1227-11eb-86c9-8c8590419f30 ``` 大多數主控台訊息包含下列欄位： `time` 已記錄事件的完整 ISO 8601 時間戳記。 `level` 已記錄事件的訊息層級。一般而言，記錄的訊息層級是 `info`、 `warn`或 之一`error`。如果 IDT 遇到預期事件導致提早結束，則發出 `fatal`或 `panic` 訊息。 `msg` 記錄的訊息。 `executionId` 目前 IDT 程序的唯一 ID 字串。此 ID 用於區分個別 IDT 執行。 從測試套件產生的主控台訊息提供有關受測裝置以及 IDT 執行的測試套件、測試群組和測試案例的其他資訊。以下摘錄顯示從測試套件產生的主控台訊息範例。 ``` time="2000-01-02T03:04:05-07:00" level=info msg=Hello world! suiteId=MyTestSuite groupId=myTestGroup testCaseId=myTestCase deviceId=my-device executionId=9a52f362-1227-11eb-86c9-8c8590419f30 ``` 主控台訊息的測試套件特定部分包含下列欄位： `suiteId` 目前正在執行的測試套件名稱。 `groupId` 目前正在執行的測試群組 ID。 `testCaseId` 目前執行的測試案例 ID。 `deviceId` 目前測試案例正在使用的測試中裝置的 ID。 若要在 IDT 完成執行測試時將測試摘要列印到主控台，您必須在測試協調器中包含 [`Report` 狀態](idt-state-machine.md#state-report)。測試摘要包含測試套件的相關資訊、執行的每個群組的測試結果，以及產生的日誌和報告檔案的位置。下列範例顯示測試摘要訊息。 ``` ========== Test Summary ========== Execution Time: 5m00s Tests Completed: 4 Tests Passed: 3 Tests Failed: 1 Tests Skipped: 0 ---------------------------------- Test Groups: GroupA: PASSED GroupB: FAILED ---------------------------------- Failed Tests: Group Name: GroupB Test Name: TestB1 Reason: Something bad happened ---------------------------------- Path to IoT Device Tester Report: /path/to/awsiotdevicetester_report.xml Path to Test Execution Logs: /path/to/logs Path to Aggregated JUnit Report: /path/to/MyTestSuite_Report.xml ``` ## AWS IoT Device Tester 報告結構描述 `awsiotdevicetester_report.xml` 是已簽章的報告，其中包含下列資訊： + IDT 版本。 + 測試套件版本。 + 用於簽署報告的報告簽章和金鑰。 + `device.json` 檔案中指定的裝置 SKU 和裝置集區名稱。 + 已測試的產品版本和裝置功能。 + 測試結果的彙總摘要。此資訊與 `suite-name_report.xml` 檔案中包含的資訊相同。 ``` idt-version test-suite-version signature keyname execution-id start-time end-time product-name product-version device-sku device-name ssh | uart | docker ``` `awsiotdevicetester_report.xml` 檔案包含 `` 標籤，其中包含關於受測產品和經過一系列測試驗證後之產品功能的資訊。`` 標籤中使用的屬性 `name` 受測產品名稱。 `version` 受測產品版本。 `features` 驗證的功能。測試套件`required`需要標記為 的功能，才能驗證裝置。以下片段顯示此資訊如何出現在 `awsiotdevicetester_report.xml` 檔案中。 ``` ``` 標記為 的功能`optional`不需要驗證。以下程式碼片段顯示選用功能。 ``` 
 ``` ## 測試套件報告結構描述 `suite-name_Result.xml` 報告採用 [JUnit XML 格式](https://llg.cubic.org/docs/junit/)。您可以將它整合到持續整合和部署平台，例如 [Jenkins](https://jenkins.io/)、[Bamboo](https://www.atlassian.com/software/bamboo) 等。報告包含測試結果的彙總摘要。 ``` reason reason reason ``` `awsiotdevicetester_report.xml` 或 中的報告區段會`suite-name_report.xml`列出已執行的測試和結果。 第一個 XML 標籤 `` 包含測試執行的摘要。例如： ``` ````` 標籤中使用的屬性 `name` 測試套件的名稱。 `time` 執行測試套件所需的時間，以秒為單位。 `tests` 執行的測試次數。 `failures` 已執行但未通過的測試次數。 `errors` IDT 無法執行的測試次數。 `disabled` 此屬性未使用，可忽略。 如果測試發生失敗或錯誤，您可以檢閱 `` XML 標籤來識別失敗的測試。`` 標籤內的 `` XML 標籤會顯示測試群組的測試結果摘要。例如： ``` ``` 其格式類似於 `` 標籤，但有不使用且可忽略的 `skipped` 屬性。在每個 `` XML 標籤內，測試群組每個執行的測試都有 `` 標籤。例如： ``` > ````` 標籤中使用的屬性 `name` 測試的名稱。 `attempts` IDT 執行測試案例的次數。 當測試案例失敗或發生錯誤時，系統就會將 `` 或 `` 標籤新增至 `` 標籤，其中附有相關資訊以利故障診斷。例如： ``` Reason for the test failure Reason for the test execution error ``` # IDT 用量指標 如果您提供具有必要許可的 AWS 登入資料， 會 AWS IoT Device Tester 收集並提交用量指標給 AWS。這是選擇加入功能，用於改善 IDT 功能。IDT 會收集下列資訊： + 用來執行 IDT 的 AWS 帳戶 ID + 用於執行測試的 IDT AWS CLI 命令 + 執行的測試套件 + ** 資料夾的測試套件 + 在裝置集區中設定的裝置數量 + 測試案例名稱和執行時間 + 測試結果資訊，例如測試是否通過、失敗、發生錯誤或被略過 + 測試的產品功能 + IDT 結束行為，例如非預期或提早結束 IDT 傳送的所有資訊也會記錄到 `/results//` 資料夾中`metrics.log`的檔案。您可以檢視日誌檔案，以查看在測試執行期間收集的資訊。只有在您選擇收集用量指標時，才會產生此檔案。 若要停用指標集合，您不需要採取其他動作。只要不要存放您的 AWS 登入資料，而且如果您有存放的 AWS 登入資料，請勿設定 `config.json` 檔案來存取這些登入資料。 ## 設定您的 AWS 登入資料 如果您還沒有 AWS 帳戶，則必須[建立一個](#idt-metrics-aws-account)。如果您已經有 AWS 帳戶，您只需要為您的帳戶[設定必要的許可](#idt-metrics-permissions)，以允許 IDT AWS 代表您將用量指標傳送至 。 ### 步驟 1：建立 AWS 帳戶 在此步驟中，建立和設定 AWS 帳戶。如果您已擁有 AWS 帳戶，請跳到 [步驟 2：設定 IDT 的許可](#idt-metrics-permissions)。 如果您沒有 AWS 帳戶，請完成下列步驟來建立一個。 **註冊 AWS 帳戶** 1. 開啟 [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup)。 1. 請遵循線上指示進行。 部分註冊程序需接收來電或簡訊，並在電話鍵盤輸入驗證碼。 當您註冊 時 AWS 帳戶，*AWS 帳戶根使用者*會建立 。根使用者有權存取該帳戶中的所有 AWS 服務 和資源。作為安全最佳實務，請將管理存取權指派給使用者，並且僅使用根使用者來執行[需要根使用者存取權的任務](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks)。 若要建立管理員使用者，請選擇下列其中一個選項。 **** | 選擇一種管理管理員的方式 | 到 | 根據 | 您也可以 | | --- | --- | --- | --- | | 在 IAM Identity Center (建議) | 使用短期憑證存取 AWS。這與安全性最佳實務一致。有關最佳實務的資訊，請參閱 *IAM 使用者指南*中的 [IAM 安全最佳實務](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-users-federation-idp)。 | 請遵循 AWS IAM Identity Center 使用者指南的[入門](https://docs.aws.amazon.com//singlesignon/latest/userguide/getting-started.html)中的說明。 | 在 AWS Command Line Interface 使用者指南中設定 [AWS CLI 以使用 來設定 AWS IAM Identity Center](https://docs.aws.amazon.com//cli/latest/userguide/cli-configure-sso.html)程式設計存取。 | | 在 IAM 中 (不建議使用) | 使用長期憑證存取 AWS。 | 請遵循《IAM 使用者指南》中[建立 IAM 使用者以進行緊急存取](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started-emergency-iam-user.html) 的指示。 | 請依照《IAM 使用者指南》中的[管理 IAM 使用者的存取金鑰](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_credentials_access-keys.html)設定以程式設計方式存取。 | ### 步驟 2：設定 IDT 的許可 在此步驟中，設定 IDT 用來執行測試和收集 IDT 用量資料的許可。您可以使用 AWS 管理主控台 或 AWS Command Line Interface (AWS CLI) 來建立 IAM 政策和 IDT 的使用者，然後將政策連接到使用者。 + [設定 IDT (主控台) 的許可](#idt-metrics-permissions-console) + [步驟 2：設定 IDT (AWS CLI) 的許可](#idt-metrics-permissions-cli) **設定 IDT (主控台) 的許可** 請依照下列步驟使用主控台來設定 IDT for AWS IoT Greengrass的許可。 1. 登入 [IAM 主控台](https://console.aws.amazon.com/iam)。 1. 建立客戶受管政策，該政策授與建立具有特定許可之角色的許可。 1. 在導覽窗格中，選擇**政策**，然後選擇**建立政策**。 1. 在 **JSON** 標籤上，用以下政策取代預留位置內容。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot-device-tester:SendMetrics" ], "Resource": "*" } ] } ``` ------ 1. 選擇**檢閱政策**。 1. 對於**名稱**，輸入 **IDTUsageMetricsIAMPermissions**。在 **Summary (摘要)** 下，檢閱您的政策所授與的許可。 1. 選擇**建立政策**。 1. 建立 IAM 使用者並將許可連接到使用者。 1. 建立 IAM 使用者。請遵循《[IAM 使用者指南》中建立 IAM 使用者 （主控台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console) 的步驟 1 到 5。 **如果您已建立 IAM 使用者，請跳至下一個步驟。 1. 將許可連接至您的 IAM 使用者： 1. 在 **Set permissions (設定許可)** 頁面上，選擇 **Attach existing policies directly (直接連接現有的政策)**。 1. 搜尋您在上一個步驟中建立的 **IDTUsageMetricsIAMPermissions** 政策。選取核取方塊。 1. 選擇下**一步：標籤**。 1. 選擇 **Next: Review (下一步：檢閱)** 以檢視選擇的摘要。 1. 選擇 **Create user** (建立使用者)。 1. 若要檢視使用者的存取金鑰 (存取金鑰 ID 和私密存取金鑰)，請選擇密碼和存取金鑰旁的 **Show (顯示)**。若要儲存存取金鑰，請選擇 **Download.csv**，並將檔案儲存到安全的位置。您稍後會使用此資訊來設定您的 AWS 登入資料檔案。   **步驟 2：設定 IDT (AWS CLI) 的許可** 請依照下列步驟使用 AWS CLI 來設定 IDT for 的許可 AWS IoT Greengrass。 1. 如果尚未安裝，請在電腦上安裝和設定 AWS CLI 。請遵循*AWS Command Line Interface 《 使用者指南*》中的[安裝 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) 中的步驟。 **注意** AWS CLI 是開放原始碼工具，可用來與命令列 Shell 中的 AWS 服務互動。 1. 建立下列客戶受管政策，授予管理 IDT 和 AWS IoT Greengrass 角色的許可。 ------ #### [ Linux or Unix ] ``` aws iam create-policy --policy-name IDTUsageMetricsIAMPermissions --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot-device-tester:SendMetrics" ], "Resource": "*" } ] }' ``` ------ #### [ Windows command prompt ] ``` aws iam create-policy --policy-name IDTUsageMetricsIAMPermissions --policy-document '{\"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\", \"Action\": [\"iot-device-tester:SendMetrics\"], \"Resource": \"*\"}]}' ``` **注意** 此步驟包含 Windows 命令提示字元範例，因為它使用的 JSON 語法與 Linux、macOS 或 Unix 終端機命令不同。 ------ #### [ PowerShell ] ``` aws iam create-policy --policy-name IDTUsageMetricsIAMPermissions --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot-device-tester:SendMetrics" ], "Resource": "*" } ] }' ``` ------ 1. 建立 IAM 使用者並連接 IDT for 所需的許可 AWS IoT Greengrass。 1. 建立 IAM 使用者。 ``` aws iam create-user --user-name user-name ``` 1. 將您建立`IDTUsageMetricsIAMPermissions`的政策連接至您的 IAM 使用者。將 *user-name* 取代為您的 IAM 使用者名稱，並將 命令中的 ** 取代為您的 ID AWS 帳戶。 ``` aws iam attach-user-policy --user-name user-name --policy-arn arn:aws:iam:::policy/IDTGreengrassIAMPermissions ``` 1. 為使用者建立私密存取金鑰。 ``` aws iam create-access-key --user-name user-name ``` 將輸出儲存在安全的位置。您稍後會使用此資訊來設定您的 AWS 登入資料檔案。 ## 提供 AWS 登入資料給 IDT 若要允許 IDT 存取您的 AWS 登入資料並提交指標 AWS，請執行下列動作： 1. 將 IAM 使用者的 AWS 登入資料儲存為環境變數或儲存在登入資料檔案中： 1. 若要使用環境變數，請執行下列命令。 ------ #### [ Linux or Unix ] ``` export AWS_ACCESS_KEY_ID=access-key export AWS_SECRET_ACCESS_KEY=secret-access-key ``` ------ #### [ Windows Command Prompt (CMD) ] ``` set AWS_ACCESS_KEY_ID=access-key set AWS_SECRET_ACCESS_KEY=secret-access-key ``` ------ #### [ PowerShell ] ``` $env:AWS_ACCESS_KEY_ID="access-key" $env:AWS_SECRET_ACCESS_KEY="secret-access-key" ``` ------ 1. 若要使用登入資料檔案，請將下列資訊新增至`~/.aws/credentials`檔案。 ``` [profile-name] aws_access_key_id=access-key aws_secret_access_key=secret-access-key ``` 1. 設定 `config.json` 檔案的 `auth`區段。如需詳細資訊，請參閱[（選用） 設定 config.json](set-custom-idt-config.md#config-json-custom)。 # 對 IDT for AWS IoT Greengrass V2 進行故障診斷 IDT for AWS IoT Greengrass V2 會根據錯誤類型將錯誤寫入各種位置。IDT 會將錯誤寫入主控台、日誌檔案和測試報告。 ## 在哪裡尋找錯誤 當測試執行時，主控台會顯示高階錯誤，而失敗測試的摘要會在所有測試完成時顯示。 `awsiotdevicetester_report.xml`包含導致測試失敗之所有錯誤的摘要。IDT 會將每個測試執行的日誌檔案存放在具有測試執行 UUID 的目錄中，並在測試執行期間顯示在主控台上。 IDT 測試日誌目錄為 `/results//logs/`。此目錄包含資料表中顯示的下列檔案。這適用於除錯。 | 檔案 | Description | | --- | --- | | test\$1manager.log | 測試執行時寫入主控台的日誌。此檔案結尾的結果摘要包含測試失敗的清單。 這個檔案中的警告和錯誤日誌提供有關失敗的一些資訊。 | | test-group-id/test-case-id/test-name.log | 測試群組中特定測試的詳細日誌。對於部署 Greengrass 元件的測試，測試案例日誌檔案稱為 greengrass-test-run.log。 | | test-group-id/test-case-id/greengrass.log | AWS IoT Greengrass Core 軟體的詳細日誌。IDT 會在裝置上執行安裝 AWS IoT Greengrass Core 軟體的測試時，從待測裝置複製此檔案。如需此日誌檔案中訊息的詳細資訊，請參閱 [故障診斷 AWS IoT Greengrass V2](troubleshooting.md)。 | | test-group-id/test-case-id/component-name.log | 測試執行期間部署之 Greengrass 元件的詳細日誌。IDT 會在執行部署特定元件的測試時，從待測裝置複製元件日誌檔案。每個元件日誌檔的名稱對應於已部署元件的名稱。如需此日誌檔案中訊息的詳細資訊，請參閱 [故障診斷 AWS IoT Greengrass V2](troubleshooting.md)。 | ## 解決 IDT for AWS IoT Greengrass V2 錯誤 執行 IDT for 之前 AWS IoT Greengrass，請先取得正確的組態檔案。如果您收到剖析和組態錯誤，您的第一步是找出並使用適合您環境的組態範本。 如果您仍然有問題，請參閱下列除錯程序。 **Topics** + [別名解析錯誤](#alias-resolution-errors) + [衝突錯誤](#conflict-error) + [無法開始測試錯誤](#could-not-start-test) + [Docker 資格映像存在錯誤](#docker-qualification-image-exists) + [無法讀取登入資料](#failed-to-read-credential-windows) + [PreInstalled Greengrass 的 Guice 錯誤](#guice-errors) + [無效的簽章例外狀況](#invalid-signature-exception-lambda) + [機器學習資格錯誤](#machine-learning-qualification-failure) + [開放測試架構 (OTF) 失敗的部署](#otf-deployment-failure) + [剖析錯誤](#parse-error) + [拒絕許可錯誤](#permission-denied-pwd-sudo) + [資格報告產生錯誤](#qualification-report-policy-error) + [遺漏必要參數錯誤](#required-param-missing) + [macOS 上的安全例外狀況](#security-exception-macos) + [SSH 連線錯誤](#ssh-connect-errors) + [串流管理員資格錯誤](#stream-manager-qualification-failure) + [逾時錯誤](#test-timeout) + [版本檢查錯誤](#version-compatibility-check-failure) ### 別名解析錯誤 當您執行自訂測試套件時，您可能會在 主控台和 中看到下列錯誤`test_manager.log`。 ``` Couldn't resolve placeholders: couldn't do a json lookup: index out of range ``` 當 IDT 測試協調器中設定的別名未正確解析，或已解析的值不存在於組態檔案中時，就會發生此錯誤。若要解決此錯誤，請確定您的 `device.json`和 `userdata.json `包含測試套件所需的正確資訊。如需 AWS IoT Greengrass 資格所需組態的資訊，請參閱 [設定 IDT AWS IoT Greengrass 設定以執行資格套件](set-config.md)。 ### 衝突錯誤 當您同時在多個裝置上執行 AWS IoT Greengrass 資格套件時，您可能會看到下列錯誤。 ``` ConflictException: Component [com.example.IDTHelloWorld : 1.0.0] for account [account-id] already exists with state: [DEPLOYABLE] { RespMetadata: { StatusCode: 409, RequestID: “id” }, Message_: “Component [com.example.IDTHelloWorld : 1.0.0] for account [account-id] already exists with state: [DEPLOYABLE]” } ``` AWS IoT Greengrass 資格套件尚未支援並行測試執行。為每個裝置依序執行資格套件。 ### 無法開始測試錯誤 您可能會遇到錯誤，指出測試嘗試啟動時發生的失敗。有數種可能的原因，因此，請執行下列動作： + 請確定執行命令中的集區名稱確實存在。IDT 會直接從您的 `device.json` 檔案參考集區名稱。 + 確保您集區中的裝置都有正確的組態參數。 ### Docker 資格映像存在錯誤 Docker 應用程式管理員資格測試使用 Amazon ECR 中的`amazon/amazon-ec2-metadata-mock`容器映像來限定測試中的裝置。 如果影像已存在於待測裝置的 Docker 容器中，您可能會收到下列錯誤。 ``` The Docker image amazon/amazon-ec2-metadata-mock:version already exists on the device. ``` 如果您先前已下載此映像並在裝置上執行`amazon/amazon-ec2-metadata-mock`容器，請務必在執行資格測試之前，從受測裝置移除此映像。 ### 無法讀取登入資料 測試 Windows 裝置時，如果您用來連線至待測裝置的使用者未在該裝置的登入資料管理員中設定，則可能會在 `greengrass.log` 檔案中遇到`Failed to read credential`錯誤。 若要解決此錯誤，請在待測裝置的登入資料管理員中設定 IDT 使用者的使用者名稱和密碼。 如需詳細資訊，請參閱[設定 Windows 裝置的使用者登入資料](device-config-setup.md#configure-windows-user-for-idt)。 ### PreInstalled Greengrass 的 Guice 錯誤 使用 PreInstalled Greengrass 執行 IDT 時，如果您遇到 `Guice`或 的錯誤`ErrorInCustomProvider`，請檢查檔案是否已`userdata.json`將 `InstalledDirRootOnDevice`設定為 Greengrass 安裝資料夾。IDT 會在 `effectiveConfig.yaml`下檢查 檔案`/config/effectiveConfig.yaml`。 如需詳細資訊，請參閱[設定 Windows 裝置的使用者登入資料](device-config-setup.md#configure-windows-user-for-idt)。 ### 無效的簽章例外狀況 當您執行 Lambda 資格測試時，如果您的 IDT 主機機器遇到網路存取問題，您可能會遇到`invalidsignatureexception`錯誤。重設路由器並再次執行測試。 ### 機器學習資格錯誤 當您執行機器學習 (ML) 資格測試時，如果裝置不符合部署 AWS所提供 ML 元件[的需求](dlr-component.md#dlr-component-requirements)，您可能會遇到資格失敗。若要疑難排解 ML 資格錯誤，請執行下列動作： + 在元件日誌中尋找測試執行期間所部署元件的錯誤詳細資訊。元件日誌位於 `/results//logs/`目錄中。 + 將 `-Dgg.persist=installed.software`引數新增至失敗測試案例的 `test.json` 檔案。`test.json` 檔案位於 `/tests/GGV2Q_version directory. ` ### 開放測試架構 (OTF) 失敗的部署 如果 OTF 測試無法完成部署，可能原因可能是為 `TempResourcesDirOnDevice`和 的父資料夾設定許可`InstallationDirRootOnDevice`。若要正確設定此資料夾的許可，請執行下列命令。`folder-name` 將 取代為父資料夾的名稱。 ``` sudo chmod 755 folder-name ``` ### 剖析錯誤 JSON 組態中的 Typos 可能會導致剖析錯誤。在大部分的情況下，問題是出在 JSON 檔案中省略了括弧、逗號或引號。IDT 會執行 JSON 驗證並列印除錯資訊。該工具會印出發生錯誤的行、行號和語法錯誤的欄號。此資訊應足以協助您修正錯誤，但如果您仍然找不到錯誤，您可以在 IDE、Atom 或 Sublime 等文字編輯器，或透過 JSONLint 等線上工具手動執行驗證。 ### 拒絕許可錯誤 IDT 會在待測裝置的各種目錄和檔案上執行操作。這些操作中有些需要根存取。IDT 必須能夠在不輸入密碼的情況下使用 sudo 執行命令，才能自動化這些操作。 依照以下步驟，在不輸入密碼的情況下允許 sudo 存取。 **注意** `user` 和 `username` 是指 IDT 存取待測裝置時所使用的 SSH 使用者。 1. 使用 **sudo usermod -aG sudo **** 將您的 SSH 使用者新增至 sudo 群組。 1. 登出後再登入，以使變更生效。 1. 開啟 `/etc/sudoers` 檔案，然後在檔案結尾處新增以下一行：` ALL=(ALL) NOPASSWD: ALL` **注意** 最佳實務為建議您在編輯 `/etc/sudoers` 時使用 **sudo visudo**。 ### 資格報告產生錯誤 IDT 支援四個`major.minor`最新版本的 AWS IoT Greengrass V2 資格套件 (GGV2Q)，以產生資格報告，您可以提交至 AWS Partner Network 以將裝置包含在 AWS Partner Device Catalog 中。舊版的資格套件不會產生資格報告。 如果您對支援政策有任何疑問，請聯絡 [AWS 支援](https://aws.amazon.com/contact-us/)。 ### 遺漏必要參數錯誤 當 IDT 新增新功能時，可能會將變更引入組態檔案。使用舊的組態檔案可能會破壞組態。如果發生這種情況，`/results//logs` 下的 `.log` 檔案會明確列出所有遺漏的參數。IDT 也會驗證您的 JSON 組態檔案結構描述，以確認您使用的是最新的支援版本。 ### macOS 上的安全例外狀況 當您在 macOS 主機電腦上執行 IDT 時，它會封鎖 IDT 執行。若要執行 IDT，請將安全例外授予 IDT 執行期功能一部分的可執行檔。當您在主機電腦上看到警告訊息顯示時，請針對每個適用的可執行檔執行下列動作： **將安全性例外狀況授予 IDT 可執行檔** 1. 在 macOS 電腦上的 Apple 功能表上，開啟**系統偏好設定**。 1. 選擇**安全性與隱私權**，然後在**一般**索引標籤上，選擇鎖定圖示以變更安全性設定。 1. 如果 遭到封鎖`devicetester_mac_x86-64`，請尋找訊息`"devicetester_mac_x86-64" was blocked from use because it is not from an identified developer.`，然後選擇**允許任何方式**。 1. 繼續 IDT 測試，直到您完成所有涉及的可執行檔為止。 ### SSH 連線錯誤 當 IDT 無法連線至受測裝置時，它會在 中記錄連線失敗`/results//logs/.log`。SSH 訊息會顯示在此日誌檔案的頂端，因為連線至待測裝置是 IDT 執行的第一個操作之一。 大多數 Windows 組態使用 PuTTy 終端機應用程式連線到 Linux 主機。此應用程式要求您將標準 PEM 私有金鑰檔案轉換為名為 PPK 的專屬 Windows 格式。如果您在 `device.json` 檔案中設定 SSH，請使用 PEM 檔案。如果您使用 PPK 檔案，IDT 無法與 AWS IoT Greengrass 裝置建立 SSH 連線，也無法執行測試。 從 IDT v4.4.0 開始，如果您尚未在待測裝置上啟用 SFTP，則您可能會在日誌檔案中看到下列錯誤。 ``` SSH connection failed with EOF ``` 若要解決此錯誤，請在裝置上啟用 SFTP。 ### 串流管理員資格錯誤 當您執行串流管理員資格測試時，您可能會在 `com.aws.StreamManagerExport.log` 檔案中看到下列錯誤。 ``` Failed to upload data to S3 ``` 當串流管理員使用您裝置上的 `~/root/.aws/credentials` 檔案中的 AWS 登入資料，而不是使用 IDT 匯出到待測裝置的環境登入資料時，可能會發生此錯誤。若要避免此問題，請刪除裝置上的 `credentials` 檔案，然後重新執行資格測試。 ### 逾時錯誤 您可以指定套用至每個測試逾時預設值的逾時乘數，以增加每個測試的逾時。此旗標設定的任何值必須大於或等於 1.0。 若要使用逾時乘數，請在執行測試時使用旗標 `--timeout-multiplier`。例如： ``` ./devicetester_linux run-suite --suite-id GGV2Q_1.0.0 --pool-id DevicePool1 --timeout-multiplier 2.5 ``` 如需詳細資訊，請執行 `run-suite --help`。 當 IDT 測試案例因為組態問題而無法完成時，會發生一些逾時錯誤。您無法透過增加逾時乘數來解決這些錯誤。使用測試執行的日誌來疑難排解基礎組態問題。 + 如果 MQTT 或 Lambda 元件日誌包含`Access denied`錯誤，您的 Greengrass 安裝資料夾可能沒有正確的檔案許可。針對您在 `userdata.json` 檔案中定義的安裝路徑中的每個資料夾執行下列命令。 ``` sudo chmod 755 folder-name ``` + 如果 Greengrass 日誌指出 Greengrass CLI 部署未完成，請執行下列動作： + 確認 `bash` 已安裝在待測裝置上。 + 如果您的`userdata.json`檔案包含 `GreengrassCliVersion` 組態參數，請將其移除。此參數在 IDT v4.1.0 和更新版本中已棄用。如需詳細資訊，請參閱[設定 userdata.json](set-config.md#userdata-config)。 + 如果 Lambda 部署測試失敗，並顯示錯誤訊息「驗證 Lambda 發佈：逾時」，而且您在測試日誌檔案中收到錯誤，指出 (`idt-gg2-lambda-function-idt-.log`)`Error: Could not find or load main class com.amazonaws.greengrass.runtime.LambdaRuntime.`，請執行下列動作： + 驗證 `userdata.json` `InstallationDirRootOnDevice`檔案中用於哪些資料夾。 + 請確定您的裝置已設定正確的使用者許可。如需詳細資訊，請參閱[在裝置上設定使用者許可](https://docs.aws.amazon.com/greengrass/v2/developerguide/device-config-setup.html#root-access)。 ### 版本檢查錯誤 當 IDT AWS 使用者的使用者登入資料沒有必要的 IAM 許可時，IDT 會發出下列錯誤。 ``` Failed to check version compatibility ``` 沒有必要 IAM 許可 AWS 的使用者。 # 適用於 AWS IoT Device Tester 的支援政策 AWS IoT Greengrass AWS IoT Device Tester for AWS IoT Greengrass 是測試自動化工具，用於驗證 AWS IoT Greengrass 您的裝置，並符合[AWS Partner 包含在 Device Catalog](https://devices.amazonaws.com/) 中[的資格](https://aws.amazon.com/partners/dqp/)。我們建議您使用最新版本的 AWS IoT Greengrass 和 AWS IoT Device Tester 來測試或驗證您的裝置。 每個支援的 版本至少 AWS IoT Device Tester 有一個 版本可用 AWS IoT Greengrass。如需支援的 版本 AWS IoT Greengrass，請參閱 [Greengrass 核版本](greengrass-nucleus-component.md#greengrass-nucleus-component-versions)。如需支援的 版本 AWS IoT Device Tester，請參閱 [for AWS IoT Greengrass V2 AWS IoT Device Tester 支援的版本](dev-test-versions.md)。 您也可以使用任何支援的 AWS IoT Greengrass 和 版本 AWS IoT Device Tester 來測試或驗證您的裝置。雖然您可以繼續使用不支援的 版本 AWS IoT Device Tester，但這些版本不會收到錯誤修正或更新。如果您對支援政策有任何疑問，請聯絡 [AWS 支援](https://aws.amazon.com/contact-us/)。