本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # AWS IoT Greengrass 開發工具 使用 AWS IoT Greengrass 開發工具來建立、測試、建置、發佈和部署自訂 Greengrass 元件。 + **[Greengrass 開發套件 CLI](greengrass-development-kit-cli.md)** 在本機開發環境中使用 AWS IoT Greengrass 開發套件命令列界面 (GDK CLI)，從 [Greengrass 軟體目錄中](greengrass-software-catalog.md)的範本和社群元件建立元件。您可以使用 GDK CLI 建置元件，並將元件以私有元件的形式發佈至 AWS IoT Greengrass 服務 AWS 帳戶。 + **[Greengrass 命令列界面](gg-cli.md)** 在 Greengrass 核心裝置上使用 Greengrass Command Line Interface (Greengrass CLI) 來部署和偵錯 Greengrass 元件。Greengrass CLI 是一種元件，您可以部署到核心裝置，以建立本機部署、檢視已安裝元件的詳細資訊，以及探索日誌檔案。 + **[本機偵錯主控台](local-debug-console-component.md)** 使用 Greengrass 核心裝置上的本機偵錯主控台，使用本機儀表板 Web 介面來部署和偵錯 Greengrass 元件。本機偵錯主控台是您可以部署到核心裝置的元件，以建立本機部署並檢視已安裝元件的詳細資訊。 AWS IoT Greengrass 也提供下列 SDKs，您可以在自訂 Greengrass 元件中使用： + AWS IoT Device SDK，其中包含程序間通訊 (IPC) 程式庫。如需詳細資訊，請參閱[使用 AWS IoT Device SDK 與 Greengrass 核、其他元件和 通訊 AWS IoT Core與 Greengrass 核、其他元件和 通訊 AWS IoT Core](interprocess-communication.md)。 + 串流管理員 SDK，可用來將資料串流傳輸至 AWS 雲端。如需詳細資訊，請參閱[管理 Greengrass 核心裝置上的資料串流](manage-data-streams.md)。 **Topics** + [AWS IoT Greengrass 開發套件命令列介面](greengrass-development-kit-cli.md) + [Greengrass 命令列界面](gg-cli.md) + [使用 AWS IoT Greengrass 測試架構](gg-testing-framework.md) # AWS IoT Greengrass 開發套件命令列介面 AWS IoT Greengrass 開發套件命令列界面 (GDK CLI) 提供可協助您開發[自訂 Greengrass 元件](develop-greengrass-components.md)的功能。您可以使用 GDK CLI 來建立、建置和發佈自訂元件。當您使用 GDK CLI 建立元件儲存庫時，您可以從範本或 [Greengrass 軟體目錄中](greengrass-software-catalog.md)的社群元件開始。然後，您可以選擇建置系統，將檔案封裝為 ZIP 封存檔、使用 Maven 或 Gradle 建置指令碼，或執行自訂建置命令。建立元件後，您可以使用 GDK CLI 將其發佈至 AWS IoT Greengrass 服務，以便您可以使用 AWS IoT Greengrass 主控台或 API 將元件部署至 Greengrass 核心裝置。 當您在沒有 GDK CLI 的情況下開發 Greengrass 元件時，每次建立新的元件版本時，都必須更新[元件配方檔案中](component-recipe-reference.md)的版本和成品 URIs。當您使用 GDK CLI 時，它可以在每次發佈新版本的元件時自動為您更新版本和成品 URIs。 GDK CLI 是開放原始碼，可在 GitHub 上使用。您可以自訂和擴展 GDK CLI，以滿足元件開發需求。我們邀請您在 GitHub 儲存庫上開啟問題並提取請求。您可以在以下連結找到 GDK CLI 來源：https：//[https://github.com/aws-greengrass/aws-greengrass-gdk-cli](https://github.com/aws-greengrass/aws-greengrass-gdk-cli)。 ## 先決條件 若要安裝和使用 Greengrass 開發套件 CLI，您需要下列項目： + AWS 帳戶：如果您沒有帳戶，請參閱 [設定 AWS 帳戶](setting-up.md#set-up-aws-account)。 + 具有網際網路連線的 Windows、macOS 或類似 Unix 的開發電腦。 + 對於 GDK CLI 1.1.0 版或更新版本，[Python](https://www.python.org/downloads/) 3.6 或更新版本會安裝在開發電腦上。 對於 GDK CLI 1.0.0 版，[Python](https://www.python.org/downloads/) 3.8 或更新版本安裝在開發電腦上。 + 安裝在開發電腦上的 [Git](https://git-scm.com/)。 + AWS Command Line Interface (AWS CLI) 在開發電腦上安裝並設定 憑證。如需詳細資訊，請參閱*AWS Command Line Interface 《 使用者指南*》中的[安裝、更新和解除安裝 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) 和[設定 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)。 **注意** 如果您使用 Raspberry Pi 或其他 32 位元 ARM 裝置，則 install AWS CLI V1. AWS CLI V2 不適用於 32 位元 ARM 裝置。如需詳細資訊，請參閱[安裝、更新和解除安裝 AWS CLI 版本 1](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv1.html)。 + 若要使用 GDK CLI 將元件發佈至 AWS IoT Greengrass 服務，您必須具有下列許可： + `s3:CreateBucket` + `s3:GetBucketLocation` + `s3:PutObject` + `greengrass:CreateComponentVersion` + `greengrass:ListComponentVersions` + 若要使用 GDK CLI 來建置其成品存在於 S3 儲存貯體而非本機檔案系統中的元件，您必須具有下列許可： + `s3:ListBucket` 此功能適用於 GDK CLI 1.1.0 版及更新版本。 ## 變更記錄 下表說明每個 GDK CLI 版本中的變更。如需詳細資訊，請參閱 GitHub 上的 [GDK CLI 版本頁面](https://github.com/aws-greengrass/aws-greengrass-gdk-cli/releases)。 | **版本** | **變更** | | --- | --- | | 1.6.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.6.1 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.6.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.5.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.4.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.3.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.2.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.2.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.2.1 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.2.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.0.0 | 初始版本。 | # 安裝或更新 AWS IoT Greengrass 開發套件命令列界面 AWS IoT Greengrass 開發套件命令列界面 (GDK CLI) 是以 Python 為基礎，因此您可以使用 `pip`將其安裝在開發電腦上。 **提示** 您也可以在 Python 虛擬環境中安裝 GDK CLI，例如 [venv](https://docs.python.org/3/library/venv.html#module-venv)。如需詳細資訊，請參閱 *Python 3 文件*中的[虛擬環境和套件](https://docs.python.org/3/tutorial/venv.html)。 **安裝或更新 GDK CLI** 1. 執行下列命令，從其 [GitHub 儲存庫](https://github.com/aws-greengrass/aws-greengrass-gdk-cli)安裝最新版本的 GDK CLI。 ``` python3 -m pip install -U git+https://github.com/aws-greengrass/aws-greengrass-gdk-cli.git@v1.6.2 ``` **注意** 若要安裝特定版本的 GDK CLI，請將 *versionTag* 取代為要安裝的版本標籤。您可以在其 [GitHub 儲存庫](https://github.com/aws-greengrass/aws-greengrass-gdk-cli/tags)中檢視 GDK CLI 的版本標籤。 ``` python3 -m pip install -U git+https://github.com/aws-greengrass/aws-greengrass-gdk-cli.git@versionTag ``` 1. 執行下列命令來驗證 GDK CLI 是否已成功安裝。 ``` gdk --help ``` 如果找不到 `gdk`命令，請將其資料夾新增至 PATH。 + 在 Linux 裝置上，將 `/home/MyUser/.local/bin` 新增至 PATH，並以您的使用者名稱取代 *MyUser*。 + 在 Windows 裝置上，將 `PythonPath\\Scripts` 新增至 PATH，並將 *PythonPath* 取代為您裝置上的 Python 資料夾路徑。 您現在可以使用 GDK CLI 來建立、建置和發佈 Greengrass 元件。如需如何使用 GDK CLI 的詳細資訊，請參閱[AWS IoT Greengrass 開發套件命令列界面命令](greengrass-development-kit-cli-commands.md)。 # AWS IoT Greengrass 開發套件命令列界面命令 Development AWS IoT Greengrass Kit Command-Line Interface (GDK CLI) 提供命令列介面，可用於在開發電腦上建立、建置和發佈 Greengrass 元件。GDK CLI 命令使用以下格式。 ``` gdk [arguments] ``` [安裝 GDK CLI](install-greengrass-development-kit-cli.md) 時，安裝程式會`gdk`新增至 PATH，以便您可以從命令列執行 GDK CLI。 您可以搭配任何命令使用下列引數： + 如需 GDK CLI 命令的相關資訊，`--help`請使用 `-h`或 。 + 使用 `-v`或 `--version` 來查看已安裝的 GDK CLI 版本。 + 使用 `-d`或 `--debug`輸出詳細日誌，您可以用來偵錯 GDK CLI。 本節說明 GDK CLI 命令，並提供每個命令的範例。每個命令的摘要會顯示其引數及其用量。選用引數以方括號顯示。 **Topics** + [元件](greengrass-development-kit-cli-component.md) + [config](greengrass-development-kit-cli-config.md) + [test-e2e](greengrass-development-kit-cli-test.md) # 元件 使用 AWS IoT Greengrass 開發套件命令列界面 (GDK CLI) 中的 `component`命令來建立、建置和發佈自訂 Greengrass 元件。 **Topics** + [init](#greengrass-development-kit-cli-component-init) + [build](#greengrass-development-kit-cli-component-build) + [發布](#greengrass-development-kit-cli-component-publish) + [列出](#greengrass-development-kit-cli-component-list) ## init 從元件範本或社群元件初始化 Greengrass 元件資料夾。 GDK CLI 從 [Greengrass 軟體目錄](greengrass-software-catalog.md)擷取社群元件，並從 [AWS IoT Greengrass GitHub 上的元件範本儲存庫擷取元件範本](https://github.com/aws-greengrass/aws-greengrass-component-templates)。 **注意** 如果您使用 GDK CLI 1.0.0 版，您必須在空的資料夾中執行此命令。GDK CLI 會將範本或社群元件下載到目前的資料夾。 如果您使用 GDK CLI 1.1.0 版或更新版本，您可以指定`--name`引數來指定 GDK CLI 下載範本或社群元件的資料夾。如果您使用此引數，請指定不存在的資料夾。GDK CLI 會為您建立 資料夾。如果您未指定此引數，GDK CLI 會使用目前的資料夾，該資料夾必須是空的。 如果元件使用 [zip 組建系統](gdk-cli-configuration-file.md#gdk-cli-configuration-file-build-system)，GDK CLI 會將元件資料夾中的特定檔案壓縮為與元件資料夾名稱相同的 zip 檔案。例如，如果元件資料夾的名稱是 `HelloWorld`，GDK CLI 會建立名為 的 zip 檔案`HelloWorld.zip`。在元件配方中， zip 成品名稱必須符合元件資料夾的名稱。如果您在 Windows 裝置上使用 GDK CLI 1.0.0 版，元件資料夾和 zip 檔案名稱只能包含小寫字母。 如果您將範本或社群元件初始化為使用 zip build 系統的資料夾，其名稱與範本或元件不同，則必須在元件配方中變更 zip 成品名稱。更新 `Artifacts`和 `Lifecycle`定義，讓 zip 檔案名稱符合元件資料夾的名稱。下列範例會反白顯示 `Artifacts`和 `Lifecycle`定義中的 zip 檔案名稱。 ``` { ... "Manifests": [ { "Platform": { "os": "all" }, "Artifacts": [ { "URI": "s3://BUCKET_NAME/COMPONENT_NAME/COMPONENT_VERSION/HelloWorld.zip", "Unarchive": "ZIP" } ], "Lifecycle": { "Run": "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}" } } ] } ``` ``` --- ... Manifests: - Platform: os: all Artifacts: - URI: "s3://BUCKET_NAME/COMPONENT_NAME/COMPONENT_VERSION/HelloWorld.zip" Unarchive: ZIP Lifecycle: Run: "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}" ``` **概要** ``` $ gdk component init [--language] [--template] [--repository] [--name] ``` **引數 （從元件範本初始化）** + `-l`， `--language` – 用於您指定範本的程式設計語言。 您必須指定 `--repository`或 `--language`和 `--template`。 + `-t`， `--template` – 用於本機元件專案的元件範本。若要檢視可用的範本，請使用[清單](#greengrass-development-kit-cli-component-list)命令。 您必須指定 `--repository`或 `--language`和 `--template`。 + `-n`， `--name` – （選用） GDK CLI 初始化元件的本機資料夾名稱。指定不存在的資料夾。GDK CLI 會為您建立 資料夾。 此功能適用於 GDK CLI 1.1.0 版及更新版本。 **引數 （從社群元件初始化）** + `-r`， `--repository` – 要簽出至本機資料夾的社群元件。若要檢視可用的社群元件，請使用 [list](#greengrass-development-kit-cli-component-list) 命令。 您必須指定 `--repository`或 `--language`和 `--template`。 + `-n`， `--name` – （選用） GDK CLI 初始化元件的本機資料夾名稱。指定不存在的資料夾。GDK CLI 會為您建立 資料夾。 此功能適用於 GDK CLI 1.1.0 版及更新版本。 **輸出** 下列範例顯示執行此命令以初始化 Python Hello World 範本中的元件資料夾時產生的輸出。 ``` $ gdk component init -l python -t HelloWorld [2021-11-29 12:51:40] INFO - Initializing the project directory with a python component template - 'HelloWorld'. [2021-11-29 12:51:40] INFO - Fetching the component template 'HelloWorld-python' from Greengrass Software Catalog. ``` 下列範例顯示執行此命令從社群元件初始化元件資料夾時產生的輸出。 ``` $ gdk component init -r aws-greengrass-labs-database-influxdb [2022-01-24 15:44:33] INFO - Initializing the project directory with a component from repository catalog - 'aws-greengrass-labs-database-influxdb'. [2022-01-24 15:44:33] INFO - Fetching the component repository 'aws-greengrass-labs-database-influxdb' from Greengrass Software Catalog. ``` ## build 將元件的來源建置到您可以發佈到服務的配方和成品中 AWS IoT Greengrass 。GDK CLI 會執行您在 [GDK CLI 組態檔案](gdk-cli-configuration-file.md) 中指定的建置系統`gdk-config.json`。您必須在`gdk-config.json`檔案存在的相同資料夾中執行此命令。 當您執行此命令時，GDK CLI 會在元件`greengrass-build`資料夾中的 資料夾中建立配方和成品。GDK CLI 會將配方儲存在 `greengrass-build/recipes` 資料夾中，並將成品儲存在 `greengrass-build/artifacts/componentName/componentVersion` 資料夾中。 如果您使用 GDK CLI 1.1.0 版或更新版本，元件配方可以指定 S3 儲存貯體中存在的成品，但不能指定本機元件建置資料夾中存在的成品。當您開發具有大型成品的元件時，您可以使用此功能來減少頻寬用量，例如機器學習模型。 建置元件之後，您可以執行下列其中一項操作，在 Greengrass 核心裝置上進行測試： + 如果您在與執行 AWS IoT Greengrass Core 軟體不同的裝置上開發 ，則必須發佈元件，將其部署到 Greengrass 核心裝置。將元件發佈至 AWS IoT Greengrass 服務，並將其部署至 Greengrass 核心裝置。如需詳細資訊，請參閱[發佈](#greengrass-development-kit-cli-component-build)命令和 [建立部署](create-deployments.md)。 + 如果您在執行 AWS IoT Greengrass Core 軟體的相同裝置上開發 ，您可以將元件發佈至要部署 AWS IoT Greengrass 的服務，或者您可以建立本機部署來安裝和執行元件。若要建立本機部署，請使用 Greengrass CLI。如需詳細資訊，請參閱 [Greengrass 命令列界面](gg-cli.md) 和 [使用本機部署測試 AWS IoT Greengrass 元件](test-components.md)。當您建立本機部署時，請將 指定`greengrass-build/recipes`為配方資料夾，並將 指定`greengrass-build/artifacts`為成品資料夾。 **概要** ``` $ gdk component build ``` **Arguments (引數)** 無 **輸出** 下列範例顯示執行此命令時產生的輸出。 ``` $ gdk component build [2021-11-29 13:18:49] INFO - Getting project configuration from gdk-config.json [2021-11-29 13:18:49] INFO - Found component recipe file 'recipe.yaml' in the project directory. [2021-11-29 13:18:49] INFO - Building the component 'com.example.PythonHelloWorld' with the given project configuration. [2021-11-29 13:18:49] INFO - Using 'zip' build system to build the component. [2021-11-29 13:18:49] WARNING - This component is identified as using 'zip' build system. If this is incorrect, please exit and specify custom build command in the 'gdk-config.json'. [2021-11-29 13:18:49] INFO - Zipping source code files of the component. [2021-11-29 13:18:49] INFO - Copying over the build artifacts to the greengrass component artifacts build folder. [2021-11-29 13:18:49] INFO - Updating artifact URIs in the recipe. [2021-11-29 13:18:49] INFO - Creating component recipe in 'C:\Users\MyUser\Documents\greengrass-components\python\HelloWorld\greengrass-build\recipes'. ``` ## 發布 將此元件發佈至 AWS IoT Greengrass 服務。此命令會將建置成品上傳至 S3 儲存貯體、更新配方中的成品 URI，以及從配方建立新的版本元件。GDK CLI 使用您在 GDK [CLI 組態檔案中](gdk-cli-configuration-file.md)指定的 S3 儲存貯體和 AWS 區域`gdk-config.json`。您必須在`gdk-config.json`檔案存在的相同資料夾中執行此命令。 如果您使用 GDK CLI 1.1.0 版或更新版本，您可以指定`--bucket`引數來指定 GDK CLI 上傳元件成品的 S3 儲存貯體。如果您未指定此引數，GDK CLI 會上傳到名稱為 的 S3 儲存貯體`bucket-region-accountId`，其中儲存*貯*體和*區域*是您在 中指定的值`gdk-config.json`，而 *accountId* 是您的 AWS 帳戶 ID。如果儲存貯體不存在，GDK CLI 會建立儲存貯體。 如果您使用 GDK CLI 1.2.0 版或更新版本，您可以使用 `--region` 參數覆寫 GDK CLI 組態檔案中 AWS 區域 指定的 。您也可以使用 `--options` 參數指定其他選項。如需可用選項的清單，請參閱 [Greengrass 開發套件 CLI 組態檔案](gdk-cli-configuration-file.md)。 當您執行此命令時，GDK CLI 會使用您在配方中指定的版本發佈元件。如果您指定 `NEXT_PATCH`，GDK CLI 會使用不存在的下一個修補程式版本。語意版本使用 *major*.*minor*.*patch* 編號系統。如需詳細資訊，請參閱[語意版本規格](https://semver.org/)。 **注意** 如果您使用 GDK CLI 1.1.0 版或更新版本，當您執行此命令時，GDK CLI 會檢查元件是否已建置。如果未建置元件，則 GDK CLI [會在發佈元件之前建置](#greengrass-development-kit-cli-component-build)元件。 **概要** ``` $ gdk component publish [--bucket] [--region] [--options] ``` **Arguments (引數)** + `-b`， `--bucket` – （選用） 指定 GDK CLI 發佈元件成品的 S3 儲存貯體名稱。 如果您未指定此引數，GDK CLI 會上傳到名稱為 的 S3 儲存貯體`bucket-region-accountId`，其中儲存*貯*體和*區域*是您在 中指定的值`gdk-config.json`，而 *accountId* 是您的 AWS 帳戶 ID。如果儲存貯體不存在，GDK CLI 會建立儲存貯體。 如果儲存貯體不存在，GDK CLI 會建立儲存貯體。 此功能適用於 GDK CLI 1.1.0 版及更新版本。 + `-r`， `--region` – （選用） 建立元件時，將 的名稱指定 AWS 區域 為 。此引數會覆寫 GDK CLI 組態中的區域名稱。 此功能適用於 GDK CLI 1.2.0 版及更新版本。 + `-o`，`--options`（選用） 指定發佈元件的選項清單。引數必須是有效的 JSON 字串或包含發佈選項的 JSON 檔案路徑。此引數會覆寫 GDK CLI 組態中的選項。 此功能適用於 GDK CLI 1.2.0 版及更新版本。 **輸出** 下列範例顯示執行此命令時產生的輸出。 ``` $ gdk component publish [2021-11-29 13:45:29] INFO - Getting project configuration from gdk-config.json [2021-11-29 13:45:29] INFO - Found component recipe file 'recipe.yaml' in the project directory. [2021-11-29 13:45:29] INFO - Found credentials in shared credentials file: ~/.aws/credentials [2021-11-29 13:45:30] INFO - Publishing the component 'com.example.PythonHelloWorld' with the given project configuration. [2021-11-29 13:45:30] INFO - No private version of the component 'com.example.PythonHelloWorld' exist in the account. Using '1.0.0' as the next version to create. [2021-11-29 13:45:30] INFO - Uploading the component built artifacts to s3 bucket. [2021-11-29 13:45:30] INFO - Uploading component artifacts to S3 bucket: {bucket}. If this is your first time using this bucket, add the 's3:GetObject' permission to each core device's token exchange role to allow it to download the component artifacts. For more information, see https://docs.aws.amazon.com/greengrass/v2/developerguide/device-service-role.html. [2021-11-29 13:45:30] INFO - Not creating an artifacts bucket as it already exists. [2021-11-29 13:45:30] INFO - Updating the component recipe com.example.PythonHelloWorld-1.0.0. [2021-11-29 13:45:30] INFO - Creating a new greengrass component com.example.PythonHelloWorld-1.0.0 [2021-11-29 13:45:30] INFO - Created private version '1.0.0' of the component in the account.'com.example.PythonHelloWorld'. ``` ## 列出 擷取可用元件範本和社群元件的清單。 GDK CLI 從 [Greengrass 軟體目錄](greengrass-software-catalog.md)擷取社群元件，並從 [AWS IoT Greengrass GitHub 上的元件範本儲存庫擷取元件範本](https://github.com/aws-greengrass/aws-greengrass-component-templates)。 您可以將此命令的輸出傳遞至 [init](#greengrass-development-kit-cli-component-init) 命令，以從範本和社群元件初始化元件儲存庫。 **概要** ``` $ gdk component list [--template] [--repository] ``` **Arguments (引數)** + `-t`， `--template` – （選用） 指定此引數以列出可用的元件範本。此命令會以 格式輸出每個範本的名稱和語言`name-language`。例如，在 中`HelloWorld-python`，範本名稱為 `HelloWorld`，語言為 `python`。 + `-r`， `--repository` – （選用） 指定此引數以列出可用的社群元件儲存庫。 **輸出** 下列範例顯示執行此命令時產生的輸出。 ``` $ gdk component list --template [2021-11-29 12:29:04] INFO - Listing all the available component templates from Greengrass Software Catalog. [2021-11-29 12:29:04] INFO - Found '2' component templates to display. 1. HelloWorld-python 2. HelloWorld-java ``` # config 使用 AWS IoT Greengrass 開發套件命令列界面 (GDK CLI) 中的 `config` 命令來修改組態檔案中的 GDK 組態`gdk-config.json`。 **Topics** + [update](#greengrass-development-kit-cli-config-update) ## update 啟動互動式提示來修改現有 GDK 組態檔案中的欄位。 **概要** ``` $ gdk config update [--component] ``` **Arguments (引數)** + `-c`， `--component` – 更新 `gdk-config.json` 檔案中與元件相關的欄位。此引數是必要的，因為它是唯一的選項。 **輸出** 下列範例顯示執行此命令以設定元件時產生的輸出。 ``` $ gdk config update --component Current value of the REQUIRED component_name is (default: com.example.PythonHelloWorld): Current value of the REQUIRED author is (default: author): Current value of the REQUIRED version is (default: NEXT_PATCH): Do you want to change the build configurations? (y/n) Do you want to change the publish configurations? (y/n) [2023-09-26 10:19:48] INFO - Config file has been updated. Exiting... ``` # test-e2e 使用 AWS IoT Greengrass 開發套件命令列界面 (GDK CLI) 中的 `test-e2e`命令，在 GDK 專案中初始化、建置和執行end-to-end測試模組。 **Topics** + [init](#greengrass-development-kit-cli-test-init) + [build](#greengrass-development-kit-cli-test-build) + [run](#greengrass-development-kit-cli-test-run) ## init 使用使用 Greengrass 測試架構 (GTF) 的測試模組初始化現有的 GDK CLI 專案。 根據預設，GDK CLI 會從 [AWS IoT Greengrass GitHub 上的元件範本儲存庫擷取數學模組範本](https://github.com/aws-greengrass/aws-greengrass-component-templates)。此 maven 模組隨附 `aws-greengrass-testing-standalone` JAR 檔案的相依性。 此命令會在 GDK 專案`gg-e2e-tests`內建立新的目錄，稱為 。如果測試模組目錄已存在且不是空的，則命令會結束而不執行任何動作。此`gg-e2e-tests`資料夾包含在 maven 專案中建構的 Cucumber 功能和步驟定義。 根據預設，此命令會嘗試使用最新版本的 GTF。 **概要** ``` $ gdk test-e2e init [--gtf-version] ``` **Arguments (引數)** + `-ov`、 `--gtf-version` – （選用） GTF 的版本，用於 GDK 專案中的end-to-end測試模組。此值必須是版本中的[其中一個 GTF ](https://github.com/aws-greengrass/aws-greengrass-testing/releases)版本。此引數會覆寫 GDK CLI 組態`gtf_version`中的 。 **輸出** 下列範例顯示執行此命令以使用測試模組初始化 GDK 專案時產生的輸出。 ``` $ gdk test-e2e init [2023-12-06 12:20:28] INFO - Using the GTF version provided in the GDK test config 1.2.0 [2023-12-06 12:20:28] INFO - Downloading the E2E testing template from GitHub into gg-e2e-tests directory... ``` ## build **注意** 您必須先執行 來建置元件，**gdk component build**end-to-end測試模組。 建置end-to-end測試模組。GDK CLI 會使用您在 `test-e2e` 屬性下的 [GDK CLI 組態檔案中](gdk-cli-configuration-file.md)指定的建置系統`gdk-config.json`來建置測試模組。您必須在`gdk-config.json`檔案存在的相同資料夾中執行此命令。 根據預設，GDK CLI 會使用 maven 建置系統來建置測試模組。執行 `gdk test-e2e build`命令需要 [Maven](https://maven.apache.org/)。 如果測試功能檔案具有 `GDK_COMPONENT_NAME`和 等變數`GDK_COMPONENT_RECIPE_FILE`來插補，則必須先執行 來建置元件，**gdk-component-build**才能建置測試模組。 當您執行此命令時，GDK CLI 會從 GDK 專案組態插入所有變數，並建置`gg-e2e-tests`模組以產生最終測試 JAR 檔案。 **概要** ``` $ gdk test-e2e build ``` **Arguments (引數)** 無 **輸出** 下列範例顯示執行此命令時產生的輸出。 ``` $ gdk test-e2e build [2023-07-20 15:36:48] INFO - Updating feature file: file:///path/to//HelloWorld/greengrass-build/gg-e2e-tests/src/main/resources/greengrass/features/component.feature [2023-07-20 15:36:48] INFO - Creating the E2E testing recipe file:///path/to/HelloWorld/greengrass-build/recipes/e2e_test_recipe.yaml [2023-07-20 15:36:48] INFO - Building the E2E testing module [2023-07-20 15:36:48] INFO - Running the build command 'mvn package' ......... ``` ## run 使用 GDK 組態檔案中的測試選項執行測試模組。 **注意** 您必須先執行 來建置測試模組，**gdk test-e2e build**end-to-end測試。 **概要** ``` $ gdk test-e2e run [--gtf-options] ``` **Arguments (引數)** + `-oo`， `--gtf-options` – （選用） 指定執行end-to-end測試的選項清單。引數必須是有效的 JSON 字串或包含 GTF 選項的 JSON 檔案路徑。組態檔案中提供的選項會與命令引數中提供的選項合併。如果兩個位置都有 選項，則引數中的一個會比組態檔案中的某個選項有前置。 如果此命令中未指定 `tags`選項，則 GDK 會使用 `Sample`進行標籤。如果`ggc-archive`未指定 ，則 GDK 會下載最新版本的 Greengrass 核封存。 **輸出** 下列範例顯示執行此命令時產生的輸出。 ``` $ gdk test-e2e run [2023-07-20 16:35:53] INFO - Downloading latest nucleus archive from url https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-latest.zip [2023-07-20 16:35:57] INFO - Running test jar with command java -jar /path/to/greengrass-build/gg-e2e-tests/target/uat-features-1.0.0.jar —ggc-archive=/path/to/aws-greengrass-gdk-cli/HelloWorld/greengrass-build/greengrass-nucleus-latest.zip —tags=Sample 16:35:59.693 [] [] [] [INFO] com.aws.greengrass.testing.modules.GreengrassContextModule - Extracting /path/to/workplace/aws-greengrass-gdk-cli/HelloWorld/greengrass-build/greengrass-nucleus-latest.zip into /var/folders/7g/ltzcb_3s77nbtmkzfb6brwv40000gr/T/gg-testing-7718418114158172636/greengrass 16:36:00.534 [gtf-1.1.0-SNAPSHOT] [] [] [INFO] com.aws.greengrass.testing.features.LoggerSteps - GTF Version is gtf-1.1.0-SNAPSHOT ....... ``` # Greengrass 開發套件 CLI 組態檔案 AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) 會從名為 的組態檔案讀取，`gdk-config.json`以建置和發佈元件。此組態檔案必須存在於元件儲存庫的根目錄中。您可以使用 GDK CLI [init 命令](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-init)來使用此組態檔案初始化元件儲存庫。 **Topics** + [GDK CLI 組態檔案格式](#gdk-config-format) + [GDK CLI 組態檔案範例](#gdk-config-examples) ## GDK CLI 組態檔案格式 當您定義元件的 GDK CLI 組態檔案時，請以 JSON 格式指定下列資訊。 `gdk_version` 與此元件相容的 GDK CLI 最低版本。此值必須是 [版本的](https://github.com/aws-greengrass/aws-greengrass-gdk-cli/releases)其中一個 GDK CLI 版本。 `component` 此元件的組態。 `componentName` `author` 元件的作者或發佈者。 `version` 元件的版本。請指定下列其中一項： + `NEXT_PATCH` – 選擇此選項時，GDK CLI 會在您發佈元件時設定版本。GDK CLI 會查詢 AWS IoT Greengrass 服務，以識別元件的最新發佈版本。然後，它會將版本設定為該版本之後的下一個修補程式版本。如果您先前尚未發佈元件，GDK CLI 會使用版本 `1.0.0`。 如果您選擇此選項，則無法使用 [Greengrass CLI](greengrass-cli-component.md) 將元件本機部署和測試到執行 AWS IoT Greengrass Core 軟體的本機開發電腦。若要啟用本機部署，您必須改為指定語意版本。 + 語意版本，例如 **1.0.0**。語意版本使用 *major*.*minor*.*patch* 編號系統。如需詳細資訊，請參閱[語意版本規格](https://semver.org/)。 如果您在想要部署和測試元件的 Greengrass 核心裝置上開發元件，請選擇此選項。您必須使用特定版本建置元件，才能使用 [Greengrass CLI ](greengrass-cli-component.md)建立本機部署。 `build` 用來將此元件的來源建置為成品的組態。此物件包含下列資訊： `build_system` 要使用的建置系統。您可以從以下選項中選擇： + `zip` – 將元件的資料夾封裝為 ZIP 檔案，以定義為元件的唯一成品。針對下列類型的元件選擇此選項： + 使用解譯程式設計語言的元件，例如 Python 或 JavaScript。 + 封裝程式碼以外檔案的元件，例如機器學習模型或其他資源。 GDK CLI 會將元件的資料夾壓縮成與元件資料夾名稱相同的 zip 檔案。例如，如果元件資料夾的名稱為 `HelloWorld`，GDK CLI 會建立名為 的 zip 檔案`HelloWorld.zip`。 **注意** 如果您在 Windows 裝置上使用 GDK CLI 1.0.0 版，元件資料夾和 zip 檔案名稱只能包含小寫字母。 當 GDK CLI 將元件的資料夾壓縮為 zip 檔案時，它會略過下列檔案： + `gdk-config.json` 檔案 + 配方檔案 (`recipe.json` 或 `recipe.yaml`) + 建置資料夾，例如 `greengrass-build` + `maven` – 執行 `mvn clean package`命令，將元件的來源建置為成品。針對使用 [Maven](https://maven.apache.org/) 的元件選擇此選項，例如 Java 元件。 在 Windows 裝置上，此功能適用於 GDK CLI 1.1.0 版及更新版本。 + `gradle` – 執行 `gradle build`命令，將元件的來源建置為成品。針對使用 [Gradle](https://gradle.org/) 的元件選擇此選項。此功能適用於 GDK CLI 1.1.0 版及更新版本。 `gradle` 建置系統支援 Kotlin DSL 做為建置檔案。此功能適用於 GDK CLI 1.2.0 版及更新版本。 + `gradlew` – 執行 `gradlew`命令，將元件的來源建置為成品。針對使用 [Gradle Wrapper ](https://docs.gradle.org/current/userguide/gradle_wrapper.html)的元件選擇此選項。 此功能適用於 GDK CLI 1.2.0 版及更新版本。 + `custom` – 執行自訂命令，將元件的來源建置到配方和成品中。在 `custom_build_command` 參數中指定自訂命令。 `custom_build_command` （選用） 要為自訂建置系統執行的自訂建置命令。如果您`custom`為 指定 ，則必須指定此參數`build_system`。 此命令必須在元件資料夾中的下列資料夾中建立配方和成品。當您執行[元件建置命令](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-build)時，GDK CLI 會為您建立這些資料夾。 + 配方資料夾： `greengrass-build/recipes` + 成品資料夾： `greengrass-build/artifacts/componentName/componentVersion` 將 *componentName* 取代為元件名稱，並將 *componentVersion* 取代為元件版本 或 `NEXT_PATCH`。 您可以指定單一字串或字串清單，其中每個字串都是 命令中的字詞。例如，若要執行 C\$1\$1 元件的自訂建置命令，您可以指定 **cmake --build build --config Release**或 **["cmake", "--build", "build", "--config", "Release"]**。 若要檢視自訂建置系統的範例，請參閱 [aws.greengrass.labs.LocalWebServer community component GitHub 上的](https://github.com/awslabs/aws-greengrass-labs-local-web-server) 。 `options` （選用） 元件建置程序期間使用的其他組態選項。 此功能適用於 GDK CLI 1.2.0 版及更新版本。 `excludes` 定義建置 zip 檔案時要從元件目錄中排除哪些檔案的 glob 模式清單。只有在 `build_system`為 時才有效`zip`。 在 GDK CLI 1.4.0 版及更早版本中，符合排除清單中項目的任何檔案都會從元件的所有子目錄中排除。若要在 GDK CLI 1.5.0 版和更新版本中實現相同的行為，請在排除清單中`**/`的現有項目前面。例如， `*.txt` 只會從 目錄排除文字檔案； `**/*.txt`會從所有目錄和子目錄中排除文字檔案。 在 GDK CLI 1.5.0 版及更新版本中，當 `excludes` GDK 組態檔案中定義 時，您可能會在元件建置期間看到警告。若要停用此警告，請將環境變數`GDK_EXCLUDES_WARN_IGNORE`設定為 `true`。 GDK CLI 一律會從 zip 檔案排除下列檔案： + `gdk-config.json` 檔案 + 配方檔案 (`recipe.json` 或 `recipe.yaml`) + 建置資料夾，例如 `greengrass-build` 預設會排除下列檔案。不過，您可以使用 `excludes`選項來控制哪些檔案遭到排除。 + 任何以字首「測試」開頭的資料夾 (`test*`) + 所有隱藏的檔案 + `node_modules` 資料夾 如果您指定 `excludes`選項，GDK CLI 只會排除您使用 `excludes`選項設定的檔案。如果您未指定 `excludes`選項，GDK CLI 會排除先前記下的預設檔案和資料夾。 `zip_name` 在建置過程中建立 zip 成品時要使用的 zip 檔案名稱。只有在 `build_system`為 時才有效`zip`。如果 `build_system`是空的，元件名稱會用於 zip 檔案名稱。 `publish` 用來將此元件發佈至 AWS IoT Greengrass 服務的組態。 如果您使用 GDK CLI 1.1.0 版或更新版本，您可以指定`--bucket`引數來指定 GDK CLI 上傳元件成品的 S3 儲存貯體。如果您未指定此引數，GDK CLI 會上傳到名稱為 的 S3 儲存貯體`bucket-region-accountId`，其中儲存*貯*體和*區域*是您在 中指定的值`gdk-config.json`，而 *accountId* 是您的 AWS 帳戶 ID。如果儲存貯體不存在，GDK CLI 會建立儲存貯體。 此物件包含下列資訊： `bucket` 用來託管元件成品的 S3 儲存貯體名稱。 `region` GDK CLI 發佈此元件 AWS 區域 的 。 如果您使用 GDK CLI 1.3.0 版或更新版本，則此屬性為選用。 `options` （選用） 元件版本建立期間使用的其他組態選項。 此功能適用於 GDK CLI 1.2.0 版及更新版本。 `file_upload_args` JSON 結構，其中包含在將檔案上傳至儲存貯體時傳送至 Amazon S3 的引數，例如中繼資料和加密機制。如需允許的引數清單，請參閱 Boto3 文件中的 [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/customizations/s3.html#boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/customizations/s3.html#boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS)類別。 *Boto3 * `test-e2e` （選用） 在元件的end-to-end測試期間使用的組態。此功能適用於 GDK CLI 1.3.0 版及更新版本。 `build` `build_system` – 要使用的建置系統。預設選項為 `maven`。您可以從以下選項中選擇： + `maven` – 執行 `mvn package`命令來建置測試模組。選擇此選項來建置使用 [Maven](https://maven.apache.org/) 的測試模組。 + `gradle` – 執行 `gradle build`命令來建置測試模組。針對使用 [Gradle](https://gradle.org/) 的測試模組選擇此選項。 `gtf_version` （選用） 使用 GTF 初始化 GDK 專案時，做為end-to-end測試模組相依性的 Greengrass 測試架構 (GTF) 版本。此值必須是版本中的[其中一個 GTF ](https://github.com/aws-greengrass/aws-greengrass-testing/releases)版本。預設為 GTF 1.1.0 版。 `gtf_options` （選用） 在元件的end-to-end測試期間使用的其他組態選項。 下列清單包含您可以搭配 GTF 1.1.0 版使用的選項。 + `additional-plugins` – （選用） 其他小黃瓜外掛程式 + `aws-region` - 以 AWS 服務的特定區域端點為目標。預設為 AWS SDK 探索的內容。 + `credentials-path` – 選用 AWS 的設定檔登入資料路徑。預設為主機環境上探索的登入資料。 + `credentials-path-rotation` – AWS 登入資料的選用輪換持續時間。預設為 15 分鐘或 `PT15M`。 + `csr-path` – 產生裝置憑證的 CSR 路徑。 + `device-mode` – 正在測試的目標裝置。預設為本機裝置。 + `env-stage` – 以 Greengrass 的部署環境為目標。預設為生產。 + `existing-device-cert-arn` – 您要用作 Greengrass 裝置憑證的現有憑證的生成。 + `feature-path` – 包含其他特徵檔案的檔案或目錄。預設為不使用其他功能檔案。 + `gg-cli-version` – 覆寫 Greengrass CLI 的版本。預設為 中找到的值`ggc.version`。 + `gg-component-bucket` – 存放 Greengrass 元件的現有 Amazon S3 儲存貯體的名稱。 + `gg-component-overrides` – Greengrass 元件覆寫的清單。 + `gg-persist` – 測試執行後要保留的測試元素清單。預設行為是不保留任何內容。接受的值為：`aws.resources`、 `installed.software`和 `generated.files`。 + `gg-runtime` – 影響測試如何與測試資源互動的值清單。這些值會取代 `gg.persist` 參數。如果預設值為空，則假設所有測試資源都由測試案例管理，包括安裝的 Greengrass 執行期。接受的值為：`aws.resources`、 `installed.software`和 `generated.files`。 + `ggc-archive` – 封存 Greengrass 核元件的路徑。 + `ggc-install-root` – 安裝 Greengrass 核元件的目錄。預設為 test.temp.path 和 test run 資料夾。 + `ggc-log-level` – 設定測試執行的 Greengrass 核日誌層級。預設為「INFO」。 + `ggc-tes-rolename` – Core AWS IoT Greengrass 將擔任以存取 AWS 服務的 IAM 角色。如果指定名稱的角色不存在，則會建立一個 和預設存取政策。 + `ggc-trusted-plugins` – 需要新增至 Greengrass 的信任外掛程式路徑 （主機上） 的逗號分隔清單。若要提供 DUT 本身的路徑，請在路徑前面加上 'dut：' + `ggc-user-name` – Greengrass 核的 user：group posixUser 值。預設為目前登入的使用者名稱。 + `ggc-version` – 覆寫執行中 Greengrass 核元件的版本。預設為 ggc.archive 中的值。 + `log-level` – 測試執行的日誌層級。預設為「INFO」。 + `parallel-config` – 批次索引集和批次數量做為 JSON 字串。批次索引的預設值為 0，批次數量為 1。 + `proxy-url` – 設定所有測試以透過此 URL 路由流量。 + `tags` – 僅執行功能標籤。可與 '&' 交集 + `test-id-prefix` – 套用至所有測試特定資源的通用字首，包括 AWS 資源名稱和標籤。預設為「gg」字首。 + `test-log-path` – 將包含整個測試執行結果的目錄。預設為「testResults」。 + `test-results-json` – 標記以判斷是否產生寫入磁碟的 Cucumber JSON 報告。預設為 true。 + `test-results-log` – 用來判斷主控台輸出是否寫入磁碟的旗標。預設為 false。 + `test-results-xml` – 標記以判斷是否產生寫入磁碟的 JUnit XML 報告。預設為 true。 + `test-temp-path` – 產生本機測試成品的目錄。預設為字首為 gg-testing 的隨機暫存目錄。 + `timeout-multiplier` – 提供給所有測試逾時的乘數。預設值為 1.0。 ## GDK CLI 組態檔案範例 您可以參考下列 GDK CLI 組態檔案範例，協助您設定 Greengrass 元件環境。 ### Hello World (Python) 下列 GDK CLI 組態檔案支援執行 Python 指令碼的 Hello World 元件。此組態檔案使用`zip`建置系統，將元件的 Python 指令碼封裝到 ZIP 檔案中，而 GDK CLI 會上傳為成品。 ``` { "component": { "com.example.PythonHelloWorld": { "author": "Amazon", "version": "NEXT_PATCH", "build": { "build_system" : "zip", "options": { "excludes": [".*"] } }, "publish": { "bucket": "greengrass-component-artifacts", "region": "us-west-2", "options": { "file_upload_args": { "Metadata": { "some-key": "some-value" } } } } }, "test-e2e":{ "build":{ "build_system": "maven" }, "gtf_version": "1.1.0", "gtf_options": { "tags": "Sample" } }, "gdk_version": "1.6.1" } } ``` ### Hello World (Java) 下列 GDK CLI 組態檔案支援執行 Java 應用程式的 Hello World 元件。此組態檔案使用`maven`建置系統，將元件的 Java 原始碼封裝到 GDK CLI 上傳為成品的 JAR 檔案。 ``` { "component": { "com.example.JavaHelloWorld": { "author": "Amazon", "version": "NEXT_PATCH", "build": { "build_system" : "maven" }, "publish": { "bucket": "greengrass-component-artifacts", "region": "us-west-2", "options": { "file_upload_args": { "Metadata": { "some-key": "some-value" } } } } }, "test-e2e":{ "build":{ "build_system": "maven" }, "gtf_version": "1.1.0", "gtf_options": { "tags": "Sample" } }, "gdk_version": "1.6.1" } } ``` ### 社群元件 [Greengrass 軟體目錄中](greengrass-software-catalog.md)的數個社群元件使用 GDK CLI。您可以在這些元件的儲存庫中探索 GDK CLI 組態檔案。 **檢視社群元件的 GDK CLI 組態檔案** 1. 執行下列命令，列出使用 GDK CLI 的社群元件。 ``` gdk component list --repository ``` 回應會列出使用 GDK CLI 的每個社群元件的 GitHub 儲存庫名稱。`awslabs` 組織中存在每個儲存庫。 ``` [2022-02-22 17:27:31] INFO - Listing all the available component repositories from Greengrass Software Catalog. [2022-02-22 17:27:31] INFO - Found '6' component repositories to display. 1. aws-greengrass-labs-database-influxdb 2. aws-greengrass-labs-telemetry-influxdbpublisher 3. aws-greengrass-labs-dashboard-grafana 4. aws-greengrass-labs-dashboard-influxdb-grafana 5. aws-greengrass-labs-local-web-server 6. aws-greengrass-labs-lookoutvision-gstreamer ``` 1. 在下列 URL 開啟社群元件的 GitHub 儲存庫。將 *community-component-name* 取代為上一個步驟的社群元件名稱。 ``` https://github.com/awslabs/community-component-name ``` # Greengrass 命令列界面 Greengrass 命令列界面 (CLI) 可讓您與裝置上的 AWS IoT Greengrass Core 互動，在本機開發元件和偵錯問題。例如，您可以使用 Greengrass CLI 來建立本機部署，並重新啟動核心裝置上的元件。 部署 [Greengrass CLI 元件](greengrass-cli-component.md) (`aws.greengrass.Cli`)，在您的核心裝置上安裝 Greengrass CLI。 **重要** 建議您僅在開發環境中使用此元件，而不是在生產環境中。此元件可讓您存取生產環境中通常不需要的資訊和操作。僅將此元件部署到您需要的核心裝置，以遵循最低權限原則。 **Topics** + [安裝 Greengrass CLI](install-gg-cli.md) + [Greengrass CLI 命令](gg-cli-reference.md) # 安裝 Greengrass CLI 您可以使用下列其中一種方式安裝 Greengrass CLI： + 當您第一次在裝置上設定 AWS IoT Greengrass Core 軟體時，請使用 `--deploy-dev-tools`引數。您也必須指定 `--provision true`才能套用此引數。 + 在裝置上部署 Greengrass CLI 元件 (`aws.greengrass.Cli`)。 本節說明部署 Greengrass CLI 元件的步驟。如需有關在初始設定期間安裝 Greengrass CLI 的資訊，請參閱 [教學課程：入門 AWS IoT Greengrass V2](getting-started.md)。 ## 先決條件 若要部署 Greengrass CLI 元件，您必須符合下列要求： + AWS IoT Greengrass 在核心裝置上安裝和設定的核心軟體。如需詳細資訊，請參閱[教學課程：入門 AWS IoT Greengrass V2](getting-started.md)。 + 若要使用 AWS CLI 部署 Greengrass CLI，您必須已安裝並設定 AWS CLI。如需詳細資訊，請參閱《AWS Command Line Interface 使用者指南》中的[設定 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)。 + 您必須獲得使用 Greengrass CLI 與 AWS IoT Greengrass Core 軟體互動的授權。執行下列其中一項操作以使用 Greengrass CLI： + 使用執行 AWS IoT Greengrass Core 軟體的系統使用者。 + 使用具有根或管理許可的使用者。在 Linux 核心裝置上，您可以使用 `sudo` 來取得根許可。 + 當您部署元件時，請使用您在 `AuthorizedPosixGroups`或 `AuthorizedWindowsGroups`組態參數中指定的群組中的系統使用者。如需詳細資訊，請參閱 [Greengrass CLI 元件組態](greengrass-cli-component.md#greengrass-cli-component-configuration)。 ## 部署 Greengrass CLI 元件 完成下列步驟，將 Greengrass CLI 元件部署到您的核心裝置： ### 部署 Greengrass CLI 元件 （主控台） 1. 登入 [AWS IoT Greengrass 主控台](https://console.aws.amazon.com/greengrass)。 1. 在導覽功能表中，選擇**元件**。 1. 在**元面**頁面上的**公用元件**索引標籤上，選擇 `aws.greengrass.Cli`。 1. 在 **aws.greengrass.Cli** 頁面中，選擇**部署**。 1. 從**新增至部署**中，選擇**建立新部署**。 1. 在**指定目標**頁面的**部署目標**下，於**目標名稱**清單中，選擇您要部署的 Greengrass 群組，然後選擇**下一步**。 1. 在**選取元件**頁面上，確認已選取**aws.greengrass.Cli**元件，然後選擇**下一步**。 1. 在**設定元件**頁面上，保留預設組態設定，然後選擇**下一步**。 1. 在**設定進階設定**頁面上，保留預設組態設定，然後選擇**下一步**。 1. 在**檢閱**頁面上，按一下**部署** ### 部署 Greengrass CLI 元件 (AWS CLI) 1. 在您的裝置上，建立 `deployment.json` 檔案以定義 Greengrass CLI 元件的部署組態。此檔案看起來應該如下所示： ``` { "targetArn":"targetArn", "components": { "aws.greengrass.Cli": { "componentVersion": "2.16.1", "configurationUpdate": { "merge": "{\"AuthorizedPosixGroups\":\",,...,\",\"AuthorizedWindowsGroups\":\",,...,\"}" } } } } ``` + 在 `target` 欄位中，`targetArn`以下列格式將物件或物群組的 Amazon Resource Name (ARN) 取代為目標部署： + 物件：`arn:aws:iot:region:account-id:thing/thingName` + 物件群組：`arn:aws:iot:region:account-id:thinggroup/thingGroupName` + 在`aws.greengrass.Cli`元件物件中，指定值，如下所示： `version` Greengrass CLI 元件的版本。 `configurationUpdate.AuthorizedPosixGroups` （選用） 字串，其中包含以逗號分隔的系統群組清單。您授權這些系統群組使用 Greengrass CLI 與 AWS IoT Greengrass Core 軟體互動。您可以指定群組名稱或群組 IDs。例如， 會`group1,1002,group3`授權三個系統群組 (`group1`、 `1002`和 `group3`) 使用 Greengrass CLI。 如果您未指定任何要授權的群組，則可以使用 Greengrass CLI 做為根使用者 (`sudo`) 或執行 AWS IoT Greengrass Core 軟體的系統使用者。 `configurationUpdate.AuthorizedWindowsGroups` （選用） 字串，其中包含以逗號分隔的系統群組清單。您授權這些系統群組使用 Greengrass CLI 與 AWS IoT Greengrass Core 軟體互動。您可以指定群組名稱或群組 IDs。例如， 會`group1,1002,group3`授權三個系統群組 (`group1`、 `1002`和 `group3`) 使用 Greengrass CLI。 如果您未指定任何要授權的群組，則可以使用 Greengrass CLI 做為管理員或執行 AWS IoT Greengrass Core 軟體的系統使用者。 1. 執行下列命令，在裝置上部署 Greengrass CLI 元件： ``` $ aws greengrassv2 create-deployment --cli-input-json file://path/to/deployment.json ``` 在安裝期間，元件會在您裝置上的 `greengrass-cli` `/greengrass/v2/bin` 資料夾中新增符號連結至 ，然後您從此路徑執行 Greengrass CLI。若要在沒有絕對路徑的情況下執行 Greengrass CLI，請將`/greengrass/v2/bin`資料夾新增至 PATH 變數。若要驗證 Greengrass CLI 安裝，請執行下列命令： ------ #### [ Linux or Unix ] ``` /greengrass/v2/bin/greengrass-cli help ``` ------ #### [ Windows ] ``` C:\greengrass\v2\bin\greengrass-cli help ``` ------ 您應該會看到下列輸出： ``` Usage: greengrass-cli [-hV] [--ggcRootPath=] [COMMAND] Greengrass command line interface --ggcRootPath= The AWS IoT Greengrass V2 root directory. -h, --help Show this help message and exit. -V, --version Print version information and exit. Commands: help Show help information for a command. component Retrieve component information and stop or restart components. deployment Create local deployments and retrieve deployment status. logs Analyze Greengrass logs. get-debug-password Generate a password for use with the HTTP debug view component. ``` 如果`greengrass-cli`找不到 ，則部署可能已無法安裝 Greengrass CLI。如需詳細資訊，請參閱[故障診斷 AWS IoT Greengrass V2](troubleshooting.md)。 # Greengrass CLI 命令 Greengrass CLI 提供命令列界面，可在本機與 AWS IoT Greengrass 核心裝置互動。Greengrass CLI 命令使用以下格式。 ``` $ greengrass-cli [arguments] ``` 根據預設， `/greengrass/v2/bin/` 資料夾中的`greengrass-cli`可執行檔會與 `/greengrass/v2` 資料夾中執行 AWS IoT Greengrass 的核心軟體版本互動。如果您呼叫未放置在此位置的可執行檔，或您想要在不同位置與 AWS IoT Greengrass Core 軟體互動，則必須使用下列其中一種方法來明確指定您要互動之 AWS IoT Greengrass Core 軟體的根路徑： + 將 `GGC_ROOT_PATH` 環境變數設為 `/greengrass/v2`。 + 將`--ggcRootPath /greengrass/v2`引數新增至您的命令，如下列範例所示。 ``` greengrass-cli --ggcRootPath /greengrass/v2 [arguments] ``` 您可以搭配任何命令使用下列引數： + 使用 `--help` 以取得特定 Greengrass CLI 命令的相關資訊。 + 使用 `--version` 以取得 Greengrass CLI 版本的相關資訊。 本節說明 Greengrass CLI 命令，並提供這些命令的範例。每個命令的摘要會顯示其引數及其用量。選用引數以方括號顯示。 **Topics** + [元件](gg-cli-component.md) + [部署](gg-cli-deployment.md) + [日誌](gg-cli-logs.md) + [get-debug-password](gg-cli-get-debug-password.md) # 元件 使用 `component`命令與核心裝置上的本機元件互動。 **子命令** + [詳細資訊](#component-details) + [列出](#component-list) + [重新啟動](#component-restart) + [stop](#component-stop) ## 詳細資訊 擷取一個元件的版本、狀態和組態。 **概要** ``` greengrass-cli component details --name ``` **Arguments (引數)** `--name`、`-n`。 元件名稱。 **輸出** 下列範例顯示執行此命令時產生的輸出。 ``` $ sudo greengrass-cli component details --name MyComponent Component Name: MyComponent Version: 1.0.0 State: RUNNING Configuration: null ``` ## 列出 擷取裝置上安裝的每個元件的名稱、版本、狀態和組態。 **概要** ``` greengrass-cli component list ``` **Arguments (引數)** 無 **輸出** 下列範例顯示執行此命令時產生的輸出。 ``` $ sudo greengrass-cli component list Components currently running in Greengrass: Component Name: FleetStatusService Version: 0.0.0 State: RUNNING Configuration: {"periodicUpdateIntervalSec":86400.0} Component Name: UpdateSystemPolicyService Version: 0.0.0 State: RUNNING Configuration: null Component Name: aws.greengrass.Nucleus Version: 2.0.0 State: FINISHED Configuration: {"awsRegion":"region","runWithDefault":{"posixUser":"ggc_user:ggc_group"},"telemetry":{}} Component Name: DeploymentService Version: 0.0.0 State: RUNNING Configuration: null Component Name: TelemetryAgent Version: 0.0.0 State: RUNNING Configuration: null Component Name: aws.greengrass.Cli Version: 2.0.0 State: RUNNING Configuration: {"AuthorizedPosixGroups":"ggc_user"} ``` ## 重新啟動 重新啟動元件。 **概要** ``` greengrass-cli component restart --names ,... ``` **Arguments (引數)** `--names`、`-n`。 元件名稱。至少需要一個元件名稱。您可以指定其他元件名稱，以逗號分隔每個名稱。 **輸出** 無 ## stop 停止執行元件。 **概要** ``` greengrass-cli component stop --names ,... ``` **Arguments (引數)** `--names`、`-n`。 元件名稱。至少需要一個元件名稱。您可以視需要指定其他元件名稱，以逗號分隔每個名稱。 **輸出** 無 # 部署 使用 `deployment`命令與核心裝置上的本機元件互動。 若要監控本機部署的進度，請使用 `status`子命令。您無法使用 主控台監控本機部署的進度。 **子命令** + [建立](#deployment-create) + [取消](#deployment-cancel) + [列出](#deployment-list) + [status](#deployment-status) ## 建立 使用指定的元件配方、成品和執行期引數建立或更新本機部署。 **概要** ``` greengrass-cli deployment create --recipeDir path/to/component/recipe [--artifactDir path/to/artifact/folder ] [--update-config {component-configuration}] [--groupId ] [--merge "="]... [--runWith ":posixUser=[:]"]... [--systemLimits "{component-system-resource-limits}]"]... [--remove ,...] [--failure-handling-policy ] ``` **Arguments (引數)** + `--recipeDir`、`-r`。 包含元件配方檔案之資料夾的完整路徑。 + `--artifactDir`、`-a`。 資料夾的完整路徑，其中包含您要包含在部署中的成品檔案。成品資料夾必須包含下列目錄結構： ``` /path/to/artifact/folder/// ``` + `--update-config`、`-c`。 部署的組態引數，以 JSON 字串或 JSON 檔案的形式提供。JSON 字串的格式應該如下： ``` { \ "componentName": { \ "MERGE": {"config-key": "config-value"}, \ "RESET": ["path/to/reset/"] \ } \ } ``` `MERGE` 和 區分`RESET`大小寫，且必須是大寫。 + `--groupId`、`-g`。 部署的目標物件群組。 + `--merge`、`-m`。 您要新增或更新的目標元件名稱和版本。您必須以 格式提供元件資訊`=`。為每個要指定的額外元件使用單獨的引數。如有需要，請使用 `--runWith`引數提供執行元件的 `posixGroup`、 `posixUser`和 `windowsUser`資訊。 + `--runWith`。 執行一般或 Lambda 元件的 `posixUser``posixGroup`、 和 `windowsUser`資訊。您必須以 格式提供此資訊`:{posixUser|windowsUser}=[:<=posixGroup>]`。例如，您可以指定 **HelloWorld:posixUser=ggc\$1user:ggc\$1group**或 **HelloWorld:windowsUser=ggc\$1user**。為每個要指定的其他選項使用單獨的引數。 如需詳細資訊，請參閱[設定執行元件的使用者](configure-greengrass-core-v2.md#configure-component-user)。 + `--systemLimits`。 系統資源限制，適用於核心裝置上的一般和非容器 Lambda 元件程序。您可以設定每個元件程序可以使用的 CPU 和 RAM 用量上限。指定序列化 JSON 物件或 JSON 檔案的檔案路徑。JSON 物件必須具有下列格式。 ``` { \ "componentName": { \ "cpus": cpuTimeLimit, \ "memory": memoryLimitInKb \ } \ } ``` 您可以為每個元件設定下列系統資源限制： + `cpus` – 此元件的程序可在核心裝置上使用的 CPU 時間上限。核心裝置的 CPU 總時間等於裝置的 CPU 核心數。例如，在具有 4 個 CPU 核心的核心裝置上，您可以將此值設定為 `2`，以將此元件的程序限制為每個 CPU 核心的 50% 用量。在具有 1 個 CPU 核心的裝置上，您可以將此值設定為 `0.25`，以將此元件的程序限制為 CPU 的 25% 用量。如果您將此值設定為大於 CPU 核心數量的數字，則 AWS IoT Greengrass Core 軟體不會限制元件的 CPU 用量。 + `memory` – 此元件的程序可在核心裝置上使用的 RAM 數量上限 （以 KB 為單位）。 如需詳細資訊，請參閱[設定元件的系統資源限制](configure-greengrass-core-v2.md#configure-component-system-resource-limits)。 此功能適用於 Linux 核心裝置上的 [Greengrass 核元件](greengrass-nucleus-component.md)和 Greengrass CLI 的 v2.4.0 和更新版本。目前 AWS IoT Greengrass 不支援 Windows 核心裝置上的此功能。 + `--remove`。 您要從本機部署中移除的目標元件名稱。若要移除從雲端部署合併的元件，您必須以下列格式提供目標物件群組的群組 ID： ------ #### [ Greengrass nucleus v2.4.0 and later ] ``` --remove --groupId ``` ------ #### [ Earlier than v2.4.0 ] ``` --remove --groupId thinggroup/ ``` ------ + `--failure-handling-policy`。 定義部署失敗時所採取的動作。您可以指定兩個動作： + `ROLLBACK` – + `DO_NOTHING` – 此功能適用於 的 v2.11.0 和更新版本。 [Greengrass 核](greengrass-nucleus-component.md) **輸出** 下列範例顯示執行此命令時產生的輸出。 ``` $ sudo greengrass-cli deployment create \ --merge MyApp1=1.0.0 \ --merge MyApp2=1.0.0 --runWith MyApp2:posixUser=ggc_user \ --remove MyApp3 \ --recipeDir recipes/ \ --artifactDir artifacts/ Local deployment has been submitted! Deployment Id: 44d89f46-1a29-4044-ad89-5151213dfcbc ``` ## 取消 取消指定的部署。 概要 ``` greengrass-cli deployment cancel -i ``` 引數 `-i`。 要取消之部署的唯一識別符。部署 ID 會在 `create`命令的輸出中傳回。 輸出 + 無 ## 列出 擷取最近 10 個本機部署的狀態。 **概要** ``` greengrass-cli deployment list ``` **Arguments (引數)** 無 **輸出** 下列範例顯示執行此命令時產生的輸出。根據您的部署狀態，輸出會顯示下列其中一個狀態值：`SUCCEEDED`、 `IN_PROGRESS`或 `FAILED`。 ``` $ sudo greengrass-cli deployment list 44d89f46-1a29-4044-ad89-5151213dfcbc: SUCCEEDED Created on: 6/27/23 11:05 AM ``` ## status 擷取特定部署的狀態。 **概要** ``` greengrass-cli deployment status -i ``` **Arguments (引數)** `-i`。 部署的 ID。 **輸出** 下列範例顯示執行此命令時產生的輸出。根據您的部署狀態，輸出會顯示下列其中一個狀態值：`SUCCEEDED`、 `IN_PROGRESS`或 `FAILED`。 ``` $ sudo greengrass-cli deployment status -i 44d89f46-1a29-4044-ad89-5151213dfcbc 44d89f46-1a29-4044-ad89-5151213dfcbc: FAILED Created on: 6/27/23 11:05 AM Detailed Status: Deployment Error Stack: List of error codes Deployment Error Types: List of error types Failure Cause: Cause ``` # 日誌 使用 `logs`命令來分析核心裝置上的 Greengrass 日誌。 **子命令** + [get](#logs-get) + [list-keywords](#logs-list-keywords) + [list-log-files](#logs-list-log-files) ## get 收集、篩選和視覺化 Greengrass 日誌檔案。此命令僅支援 JSON 格式的日誌檔案。您可以在 核組態中指定[記錄格式](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-logging-format)。 **概要** ``` greengrass-cli logs get [--log-dir path/to/a/log/folder] [--log-file path/to/a/log/file] [--follow true | false ] [--filter ] [--time-window , ] [--verbose ] [--no-color ] [--before ] [--after ] [--syslog ] [--max-long-queue-size ] ``` **Arguments (引數)** + `--log-dir`、`-ld`。 要檢查日誌檔案的目錄路徑，例如 **`/greengrass/v2`/logs**。請勿與 搭配使用`--syslog`。為每個要指定的額外目錄使用單獨的引數。您必須使用 `--log-dir`或 中的至少一個`--log-file`。您也可以在單一命令中使用兩個引數。 + `--log-file`、`-lf`。 您要使用的日誌目錄路徑。為每個要指定的額外目錄使用單獨的引數。您必須使用 `--log-dir`或 中的至少一個`--log-file`。您也可以在單一命令中使用兩個引數。 + `--follow`、`-fol`。 在日誌更新發生時顯示日誌更新。Greengrass CLI 會繼續執行並從指定的日誌讀取。如果您指定時段，則 Greengrass CLI 會在所有時段結束後停止監控日誌。 + `--filter`、`-f`。 要用作篩選條件的關鍵字、規則運算式或鍵值對。將此值提供為字串、規則表達式或索引鍵/值對。為每個要指定的額外篩選條件使用單獨的引數。 評估時，單一引數中指定的多個篩選條件會由 OR 運算子分隔，而其他引數中指定的篩選條件則會與 AND 運算子合併。例如，如果您的命令包含 `--filter "installed" --filter "name=alpha,name=beta"`，則 Greengrass CLI 將篩選和顯示包含關鍵字`installed`和具有 `alpha`或 值的`name`金鑰的日誌訊息`beta`。 + `--time-window`、`-t`。 要顯示日誌資訊的時間範圍。您可以同時使用確切的時間戳記和相對位移。您必須以 格式提供此資訊`,`。如果您未指定開始時間或結束時間，則該選項的值會預設為目前的系統日期和時間。為每個要指定的額外時段使用單獨的引數。 Greengrass CLI 支援下列時間戳記格式： + `yyyy-MM-DD`，例如 `2020-06-30`。當您使用此格式時，時間預設為 00：00：00。 `yyyyMMDD`，例如 `20200630`。當您使用此格式時，時間預設為 00：00：00。 `HH:mm:ss`，例如 `15:30:45`。當您使用此格式時，日期預設為目前的系統日期。 `HH:mm:ssSSS`，例如 `15:30:45`。當您使用此格式時，日期預設為目前的系統日期。 `YYYY-MM-DD'T'HH:mm:ss'Z'`，例如 `2020-06-30T15:30:45Z`。 `YYYY-MM-DD'T'HH:mm:ss`，例如 `2020-06-30T15:30:45`。 `yyyy-MM-dd'T'HH:mm:ss.SSS`，例如 `2020-06-30T15:30:45.250`。 相對偏移會指定與目前系統時間的時段偏移。Greengrass CLI 支援下列格式的相對偏移：`+|-[h|hr|hours][valuem|min|minutes][value]s|sec|seconds`。 例如，下列引數指定目前時間 1 小時到 2 小時 15 分鐘之間的時間範圍`--time-window -2h15min,-1hr`。 + `--verbose`。 顯示日誌訊息中的所有欄位。請勿與 搭配使用`--syslog`。 + `--no-color`、`-nc`。 移除顏色編碼。日誌訊息的預設顏色編碼使用粗體紅色文字。僅支援類似 UNIX 的終端機，因為它使用 ANSI 逸出序列。 + `--before`、`-b`。 在相符的日誌項目前面顯示的行數。預設值為 0。 + `--after`、`-a`。 在相符的日誌項目之後顯示的行數。預設值為 0。 + `--syslog`。 使用 RFC3164 定義的 syslog 通訊協定來處理所有日誌檔案。請勿搭配 `--log-dir`和 使用 `--verbose`。syslog 通訊協定使用以下格式：`"<$Priority>$Timestamp $Host $Logger ($Class): $Message"`。如果您未指定日誌檔案，則 Greengrass CLI 會從下列位置讀取日誌訊息：`/var/log/messages`、 `/var/log/syslog`或 `/var/log/system.log`。 AWS IoT Greengrass 目前不支援 Windows 核心裝置上的此功能。 + `--max-log-queue-size`、`-m`。 要配置到記憶體的日誌項目數目上限。使用此選項可最佳化記憶體用量。預設為 100。 **輸出** 下列範例顯示執行此命令時產生的輸出。 ``` $ sudo greengrass-cli logs get --verbose \ --log-file /greengrass/v2/logs/greengrass.log \ --filter deployment,serviceName=DeploymentService \ --filter level=INFO \ --time-window 2020-12-08T01:11:17,2020-12-08T01:11:22 2020-12-08T01:11:17.615Z [INFO] (pool-2-thread-14) com.aws.greengrass.deployment.DeploymentService: Current deployment finished. {DeploymentId=44d89f46-1a29-4044-ad89-5151213dfcbc, serviceName=DeploymentService, currentState=RUNNING} 2020-12-08T01:11:17.675Z [INFO] (pool-2-thread-14) com.aws.greengrass.deployment.IotJobsHelper: Updating status of persisted deployment. {Status=SUCCEEDED, StatusDetails={detailed-deployment-status=SUCCESSFUL}, ThingName=MyThing, JobId=22d89f46-1a29-4044-ad89-5151213dfcbc ``` ## list-keywords 顯示建議的關鍵字，您可以用來篩選日誌檔案。 **概要** ``` greengrass-cli logs list-keywords [arguments] ``` **Arguments (引數)** 無 **輸出** 下列範例顯示執行此命令時產生的輸出。 ``` $ sudo greengrass-cli logs list-keywords Here is a list of suggested keywords for Greengrass log: level=$str thread=$str loggerName=$str eventType=$str serviceName=$str error=$str ``` ``` $ sudo greengrass-cli logs list-keywords --syslog Here is a list of suggested keywords for syslog: priority=$int host=$str logger=$str class=$str ``` ## list-log-files 顯示位於指定目錄中的日誌檔案。 **概要** ``` greengrass-cli logs list-log-files [arguments] ``` **Arguments (引數)** `--log-dir`、`-ld`。 要檢查日誌檔案的目錄路徑。 **輸出** 下列範例顯示執行此命令時產生的輸出。 ``` $ sudo greengrass-cli logs list-log-files -ld /greengrass/v2/logs/ /greengrass/v2/logs/aws.greengrass.Nucleus.log /greengrass/v2/logs/main.log /greengrass/v2/logs/greengrass.log Total 3 files found. ``` # get-debug-password 使用 `get-debug-password`命令來為[本機偵錯主控台元件](local-debug-console-component.md) () 列印隨機產生的密碼`aws.greengrass.LocalDebugConsole`。密碼會在產生後 8 小時過期。 **概要** ``` greengrass-cli get-debug-password ``` **Arguments (引數)** 無 **輸出** 下列範例顯示執行此命令時產生的輸出。 ``` $ sudo greengrass-cli get-debug-password Username: debug Password: bEDp3MOHdj8ou2w5de_sCBI2XAaguy3a8XxREXAMPLE Password expires at: 2021-04-01T17:01:43.921999931-07:00 The local debug console is configured to use TLS security. The certificate is self-signed so you will need to bypass your web browser's security warnings to open the console. Before you bypass the security warning, verify that the certificate fingerprint matches the following fingerprints. SHA-256: 15 0B 2C E2 54 8B 22 DE 08 46 54 8A B1 2B 25 DE FB 02 7D 01 4E 4A 56 67 96 DA A6 CC B1 D2 C4 1B SHA-1: BC 3E 16 04 D3 80 70 DA E0 47 25 F9 90 FA D6 02 80 3E B5 C1 ``` # 使用 AWS IoT Greengrass 測試架構 Greengrass 測試架構 (GTF) 是支援從客戶角度end-to-end自動化的建置區塊集合。GTF 使用 [Cucumber](https://cucumber.io) 做為功能驅動程式。 AWS IoT Greengrass 會使用相同的建置區塊來驗證各種裝置上的軟體變更。如需詳細資訊，請參閱 [Github 上的 Greengrass 測試架構](https://github.com/aws-greengrass/aws-greengrass-testing/tree/dev_v1)。 GTF 使用 Cucumber 實作，這是用來執行自動化測試的工具，可鼓勵元件的行為驅動開發 (BDD)。在 Cucumber 中，此系統的功能概述於稱為 的特殊檔案類型中`feature`。每個功能都以稱為案例的人類可讀格式描述，這些案例是可轉換為自動化測試的規格。每個案例都概述為一系列步驟，使用稱為 Gherkin 的網域特定語言來定義此系統的互動和結果。[Gherkin 步驟](https://cucumber.io/docs/gherkin/reference/#steps)會使用稱為步驟定義的方法連結至程式設計程式碼，該方法將規格硬式路由至測試流程。GTF 中的步驟定義是使用 Java 實作。 **Topics** + [運作方式](#gg-testing-framework-how-gtf-works) + [變更記錄](#gtf-changelog) + [Greengrass 測試架構組態選項](configuration-options-gtf.md) + [教學課程：使用 Greengrass 測試架構和 Greengrass 開發套件執行end-to-end測試](run-e2e-tests-tutorial.md) + [教學課程：使用可信度測試套件中的可信度測試](confidence-tests-tutorial.md) ## 運作方式 AWS IoT Greengrass 會將 GTF 分發為由數個 Java 模組組成的獨立 JAR。若要使用 GTF end-to-end測試，您必須在 Java 專案中實作測試。在 Java 專案中新增測試可站立的 JAR 做為相依性，可讓您使用 GTF 的現有功能，並透過撰寫自己的自訂測試案例來擴展它。若要執行自訂測試案例，您可以建置 Java 專案，並使用中所述的組態選項執行目標 JAR[Greengrass 測試架構組態選項](configuration-options-gtf.md)。 ### GTF 獨立 JAR Greengrass 使用 Cloudfront 做為 [Maven](https://maven.apache.org/) 儲存庫來託管不同版本的 GTF 獨立 JAR。如需 GTF 版本的完整清單，請參閱 [GTF 版本](https://github.com/aws-greengrass/aws-greengrass-testing/releases)。 GTF 獨立 JAR 包含下列模組。這不限於這些模組。您可以分別在專案中挑選和選擇每個相依性，或使用[測試獨立 JAR 檔案](https://github.com/aws-greengrass/aws-greengrass-testing/tree/dev_v1/aws-greengrass-testing-standalone)同時包含所有相依性。 + `aws-greengrass-testing-resources`：本單元提供在測試過程中管理 AWS 資源生命週期的抽象概念。您可以使用此參數來定義自訂 AWS 資源，以便 GTF `ResourceSpec` 為您建立和移除這些資源。 + `aws-greengrass-testing-platform`：此模組會在測試生命週期期間為待測裝置提供平台層級抽象。它包含 API， APIs 用於與獨立於 平台的作業系統互動，並可用於模擬在裝置 shell 中執行的命令。 + `aws-greengrass-testing-components`：此模組包含用於測試 Greengrass 核心功能的範例元件，例如部署、IPC 和其他功能。 + `aws-greengrass-testing-features`：此模組包含可重複使用的常見步驟及其定義，用於在 Greengrass 環境中測試 內的 。 **Topics** + [運作方式](#gg-testing-framework-how-gtf-works) + [變更記錄](#gtf-changelog) + [Greengrass 測試架構組態選項](configuration-options-gtf.md) + [教學課程：使用 Greengrass 測試架構和 Greengrass 開發套件執行end-to-end測試](run-e2e-tests-tutorial.md) + [教學課程：使用可信度測試套件中的可信度測試](confidence-tests-tutorial.md) ## 變更記錄 下表說明 GTF 每個版本中的變更。如需詳細資訊，請參閱 GitHub 上的 [GTF 版本頁面](https://github.com/aws-greengrass/aws-greengrass-testing/releases)。 | **版本** | **變更** | | --- | --- | | 1.2.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/gg-testing-framework.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/gg-testing-framework.html) | | 1.1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/gg-testing-framework.html) | | 1.0.0 | 初始版本。 | # Greengrass 測試架構組態選項 ## GTF 組態選項 Greengrass 測試架構 (GTF) 可讓您在end-to-end測試程序啟動期間設定特定參數，以協調測試流程。您可以將這些組態選項指定為 GTF 獨立 JAR 的 CLI 引數。 GTF 1.1.0 版及更新版本提供下列組態選項。 + `additional-plugins` – （選用） 其他小黃瓜外掛程式 + `aws-region` – 以服務的特定區域端點為 AWS 目標。預設為 AWS SDK 探索的內容。 + `credentials-path` – 選用 AWS 的設定檔登入資料路徑。預設為主機環境上探索的登入資料。 + `credentials-path-rotation` – 登入資料的 AWS 選用輪換持續時間。預設為 15 分鐘或 `PT15M`。 + `csr-path` – 產生裝置憑證的 CSR 路徑。 + `device-mode` – 正在測試的目標裝置。預設為本機裝置。 + `env-stage` – 以 Greengrass 的部署環境為目標。預設為生產。 + `existing-device-cert-arn` – 您要用來做為 Greengrass 裝置憑證的現有憑證。 + `feature-path` – 包含其他特徵檔案的檔案或目錄。預設為不使用其他功能檔案。 + `gg-cli-version` – 覆寫 Greengrass CLI 的版本。預設為 中找到的值`ggc.version`。 + `gg-component-bucket` – 存放 Greengrass 元件的現有 Amazon S3 儲存貯體的名稱。 + `gg-component-overrides` – Greengrass 元件覆寫的清單。 + `gg-persist` – 測試執行後要保留的測試元素清單。預設行為是不保留任何內容。接受的值為：`aws.resources`、 `installed.software`和 `generated.files`。 + `gg-runtime` – 影響測試如何與測試資源互動的值清單。這些值會取代 `gg.persist` 參數。如果預設值為空，則假設所有測試資源都由測試案例管理，包括安裝的 Greengrass 執行期。接受的值為：`aws.resources`、 `installed.software`和 `generated.files`。 + `ggc-archive` – 封存 Greengrass 核元件的路徑。 + `ggc-install-root` – 安裝 Greengrass 核元件的目錄。預設為 test.temp.path 和 test run 資料夾。 + `ggc-log-level` – 設定測試執行的 Greengrass 核日誌層級。預設為「INFO」。 + `ggc-tes-rolename` – Core AWS IoT Greengrass 將擔任以存取 AWS 服務的 IAM 角色。如果指定名稱的角色不存在，則會建立一個角色和預設存取政策。 + `ggc-trusted-plugins` – 需要新增至 Greengrass 的信任外掛程式路徑 （主機上） 的逗號分隔清單。若要提供 DUT 本身的路徑，請在路徑前面加上 'dut：' + `ggc-user-name` – Greengrass 核的 user：group posixUser 值。預設為目前登入的使用者名稱。 + `ggc-version` – 覆寫執行中 Greengrass 核元件的版本。預設為 ggc.archive 中的值。 + `log-level` – 測試執行的日誌層級。預設為「INFO」。 + `parallel-config` – 批次索引和批次數量的集合，做為 JSON 字串。批次索引的預設值為 0，批次數量為 1。 + `proxy-url` – 設定所有測試以透過此 URL 路由流量。 + `tags` – 僅執行功能標籤。可與 '&' 交集 + `test-id-prefix` – 套用至所有測試特定資源的通用字首，包括 AWS 資源名稱和標籤。預設為「gg」字首。 + `test-log-path` – 將包含整個測試執行結果的目錄。預設為「testResults」。 + `test-results-json` – 標記以判斷是否產生寫入磁碟的 Cucumber JSON 報告。預設為 true。 + `test-results-log` – 用來判斷主控台輸出是否寫入磁碟的旗標。預設為 false。 + `test-results-xml` – 標記以判斷是否產生寫入磁碟的 JUnit XML 報告。預設為 true。 + `test-temp-path` – 產生本機測試成品的目錄。預設為字首為 gg 測試的隨機暫存目錄。 + `timeout-multiplier` – 提供給所有測試逾時的乘數。預設值為 1.0。 # 教學課程：使用 Greengrass 測試架構和 Greengrass 開發套件執行end-to-end測試 AWS IoT Greengrass 測試架構 (GTF) 和 Greengrass 開發套件 (GDK) 為開發人員提供執行end-to-end測試的方法。您可以完成此教學課程，以使用元件初始化 GDK 專案、使用end-to-end測試模組初始化 GDK 專案，以及建置自訂測試案例。建置自訂測試案例之後，您就可以執行測試。 在此教學課程中，您將執行下列操作： 1. 使用元件初始化 GDK 專案。 1. 使用end-to-end測試模組初始化 GDK 專案。 1. 建置自訂測試案例。 1. 將標籤新增至新的測試案例。 1. 建置測試 JAR。 1. 執行 測試。 **Topics** + [先決條件](#run-e2e-tests-tutorial-prerequisites) + [步驟 1：使用元件初始化 GDK 專案](#init-gdk-with-component) + [步驟 2：使用end-to-end測試模組初始化 GDK 專案](#init-gdk-with-e2e-test) + [步驟 3：建置自訂測試案例](#run-e2e-tests-tutorial-instructions) + [步驟 4：將標籤新增至新的測試案例](#add-tag-to-test-case) + [步驟 5：建置測試 JAR](#build-test-jar) + [步驟 6：執行測試](#run-test-gtf) + [範例：建置自訂測試案例](#build-test-case-example) ## 先決條件 為了完成本教學，您需要以下項目： + GDK 1.3.0 版或更新版本 + Java + Maven + Git ## 步驟 1：使用元件初始化 GDK 專案 + 使用 GDK 專案初始化空資料夾。執行下列命令，下載在 Python 中實作的`HelloWorld`元件。 ``` gdk component init -t HelloWorld -l python -n HelloWorld ``` 此命令`HelloWorld`會在目前目錄中建立名為 的新目錄。 ## 步驟 2：使用end-to-end測試模組初始化 GDK 專案 + GDK 可讓您下載由功能和步驟實作組成的測試模組範本。執行下列命令以開啟 `HelloWorld` 目錄，並使用測試模組初始化現有的 GDK 專案。 ``` cd HelloWorld gdk test-e2e init ``` 此命令會在 目錄中建立新的名為 `gg-e2e-tests`的`HelloWorld`目錄。此測試目錄是 [Maven](https://maven.apache.org/) 專案，其相依於 Greengrass 測試獨立 JAR。 ## 步驟 3：建置自訂測試案例 撰寫自訂測試案例廣泛包含兩個步驟：使用測試案例建立特徵檔案並實作步驟定義。如需建置自訂測試案例的範例，請參閱 [範例：建置自訂測試案例](#build-test-case-example)。使用下列步驟來建置您的自訂測試案例： 1. 使用測試案例建立特徵檔案 功能通常會描述正在測試之軟體的特定功能。在 Cucumber 中，每個功能都會指定為個別功能檔案，其中包含標題、詳細說明，以及一或多個稱為案例的特定案例範例。每個案例都包含標題、詳細說明，以及定義互動和預期結果的一系列步驟。使用 "given"、"when" 和 "then" 關鍵字以結構化格式撰寫案例。 1. 實作步驟定義 步驟定義以純語言將 [Gherkin 步驟](https://cucumber.io/docs/gherkin/reference/#steps)連結至程式設計程式碼。當 Cucumber 在案例中識別 Gherkin 步驟時，它會尋找要執行的相符步驟定義。 ## 步驟 4：將標籤新增至新的測試案例 + 您可以將標籤指派給特徵和案例，以組織測試程序。您可以使用標籤來分類案例子集，也可以依條件選取要執行的勾點。功能和案例可以有多個以空格分隔的標籤。 在此範例中，我們使用 `HelloWorld`元件。 在特徵檔案中，在標籤`@HelloWorld`旁新增名為 的新`@Sample`標籤。 ``` @Sample @HelloWorld Scenario: As a developer, I can create a component and deploy it on my device .... ``` ## 步驟 5：建置測試 JAR 1. 建置 元件。您必須先建置元件，才能建置測試模組。 ``` gdk component build ``` 1. 使用以下命令建置測試模組。此命令將在 `greengrass-build` 資料夾中建置測試 JAR。 ``` gdk test-e2e build ``` ## 步驟 6：執行測試 當您執行自訂測試案例時，GTF 會自動執行測試的生命週期，並管理測試期間建立的資源。它會先佈建待測裝置 (DUT) 做為 AWS IoT 物件，並在其上安裝 Greengrass 核心軟體。然後，它會`HelloWorld`使用該路徑中指定的配方來建立新的名為 的元件。然後，`HelloWorld`元件會透過 Greengrass 物件部署部署到核心裝置上。如果部署成功，則會對其進行驗證。如果部署成功，部署狀態會在 `COMPLETED` 3 分鐘內變更為 。 1. 前往專案目錄中的 `gdk-config.json` 檔案，以 `HelloWorld`標籤鎖定測試目標。使用下列命令更新`test-e2e`金鑰。 ``` "test-e2e":{ "gtf_options" : { "tags":"HelloWorld" } } ``` 1. 執行測試之前，您必須提供 AWS 登入資料給主機裝置。GTF 會在測試過程中使用這些登入資料來管理 AWS 資源。請確定您提供的角色具有許可，可自動化測試中包含的必要操作。 執行下列命令以提供 AWS 登入資料。 1. ------ #### [ Linux or Unix ] ``` export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY ``` ------ #### [ Windows Command Prompt (CMD) ] ``` set AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE set AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY ``` ------ #### [ PowerShell ] ``` $env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE" $env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" ``` ------ 1. 使用以下命令執行測試。 ``` gdk test-e2e run ``` 此命令會在 `greengrass-build` 資料夾中下載最新版本的 Greengrass 核，並使用它執行測試。此命令也會僅以具有 `HelloWorld`標籤的案例為目標，並產生這些案例的報告。您會在測試結束時看到在此測試期間建立 AWS 的資源遭到捨棄。 ## 範例：建置自訂測試案例 **Example** GDK 專案中下載的測試模組包含範例功能和步驟實作檔案。 在下列範例中，我們會建立功能檔案，以測試 Greengrass 軟體的物件部署功能。我們會使用透過 Greengrass 部署元件的案例來部分測試此功能的功能 AWS 雲端。這是一系列步驟，可協助我們了解此使用案例的互動和預期結果。 1. **建立特徵檔案** 導覽至目前目錄中的 `gg-e2e-tests/src/main/resources/greengrass/features` 資料夾。您可以找到`component.feature`類似下列範例的範例。 在此功能檔案中，您可以測試 Greengrass 軟體的物件部署功能。您可以使用透過 Greengrass 雲端執行元件部署的案例來部分測試此功能的功能。該案例是一系列步驟，有助於了解此使用案例的互動和預期結果。 ``` Feature: Testing features of Greengrassv2 component Background: Given my device is registered as a Thing And my device is running Greengrass @Sample Scenario: As a developer, I can create a component and deploy it on my device When I create a Greengrass deployment with components HelloWorld | /path/to/recipe/file And I deploy the Greengrass deployment configuration Then the Greengrass deployment is COMPLETED on the device after 180 seconds And I call my custom step ``` GTF 包含所有下列步驟的步驟定義，但名為 的步驟除外：`And I call my custom step`。 1. **實作步驟定義** GTF 獨立 JAR 包含除了一個步驟以外的所有步驟的步驟定義：`And I call my custom step`。您可以在測試模組中實作此步驟。 導覽至測試檔案的原始程式碼。您可以使用下列命令，使用步驟定義來連結自訂步驟。 ``` @And("I call my custom step") public void customStep() { System.out.println("My custom step was called "); } ``` # 教學課程：使用可信度測試套件中的可信度測試 AWS IoT Greengrass 測試架構 (GTF) 和 Greengrass 開發套件 (GDK) 為開發人員提供執行end-to-end測試的方法。您可以完成此教學課程，以使用元件初始化 GDK 專案、使用end-to-end測試模組初始化 GDK 專案，以及使用可信度測試套件中的可信度測試。建置自訂測試案例之後，您就可以執行測試。 可信度測試是由 Greengrass 提供的一般測試，可驗證基本元件行為。這些測試可以修改或擴展，以滿足更具體的元件需求。 在本教學課程中，我們將使用 HelloWorld 元件。如果您使用的是其他元件，請將 HelloWorld 元件取代為您的元件。 在此教學課程中，您將執行下列操作： 1. 使用元件初始化 GDK 專案。 1. 使用end-to-end測試模組初始化 GDK 專案。 1. 使用可信度測試套件中的測試。 1. 將標籤新增至新的測試案例。 1. 建置測試 JAR。 1. 執行 測試。 **Topics** + [先決條件](#confidence-tests-tutorial-prerequisites) + [步驟 1：使用元件初始化 GDK 專案](#init-gdk-with-component) + [步驟 2：使用end-to-end測試模組初始化 GDK 專案](#init-gdk-with-e2e-test) + [步驟 3：使用可信度測試套件中的測試](#confidence-tests-tutorial-instructions) + [步驟 4：將標籤新增至新的測試案例](#add-tag-to-test-case) + [步驟 5：建置測試 JAR](#build-test-jar) + [步驟 6：執行測試](#run-test-gtf) + [範例：使用可信度測試](#build-confidence-test-case-example) ## 先決條件 為了完成本教學，您需要以下項目： + GDK 1.6.0 版或更新版本 + Java + Maven + Git ## 步驟 1：使用元件初始化 GDK 專案 + 使用 GDK 專案初始化空資料夾。執行下列命令，下載在 Python 中實作的`HelloWorld`元件。 ``` gdk component init -t HelloWorld -l python -n HelloWorld ``` 此命令`HelloWorld`會在目前目錄中建立名為 的新目錄。 ## 步驟 2：使用end-to-end測試模組初始化 GDK 專案 + GDK 可讓您下載由功能和步驟實作組成的測試模組範本。執行下列命令以開啟 `HelloWorld` 目錄，並使用測試模組初始化現有的 GDK 專案。 ``` cd HelloWorld gdk test-e2e init ``` 此命令會在 目錄中建立新的名為 `gg-e2e-tests`的`HelloWorld`目錄。此測試目錄是 [Maven](https://maven.apache.org/) 專案，其相依於 Greengrass 測試獨立 JAR。 ## 步驟 3：使用可信度測試套件中的測試 撰寫可信度測試案例包含使用提供的特徵檔案，並視需要修改案例。如需使用可信度測試的範例，請參閱 [範例：建置自訂測試案例](run-e2e-tests-tutorial.md#build-test-case-example)。使用下列步驟來使用可信度測試： + 使用提供的功能檔案。 導覽至目前目錄中的`gg-e2e-tests/src/main/resources/greengrass/features`資料夾。開啟範例`confidenceTest.feature`檔案以使用可信度測試。 ## 步驟 4：將標籤新增至新的測試案例 + 您可以將標籤指派給功能和案例，以組織測試程序。您可以使用標籤來分類案例子集，也可以依條件選取要執行的勾點。功能和案例可以有多個以空格分隔的標籤。 在此範例中，我們使用 `HelloWorld`元件。 每個案例都會以 標記`@ConfidenceTest`。如果您想要僅執行測試套件的一部分，請變更或新增標籤。每個測試案例都描述在每個可信度測試的頂端。該案例是一系列步驟，有助於了解每個測試案例的互動和預期結果。您可以透過新增自己的步驟或修改現有的步驟來擴展這些測試。 ``` @ConfidenceTest Scenario: As a Developer, I can deploy GDK_COMPONENT_NAME to my device and see it is working as expected .... ``` ## 步驟 5：建置測試 JAR 1. 建置 元件。您必須先建置元件，才能建置測試模組。 ``` gdk component build ``` 1. 使用以下命令建置測試模組。此命令將在 `greengrass-build` 資料夾中建置測試 JAR。 ``` gdk test-e2e build ``` ## 步驟 6：執行測試 當您執行可信度測試時，GTF 會自動執行測試的生命週期，並管理測試期間建立的資源。它會先佈建待測裝置 (DUT) 做為 AWS IoT 物件，並在其上安裝 Greengrass 核心軟體。然後，它會`HelloWorld`使用該路徑中指定的配方來建立新的名為 的元件。然後，`HelloWorld`元件會透過 Greengrass 物件部署部署到核心裝置上。如果部署成功，則會對其進行驗證。如果部署成功，部署狀態會在 `COMPLETED` 3 分鐘內變更為 。 1. 前往專案目錄中`gdk-config.json`的檔案，以 `ConfidenceTest`標籤或步驟 4 中指定的任何標籤 yo8u 為目標測試。使用下列命令更新`test-e2e`金鑰。 ``` "test-e2e":{ "gtf_options" : { "tags":"ConfidenceTest" } } ``` 1. 執行測試之前，您必須提供 AWS 登入資料給主機裝置。GTF 會在測試過程中使用這些登入資料來管理 AWS 資源。請確定您提供的角色具有將測試中包含的必要操作自動化的許可。 執行下列命令以提供 AWS 登入資料。 1. ------ #### [ Linux or Unix ] ``` export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY ``` ------ #### [ Windows Command Prompt (CMD) ] ``` set AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE set AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY ``` ------ #### [ PowerShell ] ``` $env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE" $env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" ``` ------ 1. 使用以下命令執行測試。 ``` gdk test-e2e run ``` 此命令會在 `greengrass-build` 資料夾中下載最新版本的 Greengrass 核，並使用它執行測試。此命令也會僅以具有 `ConfidenceTest`標籤的案例為目標，並產生這些案例的報告。您會在測試結束時看到在此測試期間建立 AWS 的資源遭到捨棄。 ## 範例：使用可信度測試 **Example** GDK 專案中下載的測試模組包含提供的功能檔案。 在下列範例中，我們使用功能檔案來測試 Greengrass 軟體的物件部署功能。我們透過 Greengrass 執行元件部署的案例，部分測試此功能的功能 AWS 雲端。這是一系列步驟，可協助我們了解此使用案例的互動和預期結果。 + **使用提供的功能檔案。** 導覽至目前目錄中的 `gg-e2e-tests/src/main/resources/greengrass/features` 資料夾。您可以找到`confidenceTest.feature`類似下列範例的範例。 ``` Feature: Confidence Test Suite Background: Given my device is registered as a Thing And my device is running Greengrass @ConfidenceTest Scenario: As a Developer, I can deploy GDK_COMPONENT_NAME to my device and see it is working as expected When I create a Greengrass deployment with components | GDK_COMPONENT_NAME | GDK_COMPONENT_RECIPE_FILE | | aws.greengrass.Cli | LATEST | And I deploy the Greengrass deployment configuration Then the Greengrass deployment is COMPLETED on the device after 180 seconds # Update component state accordingly. Possible states: {RUNNING, FINISHED, BROKEN, STOPPING} And I verify the GDK_COMPONENT_NAME component is RUNNING using the greengrass-cli ``` 每個測試案例都描述在每個可信度測試的頂端。該案例是一系列步驟，有助於了解每個測試案例的互動和預期結果。您可以透過新增自己的步驟或修改現有的步驟來擴展這些測試。每個案例都包含可協助您進行這些調整的註解。