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

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