本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # AWS IoT Greengrass 开发工具 使用 AWS IoT Greengrass 开发工具创建、测试、构建、发布和部署自定义 Greengrass 组件。 + **[Greengrass 开发工具包 CLI](greengrass-development-kit-cli.md)** 使用本地 AWS IoT Greengrass 开发环境中的开发套件命令行界面 (GDK CLI)，从 [Greengr](greengrass-software-catalog.md) ass 软件目录中的模板和社区组件创建组件。您可以使用 GDK CLI 来构建该组件，并将该组件作为私有组件发布到您的 AWS IoT Greengrass AWS 账户服务中。 + **[Greengrass 命令行界面](gg-cli.md)** 使用 Greengrass 核心设备上的 Greengrass 命令行界面（Greengrass CLI）来部署和调试 Greengrass 组件。Greengrass CLI 是一个组件，您可以将其部署到核心设备上，以创建本地部署、查看有关已安装组件的详细信息以及浏览日志文件。 + **[本地调试控制台](local-debug-console-component.md)** 使用 Greengrass 核心设备上的本地调试控制台，通过本地控制面板 Web 界面部署和调试 Greengrass 组件。本地调试控制台是一个组件，您可以将其部署到核心设备上，以创建本地部署和查看有关已安装组件的详细信息。 AWS IoT Greengrass 还提供了可以在自定义 Greengrass 组件中使用的以下内容 SDKs ： + AWS IoT Device SDK 和组 AWS IoT Greengrass 件 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)中的版本和构件 URI。当您使用 GDK CLI 时，它可以在您每次发布组件的新版本时自动为您更新版本和构件 URI。 GDK CLI 是开源的，可在 GitHub 上提供。您可以自定义和扩展 GDK CLI 以满足您的组件开发需求。我们邀请您在 GitHub 存储库上打开问题和拉取请求。您可以通过以下链接查找 GDK CLI 的源代码：[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 设备，请安装 AWS CLI V1。AWS CLIV2 不适用于 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 v1.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_cn/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_cn/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_cn/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_cn/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_cn/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_cn/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_cn/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_cn/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_cn/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_cn/greengrass/v2/developerguide/greengrass-development-kit-cli.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/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_cn/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.0.0 | 初始版本。 | # 安装或更新 AWS IoT Greengrass 开发工具包命令行界面 AWS IoT Greengrass 开发工具包命令行界面（GDK CLI）基于 Python 构建，因此您可以使用 `pip` 将其安装在开发计算机上。 **提示** 您也可以在 Python 虚拟环境（例如 [venv](https://docs.python.org/3/library/venv.html#module-venv)）中安装 GDK CLI。有关更多信息，请参阅 *Python 3 文档*中的[虚拟环境和程序包](https://docs.python.org/3/tutorial/venv.html)。 **安装或更新 GDK CLI** 1. 运行以下命令，以从 GDK CLI 的 [GitHub 存储库](https://github.com/aws-greengrass/aws-greengrass-gdk-cli)安装其最新版本。 ``` python3 -m pip install -U git+https://github.com/aws-greengrass/aws-greengrass-gdk-cli.git@v1.6.2 ``` **注意** 要安装特定版本的 GDK CLI，请将 *VersionTag* 替换为要安装的版本标签。您可以在 GDK CLI 的 [GitHub 存储库](https://github.com/aws-greengrass/aws-greengrass-gdk-cli/tags)中查看其版本标签。 ``` 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 开发工具包命令行界面命令 AWS IoT Greengrass 开发工具包命令行界面（GDK CLI）可提供一个命令行界面，该命令行界面可用于在开发计算机上创建、构建和发布 Greengrass 组件。GDK CLI 命令使用如下格式。 ``` gdk [arguments] ``` [安装 GDK CLI](install-greengrass-development-kit-cli.md) 时，安装程序会将 `gdk` 添加到 PATH 中，因此您可以从命令行运行 GDK CLI。 您可以将以下参数与任何命令一起使用： + 使用 `-h` 或 `--help` 获取有关 GDK CLI 命令的信息。 + 使用 `-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) # 组件 使用 `component` 命令在 AWS IoT Greengrass 开发工具包命令行界面（GDK CLI）中创建、构建和发布自定义 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)中检索社区组件，从 [GitHub 上的 AWS IoT Greengrass 组件模板存储库](https://github.com/aws-greengrass/aws-greengrass-component-templates)中检索组件模板。 **注意** 如果您使用的是 GDK CLI v1.0.0，则必须在空文件夹中运行此命令。GDK CLI 会将模板或社区组件下载到当前文件夹。 如果您使用的是 GDK CLI v1.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 会创建名为 `HelloWorld.zip` 的 zip 文件。在组件配方中，zip 构件名称必须与组件文件夹的名称相匹配。如果在 Windows 设备上使用 GDK CLI 版本 1.0.0，则组件文件夹名称和 ZIP 文件名称必须仅包含小写字母。 如果将使用 zip 构建系统的模板或社区组件初始化为与模板或组件名称不同的文件夹，则必须更改组件配方中的 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` – 用于本地组件项目的组件模板。要查看可用模板，请使用 [list](#greengrass-development-kit-cli-component-list) 命令。 您必须指定 `--repository` 或 `--language` 和 `--template`。 + `-n`，`--name` –（可选）供 GDK CLI 初始化组件的本地文件夹的名称。指定不存在的文件夹。GDK CLI 会为您创建文件夹。 此功能适用于 GDK CLI v1.1.0 及更高版本。 **参数（从社区组件初始化）** + `-r`，`--repository` – 要签出到本地文件夹中的社区组件。要查看可用的社区组件，请使用 [list](#greengrass-development-kit-cli-component-list) 命令。 您必须指定 `--repository` 或 `--language` 和 `--template`。 + `-n`，`--name` –（可选）供 GDK CLI 初始化组件的本地文件夹的名称。指定不存在的文件夹。GDK CLI 会为您创建文件夹。 此功能适用于 GDK CLI v1.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 v1.1.0 或更高版本，则组件配方可以指定存在于 S3 存储桶中但不存在于本地组件构建文件夹中的构件。在开发具有大型构件的组件（例如机器学习模型）时，可以使用此功能来减少带宽使用量。 构建组件后，您可以执行以下操作之一，在 Greengrass 核心设备上对组件进行测试： + 如果您在与运行 AWS IoT Greengrass Core 软件的设备不同的设备上进行开发，则必须发布该组件才能将其部署到 Greengrass 核心设备上。将组件发布到 AWS IoT Greengrass 服务，然后将其部署到 Greengrass 核心设备。有关更多信息，请参阅 [publish](#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 ``` **参数**： 无 **输出**： 下面的示例显示运行此命令时产生的输出。 ``` $ 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) `gdk-config.json` 中指定的 S3 存储桶和 AWS 区域。您必须在 `gdk-config.json` 文件所在的同一文件夹中运行此命令。 如果您使用的是 GDK CLI v1.1.0 或更高版本，则可以指定 `--bucket` 参数来指定供 GDK CLI 上传组件构件的 S3 存储桶。如果未指定此参数，GDK CLI 会上传到名为 `bucket-region-accountId` 的 S3 存储桶，其中 *bucket* 和 *region* 是您在 `gdk-config.json` 中指定的值，*accountId* 是您的 AWS 账户 ID。如果存储桶不存在，GDK CLI 将创建该存储桶。 如果您使用的是 GDK CLI v1.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 v1.1.0 或更高版本，则在运行此命令时，GDK CLI 会检查是否已构建组件。如果未构建组件，GDK CLI 将在发布组件之前[构建组件](#greengrass-development-kit-cli-component-build)。 **摘要** ``` $ gdk component publish [--bucket] [--region] [--options] ``` **参数**： + `-b`，`--bucket` –（可选）指定 GDK CLI 在其中发布组件构件的 S3 存储桶的名称。 如果未指定此参数，GDK CLI 会上传到名为 `bucket-region-accountId` 的 S3 存储桶，其中 *bucket* 和 *region* 是您在 `gdk-config.json` 中指定的值，*accountId* 是您的 AWS 账户 ID。如果存储桶不存在，GDK CLI 将创建该存储桶。 如果存储桶不存在，GDK CLI 将创建该存储桶。 此功能适用于 GDK CLI v1.1.0 及更高版本。 + `-r`，`--region` –（可选）在创建组件时指定 AWS 区域 的名称。此参数覆盖 GDK CLI 配置中的区域名称。 此功能适用于 GDK CLI v1.2.0 及更高版本。 + `-o`，`--options`（可选）指定用于发布组件的选项列表。参数必须是有效的 JSON 字符串或包含发布选项的 JSON 文件的文件路径。此参数覆盖 GDK CLI 配置中的选项。 此功能适用于 GDK CLI v1.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)中检索社区组件，从 [GitHub 上的 AWS IoT Greengrass 组件模板存储库](https://github.com/aws-greengrass/aws-greengrass-component-templates)中检索组件模板。 您可以将此命令的输出传递给 [init](#greengrass-development-kit-cli-component-init) 命令，以便从模板和社区组件初始化组件存储库。 **摘要** ``` $ gdk component list [--template] [--repository] ``` **参数**： + `-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-config.json` 中 GDK 的配置。 **Topics** + [更新](#greengrass-development-kit-cli-config-update) ## 更新 启动交互式提示以修改现有 GDK 配置文件中的字段。 **摘要** ``` $ gdk config update [--component] ``` **参数**： + `-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 项目中初始化、构建和运行端到端测试模块。 **Topics** + [init](#greengrass-development-kit-cli-test-init) + [build](#greengrass-development-kit-cli-test-build) + [运行](#greengrass-development-kit-cli-test-run) ## init 借助使用 Greengrass 测试框架（GTF）的测试模块初始化现有的 GDK CLI 项目。 默认情况下，GDK CLI 从 [GitHub 上的 AWS IoT Greengrass 组件模板存储库](https://github.com/aws-greengrass/aws-greengrass-component-templates)中检索 maven 模块模板。这个 maven 模块附带了对 `aws-greengrass-testing-standalone` JAR 文件的依赖关系。 此命令在 GDK 项目内创建一个名为 `gg-e2e-tests` 的新目录。如果测试模块目录已经存在且不为空，则命令将不执行任何操作就退出。此 `gg-e2e-tests` 文件夹包含 Maven 项目中结构化的 Cucumber 功能和步骤定义。 默认情况下，此命令将尝试使用最新发行版的 GTF。 **摘要** ``` $ gdk test-e2e init [--gtf-version] ``` **参数**： + `-ov`，`--gtf-version` –（可选）在 GDK 项目中的端到端测试模块中使用的 GTF 版本。此值必须属于[发行版](https://github.com/aws-greengrass/aws-greengrass-testing/releases)中的 GTF 版本。此参数覆盖 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** 来构建组件，然后才能构建端到端测试模块。 构建端到端测试模块。GDK CLI 使用您在 [GDK CLI 配置文件](gdk-cli-configuration-file.md) `gdk-config.json` 中的 `test-e2e` 属性下指定的构建系统来构建测试模块。您必须在 `gdk-config.json` 文件所在的同一文件夹中运行此命令。 默认情况下，GDK CLI 使用 maven 构建系统来构建测试模块。需要使用 [Maven](https://maven.apache.org/) 才能运行 `gdk test-e2e build` 命令。 如果测试功能文件有 `GDK_COMPONENT_NAME` 和 `GDK_COMPONENT_RECIPE_FILE` 等变量需要插值，则必须通过运行 **gdk-component-build** 构建组件，然后才能构建测试模块。 运行此命令时，GDK CLI 会插入 GDK 项目配置中的所有变量，并构建 `gg-e2e-tests` 模块以生成最终的测试 JAR 文件。 **摘要** ``` $ gdk test-e2e build ``` **参数**： 无 **输出**： 下面的示例显示运行此命令时产生的输出。 ``` $ 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' ......... ``` ## 运行 使用 GDK 配置文件中的测试选项运行测试模块。 **注意** 您必须通过运行 **gdk test-e2e build** 构建测试模块，然后才能运行端到端测试。 **摘要** ``` $ gdk test-e2e run [--gtf-options] ``` **参数**： + `-oo`，`--gtf-options` –（可选）指定运行端到端测试的选项列表。参数必须是有效的 JSON 字符串或包含 GTF 选项的 JSON 文件的文件路径。配置文件中提供的选项与命令参数中提供的选项合并。如果一个选项在两个位置都存在，则参数中的选项优先于配置文件中的选项。 如果此命令中未指定 `tags` 选项，GDK 会将 `Sample` 用于标签。如果未指定 `ggc-archive`，GDK 将下载最新版本的 Greengrass Nucleus 存档。 **输出**： 下面的示例显示运行此命令时产生的输出。 ``` $ 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 开发工具包命令行界面（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 会创建名为 `HelloWorld.zip` 的 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 v1.1.0 及更高版本。 + `gradle` – 运行 `gradle build` 命令以将组件的源代码构建为构件。对于使用 [Gradle](https://gradle.org/) 的组件，请选择此选项。此功能适用于 GDK CLI v1.1.0 及更高版本。 `gradle` 构建系统支持 Kotlin DSL 作为构建文件。此功能适用于 GDK CLI v1.2.0 及更高版本。 + `gradlew` – 运行 `gradlew` 命令以将组件的源代码构建为构件。对于使用 [Gradle Wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html) 的组件，请选择此选项。 此功能适用于 GDK CLI v1.2.0 及更高版本。 + `custom` – 运行自定义命令，将组件的源代码构建为配方和构件。在 `custom_build_command` 参数中指定自定义命令。 `custom_build_command` （可选）要为自定义构建系统运行的自定义构建命令。如果您为 `build_system` 指定 `custom`，您必须指定此参数。 此命令必须在组件文件夹的以下文件夹中创建配方和构件。当您运行[组件构建命令](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"]**。 要查看自定义构建系统的示例，请参阅 [GitHub 上的 aws.greengrass.labs.LocalWebServer community component](https://github.com/awslabs/aws-greengrass-labs-local-web-server)。 `options` （可选）在组件构建过程中使用的其他配置选项。 此功能适用于 GDK CLI v1.2.0 及更高版本。 `excludes` glob 模式列表，定义在构建 zip 文件时要从组件目录中排除的文件。仅当 `build_system` 为 `zip` 时才有效。 在 GDK CLI 版本 1.4.0 及更早版本中，与排除列表中条目匹配的任何文件都将从组件的所有子目录中排除。要在 GDK CLI 版本 1.5.0 及更高版本中实现相同的行为，请在排除列表中的现有条目前面加上 `**/`。例如，`*.txt` 将仅从目录中排除文本文件；`**/*.txt` 将从所有目录和子目录中排除文本文件。 在 GDK CLI 版本 1.5.0 及更高版本中，当在 GDK 配置文件中定义了 `excludes` 时，您可能会在组件构建期间看到一条警告。要禁止此警告，请将环境变量 `GDK_EXCLUDES_WARN_IGNORE` 设置为 `true`。 GDK CLI 始终从 zip 文件中排除以下文件： + `gdk-config.json` 文件 + 配方文件（`recipe.json` 或 `recipe.yaml`） + 构建文件夹，例如 `greengrass-build` 默认排除以下文件。但是，您可以使用 `excludes` 选项控制要排除其中的哪些文件。 + 以前缀“test”（`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 v1.1.0 或更高版本，则可以指定 `--bucket` 参数来指定供 GDK CLI 上传组件构件的 S3 存储桶。如果未指定此参数，GDK CLI 会上传到名为 `bucket-region-accountId` 的 S3 存储桶，其中 *bucket* 和 *region* 是您在 `gdk-config.json` 中指定的值，*accountId* 是您的 AWS 账户 ID。如果存储桶不存在，GDK CLI 将创建该存储桶。 该对象包含以下信息： `bucket` 用于托管组件构件的 S3 存储桶名称。 `region` GDK CLI 发布此组件是所用的 AWS 区域。 如果您使用的是 GDK CLI v1.3.0 或更高版本，则此属性可选。 `options` （可选）在组件版本创建期间使用的其他配置选项。 此功能适用于 GDK CLI v1.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) 类。** `test-e2e` （可选）在组件的端到端测试期间使用的配置。此功能适用于 GDK CLI v1.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 项目时，用作端到端测试模块依赖关系的 Greengrass 测试框架（GTF）的版本。此值必须属于[发行版](https://github.com/aws-greengrass/aws-greengrass-testing/releases)中的 GTF 版本。默认为 GTF 版本 1.1.0。 `gtf_options` （可选）在组件的端到端测试期间使用的其他配置选项。 以下列表包含您可以在 GTF 版本 1.1.0 中使用的选项。 + `additional-plugins` –（可选）其他 Cucumber 插件 + `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 设备证书的现有证书的 ARN。 + `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 Nucleus 组件的路径。 + `ggc-install-root` – 用于安装 Greengrass Nucleus 组件的目录。默认为 test.temp.path 和测试运行文件夹。 + `ggc-log-level` – 为测试运行设置 Greengrass Nucleus 日志级别。默认为“INFO”。 + `ggc-tes-rolename` – AWS IoT Greengrass Core 将担任的 IAM 角色，用于访问 AWS 服务。如果不存在具有给定名称的角色，则系统会创建一个角色并会创建默认访问策略。 + `ggc-trusted-plugins` – 需要添加到 Greengrass 的可信插件的路径（主机上）的逗号分隔列表。要提供 DUT 本身的路径，请在路径前加上“dut:” + `ggc-user-name` – Greengrass Nucleus 的 user:group posixUser 值。默认为当前登录的用户名。 + `ggc-version` – 覆盖正在运行的 Greengrass Nucleus 组件版本。默认为 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 会将此 zip 文件作为构件上传。 ``` { "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 源代码打包为 JAR 文件，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 执行以下任一操作以使用 Greengrass CLI： + 使用运行 C AWS IoT Greengrass ore 软件的系统用户。 + 使用具有根权限或管理员权限的用户。在 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. 在您的设备上，创建一个定义 Greengrass CLI 组件部署配置的 `deployment.json` 文件。此文件应类似以下内容： ``` { "targetArn":"targetArn", "components": { "aws.greengrass.Cli": { "componentVersion": "2.17.0", "configurationUpdate": { "merge": "{\"AuthorizedPosixGroups\":\",,...,\",\"AuthorizedWindowsGroups\":\",,...,\"}" } } } } ``` + 在 `target` 字段中，按以下格式将 `targetArn` 替换为部署目标的事物或事物组的 Amazon 资源名称（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 您可以指定组名或群组 IDs。例如，`group1,1002,group3` 授权三个系统组（`group1`、`1002` 和 `group3`）使用 Greengrass CLI。 如果您未指定要授权的任何群组，则可以以 root 用户 `sudo` () 或运行核心软件的系统用户身份使用 Greengrass CLI。 AWS IoT Greengrass `configurationUpdate.AuthorizedWindowsGroups` （可选）包含以逗号分隔的系统组列表的字符串。您授权这些系统组使用 Greengrass CLI 与核心软件进行交互。 AWS IoT Greengrass 您可以指定组名或群组 IDs。例如，`group1,1002,group3` 授权三个系统组（`group1`、`1002` 和 `group3`）使用 Greengrass CLI。 如果您未指定要授权的任何群组，则可以以管理员或运行 Core 软件的系统用户身份使用 Greengrass CLI。 AWS IoT Greengrass 1. 运行以下命令，在设备上部署 Greengrass CLI 组件： ``` $ aws greengrassv2 create-deployment --cli-input-json file://path/to/deployment.json ``` 在安装过程中，组件会在设备的 `/greengrass/v2/bin` 文件夹中添加一个指向 `greengrass-cli` 的符号链接，您可以从该路径运行 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 Core 软件版本进行交互。如果您调用未放置在此位置的可执行文件，或者您想在其它位置与 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` 命令与核心设备上的本地组件进行交互。 **子命令** + [details](#component-details) + [列表](#component-list) + [重新开始](#component-restart) + [stop](#component-stop) ## details 检索一个组件的版本、状态和配置。 **摘要** ``` greengrass-cli component details --name ``` **参数**： `--name`，`-n`。组件类型名称。 **输出**： 下面的示例显示运行此命令时产生的输出。 ``` $ sudo greengrass-cli component details --name MyComponent Component Name: MyComponent Version: 1.0.0 State: RUNNING Configuration: null ``` ## 列表 检索设备上安装的每个组件的名称、版本、状态和配置。 **摘要** ``` greengrass-cli component list ``` **参数**： 无 **输出**： 下面的示例显示运行此命令时产生的输出。 ``` $ 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 ,... ``` **参数**： `--names`，`-n`。组件类型名称。至少需要一个组件名称。您可以指定其它组件名称，用逗号分隔每个名称。 **输出**： 无 ## stop 停止运行组件。 **摘要** ``` greengrass-cli component stop --names ,... ``` **参数**： `--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 ] ``` **参数** + `--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` 参数提供运行组件的 `posixUser`、`posixGroup` 和 `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 数量（以千字节表示）。 有关更多信息，请参阅 [配置组件的系统资源限制](configure-greengrass-core-v2.md#configure-component-system-resource-limits)。 此功能适用于 Linux 核心设备上的 Greengrass n [ucleus 组件](greengrass-nucleus-component.md)和 Greengrass CLI 的 v2.4.0 及更高版本。 AWS IoT Greengrass 目前不支持在 Windows 核心设备上使用此功能。 + `--remove`。要从本地部署中移除的目标组件的名称。如果组件定义了[卸载生命周期](component-recipe-reference.md#uninstall-lifecycle-definition)步骤，则 AWS IoT Greengrass Core 软件将在移除组件之前运行卸载脚本。要移除从云部署中合并的组件，必须按以下格式提供目标事物组的组 ID： ------ #### [ Greengrass nucleus v2.4.0 and later ] ``` --remove --groupId ``` ------ #### [ Earlier than v2.4.0 ] ``` --remove --groupId thinggroup/ ``` ------ + `--failure-handling-policy`。定义部署失败时采取的操作。您可以指定两个操作： + `ROLLBACK` – + `DO_NOTHING` – 此功能适用于 [Greengrass Nucleus](greengrass-nucleus-component.md) v2.11.0 及更高版本。 **输出** 下面的示例显示运行此命令时产生的输出。 ``` $ 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` 命令的输出中返回。 Output + 无 ## 列表 检索最近 10 次本地部署的状态。 **摘要** ``` greengrass-cli deployment list ``` **参数** 无 **输出** 下面的示例显示运行此命令时产生的输出。根据您的部署状态，输出会显示以下状态值之一：`IN_PROGRESS`、`SUCCEEDED` 或 `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 ``` **参数** `-i`。部署的 ID。 **输出** 下面的示例显示运行此命令时产生的输出。根据您的部署状态，输出会显示以下状态值之一：`IN_PROGRESS`、`SUCCEEDED` 或 `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 ] ``` **参数**： + `--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` 或 `beta` 的键 `name` 的日志消息。 + `--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`。移除颜色编码。日志消息的默认颜色编码使用红色粗体文本。由于使用 ANSI 转义序列，因此仅支持 Unix 类终端。 + `--before`，`-b`。在匹配的日志条目之前显示的行数。默认值为 0。 + `--after`，`-a`。在匹配的日志条目之后显示的行数。默认值为 0。 + `--syslog`。使用 RFC3164 定义的系统日志协议处理所有日志文件。请勿与 `--log-dir` 和 `--verbose` 一起使用。系统协议使用以下格式：`"<$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] ``` **参数**： 无 **输出**： 下面的示例显示运行此命令时产生的输出。 ``` $ 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] ``` **参数**： `--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 ``` **参数**： 无 **输出**： 下面的示例显示运行此命令时产生的输出。 ``` $ 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-endGTF 使用 Cuc [u](https://cucumber.io) mber 作为功能驱动程序。 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 end-to-end 测试框架和 Greengrass 开发套件运行测试](run-e2e-tests-tutorial.md) + [教程：使用置信度测试套件中的置信度测试](confidence-tests-tutorial.md) ## 工作原理 AWS IoT Greengrass 将 GTF 作为由多个 Java 模块组成的独立 JAR 分发。要使用 GTF end-to-end 测试组件，必须在 Java 项目中实现测试。将可测试的独立 JAR 作为依赖关系添加到您的 Java 项目后，您就可以使用 GTF 的现有功能，并通过编写自己的自定义测试用例对其进行扩展。要运行自定义测试用例，您可以构建 Java 项目并使用 [Greengrass 测试框架配置选项](configuration-options-gtf.md) 中所述的配置选项运行目标 JAR。 ### 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 资源的生命周期提供了抽象。你可以用它来使用`ResourceSpec`抽象来定义你的自定义 AWS 资源，这样 GTF 就可以为你创建和删除这些资源。 + `aws-greengrass-testing-platform`：此模块测试生命周期内为被测设备提供平台级抽象。它包含 APIs 用于与独立于平台的操作系统进行交互，并可用于模拟在设备外壳中运行的命令。 + `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 end-to-end 测试框架和 Greengrass 开发套件运行测试](run-e2e-tests-tutorial.md) + [教程：使用置信度测试套件中的置信度测试](confidence-tests-tutorial.md) ## 更改日志 下表介绍每个版本 GTF 的更改。如需了解更多信息，请参阅上的 [GTF 发布页面](https://github.com/aws-greengrass/aws-greengrass-testing/releases)。 GitHub | **版本** | **更改** | | --- | --- | | 1.2.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/gg-testing-framework.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/gg-testing-framework.html) | | 1.1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/gg-testing-framework.html) | | 1.0.0 | 初始版本。 | # Greengrass 测试框架配置选项 ## GTF 配置选项 Greengrass 测试框架（GTF）允许您在端到端测试流程启动期间配置某些参数，以编排测试流程。您可以将这些配置选项指定为 GTF 独立 JAR 的 CLI 参数。 GTF 版本 1.1.0 及更高版本提供了以下配置选项。 + `additional-plugins` –（可选）其他 Cucumber 插件 + `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 设备证书的现有证书的 ARN。 + `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 Nucleus 组件的路径。 + `ggc-install-root` – 用于安装 Greengrass Nucleus 组件的目录。默认为 test.temp.path 和测试运行文件夹。 + `ggc-log-level` – 为测试运行设置 Greengrass Nucleus 日志级别。默认为“INFO”。 + `ggc-tes-rolename` – AWS IoT Greengrass Core 将担任的 IAM 角色，用于访问 AWS 服务。如果不存在具有给定名称的角色，则系统会创建一个角色并会创建默认访问策略。 + `ggc-trusted-plugins` – 需要添加到 Greengrass 的可信插件的路径（主机上）的逗号分隔列表。要提供 DUT 本身的路径，请在路径前加上“dut:” + `ggc-user-name` – Greengrass Nucleus 的 user:group posixUser 值。默认为当前登录的用户名。 + `ggc-version` – 覆盖正在运行的 Greengrass Nucleus 组件版本。默认为 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。 # 教程：使用 Greengrass end-to-end 测试框架和 Greengrass 开发套件运行测试 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 ``` 此命令将在 `HelloWorld` 目录中创建一个名为 `gg-e2e-tests` 的新目录。这个测试目录是一个 [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` 组件。 在功能文件中，在 `@Sample` 标签旁边添加一个名为 `@HelloWorld` 的新标签。 ``` @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` 的新组件。然后通过 Greengrass 事物部署将该 `HelloWorld` 组件部署至核心设备上。然后验证部署是否成功。如果部署成功，部署状态将在 3 分钟内更改为 `COMPLETED`。 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 Nucleus，并使用它运行测试。该命令也仅针对带有 `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 ``` 此命令将在 `HelloWorld` 目录中创建一个名为 `gg-e2e-tests` 的新目录。这个测试目录是一个 [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` 的新组件。然后通过 Greengrass 事物部署将该 `HelloWorld` 组件部署至核心设备上。然后验证部署是否成功。如果部署成功，部署状态将在 3 分钟内更改为 `COMPLETED`。 1. 转至项目目录中的 `gdk-config.json` 文件，使用 `ConfidenceTest` 标签或步骤 4 中指定的任何标签来定位测试。使用以下命令更新 `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 Nucleus，并使用它运行测试。该命令也仅针对带有 `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 ``` 每个测试场景的描述均可见于每个置信度测试顶部。该场景包含一系列步骤，有助于了解每个测试用例的交互作用和预期结果。您可以通过添加自己的步骤或修改现有步骤来扩展这些测试。每个场景都包含可帮助您进行这些调整的注释。