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

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