本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# AWS IoT Greengrass 开发工具包命令行界面
<a name="greengrass-development-kit-cli"></a>

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)。

## 先决条件
<a name="gdk-cli-prerequisites"></a>

要安装和使用 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/)。
+ <a name="development-component-aws-cli-prerequisite"></a>开发计算机上已安装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 及更高版本。

## 更改日志
<a name="gdk-cli-changelog"></a>

下表介绍每个版本的 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 开发工具包命令行界面
<a name="install-greengrass-development-kit-cli"></a>

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. <a name="gdk-cli-verify-installation"></a>运行以下命令验证是否已成功安装 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 开发工具包命令行界面命令
<a name="greengrass-development-kit-cli-commands"></a>

AWS IoT Greengrass 开发工具包命令行界面（GDK CLI）可提供一个命令行界面，该命令行界面可用于在开发计算机上创建、构建和发布 Greengrass 组件。GDK CLI 命令使用如下格式。

```
gdk <command> <subcommand> [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)

# 组件
<a name="greengrass-development-kit-cli-component"></a>

使用 `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
<a name="greengrass-development-kit-cli-component-init"></a>

从组件模板或社区组件初始化 Greengrass 组件文件夹。

<a name="gdk-cli-component-templates-community-components"></a>GDK CLI 从 [Greengrass 软件目录](greengrass-software-catalog.md)中检索社区组件，从 [GitHub 上的 AWS IoT Greengrass 组件模板存储库](https://github.com/aws-greengrass/aws-greengrass-component-templates)中检索组件模板。

**注意**  
<a name="gdk-cli-component-init-empty-folder-requirement"></a>如果您使用的是 GDK CLI v1.0.0，则必须在空文件夹中运行此命令。GDK CLI 会将模板或社区组件下载到当前文件夹。  
<a name="gdk-cli-component-init-empty-folder-requirement-gdk-cli-v1.1.0"></a>如果您使用的是 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
<a name="greengrass-development-kit-cli-component-build"></a>

将组件的源代码构建成可以发布到 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'.
```

## 发布
<a name="greengrass-development-kit-cli-component-publish"></a>

将此组件发布到 AWS IoT Greengrass 服务。此命令将构建构件上传到 S3 存储桶，更新配方中的构件 URI，并根据配方创建新版本的组件。GDK CLI 使用您在 [GDK CLI 配置文件](gdk-cli-configuration-file.md) `gdk-config.json` 中指定的 S3 存储桶和 AWS 区域。您必须在 `gdk-config.json` 文件所在的同一文件夹中运行此命令。

<a name="gdk-cli-s3-bucket-name-formation"></a>如果您使用的是 GDK CLI v1.1.0 或更高版本，则可以指定 `--bucket` 参数来指定供 GDK CLI 上传组件构件的 S3 存储桶。<a name="gdk-cli-s3-bucket-name-formation-format"></a>如果未指定此参数，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 存储桶的名称。

   <a name="gdk-cli-s3-bucket-name-formation-format"></a>如果未指定此参数，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'.
```

## 列表
<a name="greengrass-development-kit-cli-component-list"></a>

检索可用组件模板和社区组件的列表。

<a name="gdk-cli-component-templates-community-components"></a>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
<a name="greengrass-development-kit-cli-config"></a>

使用 AWS IoT Greengrass 开发工具包命令行界面（GDK CLI）中的 `config` 命令修改配置文件 `gdk-config.json` 中 GDK 的配置。

**Topics**
+ [更新](#greengrass-development-kit-cli-config-update)

## 更新
<a name="greengrass-development-kit-cli-config-update"></a>

启动交互式提示以修改现有 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
<a name="greengrass-development-kit-cli-test"></a>

使用 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
<a name="greengrass-development-kit-cli-test-init"></a>

借助使用 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
<a name="greengrass-development-kit-cli-test-build"></a>

**注意**  
您必须通过运行 **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'
.........
```

## 运行
<a name="greengrass-development-kit-cli-test-run"></a>

使用 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 配置文件
<a name="gdk-cli-configuration-file"></a>

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 配置文件格式
<a name="gdk-config-format"></a>

在为组件定义 GDK CLI 配置文件时，您以 JSON 格式指定以下信息。

`gdk_version`  
与此组件兼容的 GDK CLI 的最低版本。此值必须属于[发行版](https://github.com/aws-greengrass/aws-greengrass-gdk-cli/releases)中的 GDK CLI 版本。

`component`  
此组件的配置。    
`componentName`    
`author`  
组件的作者或发布者。  
`version`  
组件版本。指定下列项之一：  <a name="gdk-cli-configuration-file-component-version-options"></a>
+ `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`   
要使用的构建系统。从以下选项中进行选择：  <a name="gdk-cli-configuration-file-component-build-system-options"></a>
+ `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 服务的配置。  
<a name="gdk-cli-s3-bucket-name-formation"></a>如果您使用的是 GDK CLI v1.1.0 或更高版本，则可以指定 `--bucket` 参数来指定供 GDK CLI 上传组件构件的 S3 存储桶。<a name="gdk-cli-s3-bucket-name-formation-format"></a>如果未指定此参数，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`  
（可选）在组件的端到端测试期间使用的其他配置选项。  
<a name="gtf_options"></a>以下列表包含您可以在 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 配置文件示例
<a name="gdk-config-examples"></a>

您可以参考以下 GDK CLI 配置文件示例，帮助您配置 Greengrass 组件环境。

### Hello World (Python)
<a name="gdk-config-example-hello-world-python"></a>

以下 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）
<a name="gdk-config-example-hello-world-java"></a>

以下 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"
  }
}
```

### 社区组件
<a name="gdk-config-community-component-examples"></a>

[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
   ```