本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 元件
使用 AWS IoT Greengrass 開發套件命令列界面 (GDK CLI) 中的 `component`命令來建立、建置和發佈自訂 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
從元件範本或社群元件初始化 Greengrass 元件資料夾。
GDK CLI 從 [Greengrass 軟體目錄](greengrass-software-catalog.md)擷取社群元件，並從 [AWS IoT Greengrass GitHub 上的元件範本儲存庫擷取元件範本](https://github.com/aws-greengrass/aws-greengrass-component-templates)。
**注意**
如果您使用 GDK CLI 1.0.0 版，您必須在空的資料夾中執行此命令。GDK CLI 會將範本或社群元件下載到目前的資料夾。
如果您使用 GDK CLI 1.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 會建立名為 的 zip 檔案`HelloWorld.zip`。在元件配方中， zip 成品名稱必須符合元件資料夾的名稱。如果您在 Windows 裝置上使用 GDK CLI 1.0.0 版，元件資料夾和 zip 檔案名稱只能包含小寫字母。
如果您將範本或社群元件初始化為使用 zip build 系統的資料夾，其名稱與範本或元件不同，則必須在元件配方中變更 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` – 用於本機元件專案的元件範本。若要檢視可用的範本，請使用[清單](#greengrass-development-kit-cli-component-list)命令。
您必須指定 `--repository`或 `--language`和 `--template`。
+ `-n`， `--name` – （選用） GDK CLI 初始化元件的本機資料夾名稱。指定不存在的資料夾。GDK CLI 會為您建立 資料夾。
此功能適用於 GDK CLI 1.1.0 版及更新版本。
**引數 （從社群元件初始化）**
+ `-r`， `--repository` – 要簽出至本機資料夾的社群元件。若要檢視可用的社群元件，請使用 [list](#greengrass-development-kit-cli-component-list) 命令。
您必須指定 `--repository`或 `--language`和 `--template`。
+ `-n`， `--name` – （選用） GDK CLI 初始化元件的本機資料夾名稱。指定不存在的資料夾。GDK CLI 會為您建立 資料夾。
此功能適用於 GDK CLI 1.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
將元件的來源建置到您可以發佈到服務的配方和成品中 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 1.1.0 版或更新版本，元件配方可以指定 S3 儲存貯體中存在的成品，但不能指定本機元件建置資料夾中存在的成品。當您開發具有大型成品的元件時，您可以使用此功能來減少頻寬用量，例如機器學習模型。
建置元件之後，您可以執行下列其中一項操作，在 Greengrass 核心裝置上進行測試：
+ 如果您在與執行 AWS IoT Greengrass Core 軟體不同的裝置上開發 ，則必須發佈元件，將其部署到 Greengrass 核心裝置。將元件發佈至 AWS IoT Greengrass 服務，並將其部署至 Greengrass 核心裝置。如需詳細資訊，請參閱[發佈](#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
```
**Arguments (引數)**
無
**輸出**
下列範例顯示執行此命令時產生的輸出。
```
$ 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'.
```
## 發布
將此元件發佈至 AWS IoT Greengrass 服務。此命令會將建置成品上傳至 S3 儲存貯體、更新配方中的成品 URI，以及從配方建立新的版本元件。GDK CLI 使用您在 GDK [CLI 組態檔案中](gdk-cli-configuration-file.md)指定的 S3 儲存貯體和 AWS 區域`gdk-config.json`。您必須在`gdk-config.json`檔案存在的相同資料夾中執行此命令。
如果您使用 GDK CLI 1.1.0 版或更新版本，您可以指定`--bucket`引數來指定 GDK CLI 上傳元件成品的 S3 儲存貯體。如果您未指定此引數，GDK CLI 會上傳到名稱為 的 S3 儲存貯體`bucket-region-accountId`，其中儲存*貯*體和*區域*是您在 中指定的值`gdk-config.json`，而 *accountId* 是您的 AWS 帳戶 ID。如果儲存貯體不存在，GDK CLI 會建立儲存貯體。
如果您使用 GDK CLI 1.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 1.1.0 版或更新版本，當您執行此命令時，GDK CLI 會檢查元件是否已建置。如果未建置元件，則 GDK CLI [會在發佈元件之前建置](#greengrass-development-kit-cli-component-build)元件。
**概要**
```
$ gdk component publish
[--bucket] [--region] [--options]
```
**Arguments (引數)**
+ `-b`， `--bucket` – （選用） 指定 GDK CLI 發佈元件成品的 S3 儲存貯體名稱。
如果您未指定此引數，GDK CLI 會上傳到名稱為 的 S3 儲存貯體`bucket-region-accountId`，其中儲存*貯*體和*區域*是您在 中指定的值`gdk-config.json`，而 *accountId* 是您的 AWS 帳戶 ID。如果儲存貯體不存在，GDK CLI 會建立儲存貯體。
如果儲存貯體不存在，GDK CLI 會建立儲存貯體。
此功能適用於 GDK CLI 1.1.0 版及更新版本。
+ `-r`， `--region` – （選用） 建立元件時，將 的名稱指定 AWS 區域 為 。此引數會覆寫 GDK CLI 組態中的區域名稱。
此功能適用於 GDK CLI 1.2.0 版及更新版本。
+ `-o`，`--options`（選用） 指定發佈元件的選項清單。引數必須是有效的 JSON 字串或包含發佈選項的 JSON 檔案路徑。此引數會覆寫 GDK CLI 組態中的選項。
此功能適用於 GDK CLI 1.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'.
```
## 列出
擷取可用元件範本和社群元件的清單。
GDK CLI 從 [Greengrass 軟體目錄](greengrass-software-catalog.md)擷取社群元件，並從 [AWS IoT Greengrass GitHub 上的元件範本儲存庫擷取元件範本](https://github.com/aws-greengrass/aws-greengrass-component-templates)。
您可以將此命令的輸出傳遞至 [init](#greengrass-development-kit-cli-component-init) 命令，以從範本和社群元件初始化元件儲存庫。
**概要**
```
$ gdk component list
[--template]
[--repository]
```
**Arguments (引數)**
+ `-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
```