本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 建立 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，以便在發佈元件時自動更新元件的版本和成品 URIs，因此您不需要每次更新配方。若要使用 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 會下載範本或社群元件，因此您可以從功能範例開始。使用[元件清單](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. 將範本或社群元件下載至目前的資料夾。使用 [元件 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 1.0.0 版，您必須在空的資料夾中執行此命令。GDK CLI 會將範本或社群元件下載到目前的資料夾。
如果您使用 GDK CLI 1.1.0 版或更新版本，您可以指定 `--name` 引數來指定 GDK CLI 下載範本或社群元件的資料夾。如果您使用此引數，請指定不存在的資料夾。GDK CLI 會為您建立 資料夾。如果您未指定此引數，GDK CLI 會使用目前的資料夾，該資料夾必須是空的。
1. GDK CLI 會從名為 的 [GDK CLI 組態檔案](gdk-cli-configuration-file.md)讀取`gdk-config.json`，以建置和發佈元件。此組態檔案存在於元件資料夾的根目錄中。上一個步驟會為您建立此檔案。在此步驟中，您會`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 核心軟體的本機開發電腦。若要啟用本機部署，您必須改為指定語意版本。
+ 語意版本，例如 **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 會建立名為 的 zip 檔案`HelloWorld.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 1.1.0 版及更新版本。
+ `gradle` – 執行 `gradle build`命令，將元件的來源建置為成品。針對使用 [Gradle](https://gradle.org/) 的元件選擇此選項。此功能適用於 GDK CLI 1.1.0 版及更新版本。
`gradle` 建置系統支援 Kotlin DSL 做為建置檔案。此功能適用於 GDK CLI 1.2.0 版及更新版本。
+ `gradlew` – 執行 `gradlew`命令，將元件的來源建置為成品。針對使用 [Gradle Wrapper ](https://docs.gradle.org/current/userguide/gradle_wrapper.html)的元件選擇此選項。
此功能適用於 GDK CLI 1.2.0 版及更新版本。
+ `custom` – 執行自訂命令，將元件的來源建置到配方和成品中。在 `custom_build_command` 參數中指定自訂命令。
1. 如果您`custom`為 指定 `build_system`，請將 `custom_build_command`新增至 `build` 物件。在 中`custom_build_command`，指定單一字串或字串清單，其中每個字串都是 命令中的字詞。例如，若要執行 C\$1\$1 元件的自訂建置命令，您可以指定 **["cmake", "--build", "build", "--config", "Release"]**。
1. 如果您使用 GDK CLI 1.1.0 版或更新版本，您可以指定 `--bucket` 引數來指定 GDK CLI 上傳元件成品的 S3 儲存貯體。如果您未指定此引數，GDK CLI 會上傳至名稱為 的 S3 儲存貯體`bucket-region-accountId`，其中*儲存貯*體和*區域*是您在 中指定的值`gdk-config.json`，而 *accountId* 是您的 AWS 帳戶 ID。如果儲存貯體不存在，GDK CLI 會建立儲存貯體。
變更元件的發佈組態。請執行下列操作：
1. 指定用於託管元件成品的 S3 儲存貯體名稱。
1. 指定 AWS 區域 GDK CLI 發佈元件的 。
當您完成此步驟時，`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 元件。[元件建置](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)。