本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 创建 AWS IoT Greengrass 组件
您可以在本地开发计算机或 Greengrass 核心设备上开发自定义 AWS IoT Greengrass 组件。AWS IoT Greengrass 提供 [AWS IoT Greengrass 开发工具包命令行界面（GDK CLI）](greengrass-development-kit-cli.md)，可帮助您根据预定义的组件模板和[社区组件](greengrass-software-catalog.md)创建、构建和发布组件。您还可以运行内置的 Shell 命令来创建、构建和发布组件。从以下选项中进行选择，以创建自定义 Greengrass 组件：
+ **使用 Greengrass 开发工具包 CLI**
使用 GDK CLI 在本地开发计算机上开发组件。GDK CLI 构建组件源代码并将其打包成配方和构件，您可以将其作为私有组件发布到 AWS IoT Greengrass 服务。您可以配置 GDK CLI，以在发布组件时自动更新组件的版本和构件 URI，因此无需每次都更新配方。要使用 GDK CLI 开发组件，可以从 [Greengrass 软件目录](greengrass-software-catalog.md)中的模板或社区组件开始。有关更多信息，请参阅 [AWS IoT Greengrass 开发工具包命令行界面](greengrass-development-kit-cli.md)。
+ **运行内置 Shell 命令**
您可以运行内置 Shell 命令在本地开发计算机或 Greengrass 核心设备上开发组件。您可以使用 Shell 命令将组件源代码复制或构建到构件中。每次创建组件的新版本时，都必须使用新的组件版本创建或更新配方。将组件发布到 AWS IoT Greengrass 服务时，必须更新配方中每个组件构件的 URI。
**Topics**
+ [创建组件（GDK CLI）](#create-component-gdk-cli)
+ [创建组件（Shell 命令）](#create-component-shell-commands)
## 创建组件（GDK CLI）
按照本节中的说明，使用 GDK CLI 创建和构建组件。
**要开发 Greengrass 组件（GDK CLI），请执行以下操作**
1. 如果尚未安装 GDK CLI，请在开发计算机上进行安装。有关更多信息，请参阅 [安装或更新 AWS IoT Greengrass 开发工具包命令行界面](install-greengrass-development-kit-cli.md)。
1. 更改为要在其中创建组件文件夹的文件夹。
------
#### [ Linux or Unix ]
```
mkdir ~/greengrassv2
cd ~/greengrassv2
```
------
#### [ Windows Command Prompt (CMD) ]
```
mkdir %USERPROFILE%\greengrassv2
cd %USERPROFILE%\greengrassv2
```
------
#### [ PowerShell ]
```
mkdir ~/greengrassv2
cd ~/greengrassv2
```
------
1. 选择要下载的组件模板或社区组件。GDK CLI 下载模板或社区组件，因此您可以从功能示例开始。使用 [component list](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-list) 命令检索可用模板或社区组件的列表。
+ 要列出组件模板，请运行以下命令。响应中的每一行都包含模板的名称和编程语言。
```
gdk component list --template
```
+ 要列出社区组件，请运行以下命令。
```
gdk component list --repository
```
1. 创建并更改为供 GDK CLI 下载模板或社区组件的组件文件夹。将 *HelloWorld* 替换为组件的名称或其他可帮助您识别此组件文件夹的名称。
------
#### [ Linux or Unix ]
```
mkdir HelloWorld
cd HelloWorld
```
------
#### [ Windows Command Prompt (CMD) ]
```
mkdir HelloWorld
cd HelloWorld
```
------
#### [ PowerShell ]
```
mkdir HelloWorld
cd HelloWorld
```
------
1. 将模板或社区组件下载到当前文件夹。使用 [component init](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-init) 命令。
+ 要从模板创建组件文件夹，请运行以下命令。将 *HelloWorld* 替换为模板的名称，并将 *python* 替换为编程语言的名称。
```
gdk component init --template HelloWorld --language python
```
+ 要从社区组件创建组件文件夹，请运行以下命令。将 *ComponentName* 替换为社区组件的名称。
```
gdk component init --repository ComponentName
```
**注意**
如果您使用的是 GDK CLI v1.0.0，则必须在空文件夹中运行此命令。GDK CLI 会将模板或社区组件下载到当前文件夹。
如果您使用的是 GDK CLI v1.1.0 或更高版本，则可以指定 `--name` 参数来指定供 GDK CLI 下载模板或社区组件的文件夹。如果使用此参数，请指定一个不存在的文件夹。GDK CLI 会为您创建文件夹。如果您不指定此参数，GDK CLI 将使用当前文件夹，此文件夹必须为空。
1. GDK CLI 从名为 `gdk-config.json` 的 [GDK CLI 配置文件](gdk-cli-configuration-file.md)中读取数据，以生成和发布组件。此配置文件存在于组件文件夹的根目录中。在上一步中，将为您创建此文件。在这一步中，使用组件的相关信息更新 `gdk-config.json`。执行以下操作：
1. 在文本编辑器中打开 `gdk-config.json`。
1. （可选）更改组件的名称。组件名称是 `component` 对象中的关键。
1. 更改组件的作者。
1. （可选）更改组件的版本。指定下列项之一：
+ `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) 创建本地部署。
1. （可选）更改组件的构建配置。构建配置定义了 GDK CLI 如何将组件的源代码构建到构件中。对于 `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` 参数中指定自定义命令。
1. 如果您为 `build_system` 指定 `custom`，请将 `custom_build_command` 添加到 `build` 对象中。在 `custom_build_command` 中，指定单个字符串或字符串列表，其中每个字符串都是命令中的一个单词。例如，要为 C\$1\$1 组件运行自定义构建命令，可以指定 **["cmake", "--build", "build", "--config", "Release"]**。
1. 如果您使用的是 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 将创建该存储桶。
更改组件的发布配置。执行以下操作：
1. 指定用于托管组件构件的 S3 存储桶的名称。
1. 指定供 GDK CLI 发布组件的 AWS 区域。
这一步完成后，`gdk-config.json` 文件可能类似于以下示例。
```
{
"component": {
"com.example.PythonHelloWorld": {
"author": "Amazon",
"version": "NEXT_PATCH",
"build": {
"build_system" : "zip"
},
"publish": {
"bucket": "greengrass-component-artifacts",
"region": "us-west-2"
}
}
},
"gdk_version": "1.0.0"
}
```
1. 更新名为 `recipe.yaml` 或 `recipe.json` 的组件配方文件。执行以下操作：
1. 如果您下载了使用 `zip` 构建系统的模板或社区组件，请检查 zip 构件名称是否与组件文件夹的名称相匹配。GDK CLI 将组件文件夹压缩成与组件文件夹同名的 ZIP 文件。配方在组件构件列表和使用 zip 构件中文件的生命周期脚本中包含 zip 构件名称。更新 `Artifacts` 和 `Lifecycle` 定义，使 zip 文件名与组件文件夹的名称相匹配。以下部分配方示例突出显示了 `Artifacts` 和 `Lifecycle` 定义中的 zip 文件名。
------
#### [ JSON ]
```
{
...
"Manifests": [
{
"Platform": {
"os": "all"
},
"Artifacts": [
{
"URI": "s3://{COMPONENT_NAME}/{COMPONENT_VERSION}/HelloWorld.zip",
"Unarchive": "ZIP"
}
],
"Lifecycle": {
"Run": "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}"
}
}
]
}
```
------
#### [ YAML ]
```
---
...
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}"
```
------
1. （可选）更新组件描述、默认配置、构件、生命周期脚本和平台支持。有关更多信息，请参阅 [AWS IoT Greengrass 组件配方参考](component-recipe-reference.md)。
这一步完成后，配方文件可能类似于以下示例。
------
#### [ JSON ]
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "{COMPONENT_NAME}",
"ComponentVersion": "{COMPONENT_VERSION}",
"ComponentDescription": "This is a simple Hello World component written in Python.",
"ComponentPublisher": "{COMPONENT_AUTHOR}",
"ComponentConfiguration": {
"DefaultConfiguration": {
"Message": "World"
}
},
"Manifests": [
{
"Platform": {
"os": "all"
},
"Artifacts": [
{
"URI": "s3://{COMPONENT_NAME}/{COMPONENT_VERSION}/HelloWorld.zip",
"Unarchive": "ZIP"
}
],
"Lifecycle": {
"Run": "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}"
}
}
]
}
```
------
#### [ YAML ]
```
---
RecipeFormatVersion: "2020-01-25"
ComponentName: "{COMPONENT_NAME}"
ComponentVersion: "{COMPONENT_VERSION}"
ComponentDescription: "This is a simple Hello World component written in Python."
ComponentPublisher: "{COMPONENT_AUTHOR}"
ComponentConfiguration:
DefaultConfiguration:
Message: "World"
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}"
```
------
1. 开发和构建 Greengrass 组件。[component build](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-build) 命令在组件文件夹的 `greengrass-build` 文件夹中生成配方和构件。运行以下命令。
```
gdk component build
```
准备测试组件时，使用 GDK CLI 将其发布到 AWS IoT Greengrass 服务。然后，可以将组件部署到 Greengrass 核心设备。有关更多信息，请参阅 [发布组件以部署到您的核心设备](publish-components.md)。
## 创建组件（Shell 命令）
按照本节中的说明，创建包含多个组件的源代码和构件的配方和构件文件夹。
**要开发 Greengrass 组件（Shell 命令），请执行以下操作**
1. 为您的组件创建一个文件夹，其中包含用于存放配方和构件的子文件夹。在 Greengrass 核心设备上运行以下命令来创建这些文件夹并更改为组件文件夹。将 *\$1/greengrassv2* 或 *%USERPROFILE%\$1greengrassv2* 替换为用于本地开发的文件夹路径。
------
#### [ Linux or Unix ]
```
mkdir -p ~/greengrassv2/{recipes,artifacts}
cd ~/greengrassv2
```
------
#### [ Windows Command Prompt (CMD) ]
```
mkdir %USERPROFILE%\greengrassv2\\recipes, %USERPROFILE%\greengrassv2\\artifacts
cd %USERPROFILE%\greengrassv2
```
------
#### [ PowerShell ]
```
mkdir ~/greengrassv2/recipes, ~/greengrassv2/artifacts
cd ~/greengrassv2
```
------
1. 使用文本编辑器创建配方文件，在该配方文件中定义组件的元数据、参数、依赖关系、生命周期和平台功能。在配方文件名中包含组件版本，以便您可以识别哪个配方对应哪个组件版本。您可以为配方选择 YAML 或 JSON 格式。
例如，在基于 Linux 的系统上，您可以运行以下命令来使用 GNU nano 创建该文件。
------
#### [ JSON ]
```
nano recipes/com.example.HelloWorld-1.0.0.json
```
------
#### [ YAML ]
```
nano recipes/com.example.HelloWorld-1.0.0.yaml
```
------
**注意**
AWS IoT Greengrass 使用组件的语义版本。语义版本遵循 *major*.*minor*.*patch* 编号系统。例如，版本 `1.0.0` 表示组件的第一个主要版本。有关更多信息，请参阅[语义版本规范](https://semver.org/)。
1. 为您的组件定义配方。有关更多信息，请参阅 [AWS IoT Greengrass 组件配方参考](component-recipe-reference.md)。
您的配方可能类似于以下 Hello World 示例配方。
------
#### [ JSON ]
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.HelloWorld",
"ComponentVersion": "1.0.0",
"ComponentDescription": "My first AWS IoT Greengrass component.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"Message": "world"
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"run": "python3 -u {artifacts:path}/hello_world.py {configuration:/Message}"
}
},
{
"Platform": {
"os": "windows"
},
"Lifecycle": {
"run": "py -3 -u {artifacts:path}/hello_world.py {configuration:/Message}"
}
}
]
}
```
------
#### [ YAML ]
```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.HelloWorld
ComponentVersion: '1.0.0'
ComponentDescription: My first AWS IoT Greengrass component.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
Message: world
Manifests:
- Platform:
os: linux
Lifecycle:
run: |
python3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
- Platform:
os: windows
Lifecycle:
run: |
py -3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
```
------
此配方运行 Hello World Python 脚本，该脚本可能类似于以下示例脚本。
```
import sys
message = "Hello, %s!" % sys.argv[1]
# Print the message to stdout, which Greengrass saves in a log file.
print(message)
```
1. 为要开发的组件版本创建文件夹。建议您为每个组件版本的构件使用单独的文件夹，以便您可以识别每个组件版本对应的构件。运行以下命令。
------
#### [ Linux or Unix ]
```
mkdir -p artifacts/com.example.HelloWorld/1.0.0
```
------
#### [ Windows Command Prompt (CMD) ]
```
mkdir artifacts/com.example.HelloWorld/1.0.0
```
------
#### [ PowerShell ]
```
mkdir artifacts/com.example.HelloWorld/1.0.0
```
------
**重要**
必须为构件文件夹路径使用以下格式。其中包括您在配方中指定的组件名称和版本。
```
artifacts/componentName/componentVersion/
```
1. 在上一步中创建的文件夹中为组件创建构件。构件可以包括软件、图像和组件使用的任何其他二进制文件。
组件准备就绪后，请[测试组件](test-components.md)。