本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS IoT Greengrass 開發套件命令列介面
AWS IoT Greengrass 開發套件命令列界面 (GDK CLI) 提供可協助您開發[自訂 Greengrass 元件](develop-greengrass-components.md)的功能。您可以使用 GDK CLI 來建立、建置和發佈自訂元件。當您使用 GDK CLI 建立元件儲存庫時，您可以從範本或 [Greengrass 軟體目錄中](greengrass-software-catalog.md)的社群元件開始。然後，您可以選擇建置系統，將檔案封裝為 ZIP 封存檔、使用 Maven 或 Gradle 建置指令碼，或執行自訂建置命令。建立元件後，您可以使用 GDK CLI 將其發佈至 AWS IoT Greengrass 服務，以便您可以使用 AWS IoT Greengrass 主控台或 API 將元件部署至 Greengrass 核心裝置。
當您在沒有 GDK CLI 的情況下開發 Greengrass 元件時，每次建立新的元件版本時，都必須更新[元件配方檔案中](component-recipe-reference.md)的版本和成品 URIs。當您使用 GDK CLI 時，它可以在每次發佈新版本的元件時自動為您更新版本和成品 URIs。
GDK CLI 是開放原始碼，可在 GitHub 上使用。您可以自訂和擴展 GDK CLI，以滿足元件開發需求。我們邀請您在 GitHub 儲存庫上開啟問題並提取請求。您可以在以下連結找到 GDK CLI 來源：https：//[https://github.com/aws-greengrass/aws-greengrass-gdk-cli](https://github.com/aws-greengrass/aws-greengrass-gdk-cli)。
## 先決條件
若要安裝和使用 Greengrass 開發套件 CLI，您需要下列項目：
+ AWS 帳戶：如果您沒有帳戶，請參閱 [設定 AWS 帳戶](setting-up.md#set-up-aws-account)。
+ 具有網際網路連線的 Windows、macOS 或類似 Unix 的開發電腦。
+ 對於 GDK CLI 1.1.0 版或更新版本，[Python](https://www.python.org/downloads/) 3.6 或更新版本會安裝在開發電腦上。
對於 GDK CLI 1.0.0 版，[Python](https://www.python.org/downloads/) 3.8 或更新版本安裝在開發電腦上。
+ 安裝在開發電腦上的 [Git](https://git-scm.com/)。
+ AWS Command Line Interface (AWS CLI) 在開發電腦上安裝並設定 憑證。如需詳細資訊，請參閱*AWS Command Line Interface 《 使用者指南*》中的[安裝、更新和解除安裝 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) 和[設定 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)。
**注意**
如果您使用 Raspberry Pi 或其他 32 位元 ARM 裝置，則 install AWS CLI V1. AWS CLI V2 不適用於 32 位元 ARM 裝置。如需詳細資訊，請參閱[安裝、更新和解除安裝 AWS CLI 版本 1](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv1.html)。
+ 若要使用 GDK CLI 將元件發佈至 AWS IoT Greengrass 服務，您必須具有下列許可：
+ `s3:CreateBucket`
+ `s3:GetBucketLocation`
+ `s3:PutObject`
+ `greengrass:CreateComponentVersion`
+ `greengrass:ListComponentVersions`
+ 若要使用 GDK CLI 來建置其成品存在於 S3 儲存貯體而非本機檔案系統中的元件，您必須具有下列許可：
+ `s3:ListBucket`
此功能適用於 GDK CLI 1.1.0 版及更新版本。
## 變更記錄
下表說明每個 GDK CLI 版本中的變更。如需詳細資訊，請參閱 GitHub 上的 [GDK CLI 版本頁面](https://github.com/aws-greengrass/aws-greengrass-gdk-cli/releases)。
| **版本** | **變更** |
| --- | --- |
| 1.6.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.6.1 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.6.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.5.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.4.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.3.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.2.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.2.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.2.1 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.2.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.0.0 | 初始版本。 |
# 安裝或更新 AWS IoT Greengrass 開發套件命令列界面
AWS IoT Greengrass 開發套件命令列界面 (GDK CLI) 是以 Python 為基礎，因此您可以使用 `pip`將其安裝在開發電腦上。
**提示**
您也可以在 Python 虛擬環境中安裝 GDK CLI，例如 [venv](https://docs.python.org/3/library/venv.html#module-venv)。如需詳細資訊，請參閱 *Python 3 文件*中的[虛擬環境和套件](https://docs.python.org/3/tutorial/venv.html)。
**安裝或更新 GDK CLI**
1. 執行下列命令，從其 [GitHub 儲存庫](https://github.com/aws-greengrass/aws-greengrass-gdk-cli)安裝最新版本的 GDK CLI。
```
python3 -m pip install -U git+https://github.com/aws-greengrass/aws-greengrass-gdk-cli.git@v1.6.2
```
**注意**
若要安裝特定版本的 GDK CLI，請將 *versionTag* 取代為要安裝的版本標籤。您可以在其 [GitHub 儲存庫](https://github.com/aws-greengrass/aws-greengrass-gdk-cli/tags)中檢視 GDK CLI 的版本標籤。
```
python3 -m pip install -U git+https://github.com/aws-greengrass/aws-greengrass-gdk-cli.git@versionTag
```
1. 執行下列命令來驗證 GDK CLI 是否已成功安裝。
```
gdk --help
```
如果找不到 `gdk`命令，請將其資料夾新增至 PATH。
+ 在 Linux 裝置上，將 `/home/MyUser/.local/bin` 新增至 PATH，並以您的使用者名稱取代 *MyUser*。
+ 在 Windows 裝置上，將 `PythonPath\\Scripts` 新增至 PATH，並將 *PythonPath* 取代為您裝置上的 Python 資料夾路徑。
您現在可以使用 GDK CLI 來建立、建置和發佈 Greengrass 元件。如需如何使用 GDK CLI 的詳細資訊，請參閱[AWS IoT Greengrass 開發套件命令列界面命令](greengrass-development-kit-cli-commands.md)。
# AWS IoT Greengrass 開發套件命令列界面命令
Development AWS IoT Greengrass Kit Command-Line Interface (GDK CLI) 提供命令列介面，可用於在開發電腦上建立、建置和發佈 Greengrass 元件。GDK CLI 命令使用以下格式。
```
gdk [arguments]
```
[安裝 GDK CLI](install-greengrass-development-kit-cli.md) 時，安裝程式會`gdk`新增至 PATH，以便您可以從命令列執行 GDK CLI。
您可以搭配任何命令使用下列引數：
+ 如需 GDK CLI 命令的相關資訊，`--help`請使用 `-h`或 。
+ 使用 `-v`或 `--version` 來查看已安裝的 GDK CLI 版本。
+ 使用 `-d`或 `--debug`輸出詳細日誌，您可以用來偵錯 GDK CLI。
本節說明 GDK CLI 命令，並提供每個命令的範例。每個命令的摘要會顯示其引數及其用量。選用引數以方括號顯示。
**Topics**
+ [元件](greengrass-development-kit-cli-component.md)
+ [config](greengrass-development-kit-cli-config.md)
+ [test-e2e](greengrass-development-kit-cli-test.md)
# 元件
使用 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
```
# config
使用 AWS IoT Greengrass 開發套件命令列界面 (GDK CLI) 中的 `config` 命令來修改組態檔案中的 GDK 組態`gdk-config.json`。
**Topics**
+ [update](#greengrass-development-kit-cli-config-update)
## update
啟動互動式提示來修改現有 GDK 組態檔案中的欄位。
**概要**
```
$ gdk config update
[--component]
```
**Arguments (引數)**
+ `-c`， `--component` – 更新 `gdk-config.json` 檔案中與元件相關的欄位。此引數是必要的，因為它是唯一的選項。
**輸出**
下列範例顯示執行此命令以設定元件時產生的輸出。
```
$ gdk config update --component
Current value of the REQUIRED component_name is (default: com.example.PythonHelloWorld):
Current value of the REQUIRED author is (default: author):
Current value of the REQUIRED version is (default: NEXT_PATCH):
Do you want to change the build configurations? (y/n)
Do you want to change the publish configurations? (y/n)
[2023-09-26 10:19:48] INFO - Config file has been updated. Exiting...
```
# test-e2e
使用 AWS IoT Greengrass 開發套件命令列界面 (GDK CLI) 中的 `test-e2e`命令，在 GDK 專案中初始化、建置和執行end-to-end測試模組。
**Topics**
+ [init](#greengrass-development-kit-cli-test-init)
+ [build](#greengrass-development-kit-cli-test-build)
+ [run](#greengrass-development-kit-cli-test-run)
## init
使用使用 Greengrass 測試架構 (GTF) 的測試模組初始化現有的 GDK CLI 專案。
根據預設，GDK CLI 會從 [AWS IoT Greengrass GitHub 上的元件範本儲存庫擷取數學模組範本](https://github.com/aws-greengrass/aws-greengrass-component-templates)。此 maven 模組隨附 `aws-greengrass-testing-standalone` JAR 檔案的相依性。
此命令會在 GDK 專案`gg-e2e-tests`內建立新的目錄，稱為 。如果測試模組目錄已存在且不是空的，則命令會結束而不執行任何動作。此`gg-e2e-tests`資料夾包含在 maven 專案中建構的 Cucumber 功能和步驟定義。
根據預設，此命令會嘗試使用最新版本的 GTF。
**概要**
```
$ gdk test-e2e init
[--gtf-version]
```
**Arguments (引數)**
+ `-ov`、 `--gtf-version` – （選用） GTF 的版本，用於 GDK 專案中的end-to-end測試模組。此值必須是版本中的[其中一個 GTF ](https://github.com/aws-greengrass/aws-greengrass-testing/releases)版本。此引數會覆寫 GDK CLI 組態`gtf_version`中的 。
**輸出**
下列範例顯示執行此命令以使用測試模組初始化 GDK 專案時產生的輸出。
```
$ gdk test-e2e init
[2023-12-06 12:20:28] INFO - Using the GTF version provided in the GDK test config 1.2.0
[2023-12-06 12:20:28] INFO - Downloading the E2E testing template from GitHub into gg-e2e-tests directory...
```
## build
**注意**
您必須先執行 來建置元件，**gdk component build**end-to-end測試模組。
建置end-to-end測試模組。GDK CLI 會使用您在 `test-e2e` 屬性下的 [GDK CLI 組態檔案中](gdk-cli-configuration-file.md)指定的建置系統`gdk-config.json`來建置測試模組。您必須在`gdk-config.json`檔案存在的相同資料夾中執行此命令。
根據預設，GDK CLI 會使用 maven 建置系統來建置測試模組。執行 `gdk test-e2e build`命令需要 [Maven](https://maven.apache.org/)。
如果測試功能檔案具有 `GDK_COMPONENT_NAME`和 等變數`GDK_COMPONENT_RECIPE_FILE`來插補，則必須先執行 來建置元件，**gdk-component-build**才能建置測試模組。
當您執行此命令時，GDK CLI 會從 GDK 專案組態插入所有變數，並建置`gg-e2e-tests`模組以產生最終測試 JAR 檔案。
**概要**
```
$ gdk test-e2e build
```
**Arguments (引數)**
無
**輸出**
下列範例顯示執行此命令時產生的輸出。
```
$ gdk test-e2e build
[2023-07-20 15:36:48] INFO - Updating feature file: file:///path/to//HelloWorld/greengrass-build/gg-e2e-tests/src/main/resources/greengrass/features/component.feature
[2023-07-20 15:36:48] INFO - Creating the E2E testing recipe file:///path/to/HelloWorld/greengrass-build/recipes/e2e_test_recipe.yaml
[2023-07-20 15:36:48] INFO - Building the E2E testing module
[2023-07-20 15:36:48] INFO - Running the build command 'mvn package'
.........
```
## run
使用 GDK 組態檔案中的測試選項執行測試模組。
**注意**
您必須先執行 來建置測試模組，**gdk test-e2e build**end-to-end測試。
**概要**
```
$ gdk test-e2e run
[--gtf-options]
```
**Arguments (引數)**
+ `-oo`， `--gtf-options` – （選用） 指定執行end-to-end測試的選項清單。引數必須是有效的 JSON 字串或包含 GTF 選項的 JSON 檔案路徑。組態檔案中提供的選項會與命令引數中提供的選項合併。如果兩個位置都有 選項，則引數中的一個會比組態檔案中的某個選項有前置。
如果此命令中未指定 `tags`選項，則 GDK 會使用 `Sample`進行標籤。如果`ggc-archive`未指定 ，則 GDK 會下載最新版本的 Greengrass 核封存。
**輸出**
下列範例顯示執行此命令時產生的輸出。
```
$ gdk test-e2e run
[2023-07-20 16:35:53] INFO - Downloading latest nucleus archive from url https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-latest.zip
[2023-07-20 16:35:57] INFO - Running test jar with command java -jar /path/to/greengrass-build/gg-e2e-tests/target/uat-features-1.0.0.jar —ggc-archive=/path/to/aws-greengrass-gdk-cli/HelloWorld/greengrass-build/greengrass-nucleus-latest.zip —tags=Sample
16:35:59.693 [] [] [] [INFO] com.aws.greengrass.testing.modules.GreengrassContextModule - Extracting /path/to/workplace/aws-greengrass-gdk-cli/HelloWorld/greengrass-build/greengrass-nucleus-latest.zip into /var/folders/7g/ltzcb_3s77nbtmkzfb6brwv40000gr/T/gg-testing-7718418114158172636/greengrass
16:36:00.534 [gtf-1.1.0-SNAPSHOT] [] [] [INFO] com.aws.greengrass.testing.features.LoggerSteps - GTF Version is gtf-1.1.0-SNAPSHOT
.......
```
# Greengrass 開發套件 CLI 組態檔案
AWS IoT Greengrass Development Kit Command-Line Interface (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 組態檔案格式
當您定義元件的 GDK CLI 組態檔案時，請以 JSON 格式指定下列資訊。
`gdk_version`
與此元件相容的 GDK CLI 最低版本。此值必須是 [版本的](https://github.com/aws-greengrass/aws-greengrass-gdk-cli/releases)其中一個 GDK CLI 版本。
`component`
此元件的組態。
`componentName`
`author`
元件的作者或發佈者。
`version`
元件的版本。請指定下列其中一項：
+ `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`
要使用的建置系統。您可以從以下選項中選擇：
+ `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` 參數中指定自訂命令。
`custom_build_command`
（選用） 要為自訂建置系統執行的自訂建置命令。如果您`custom`為 指定 ，則必須指定此參數`build_system`。
此命令必須在元件資料夾中的下列資料夾中建立配方和成品。當您執行[元件建置命令](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"]**。
若要檢視自訂建置系統的範例，請參閱 [aws.greengrass.labs.LocalWebServer community component GitHub 上的](https://github.com/awslabs/aws-greengrass-labs-local-web-server) 。
`options`
（選用） 元件建置程序期間使用的其他組態選項。
此功能適用於 GDK CLI 1.2.0 版及更新版本。
`excludes`
定義建置 zip 檔案時要從元件目錄中排除哪些檔案的 glob 模式清單。只有在 `build_system`為 時才有效`zip`。
在 GDK CLI 1.4.0 版及更早版本中，符合排除清單中項目的任何檔案都會從元件的所有子目錄中排除。若要在 GDK CLI 1.5.0 版和更新版本中實現相同的行為，請在排除清單中`**/`的現有項目前面。例如， `*.txt` 只會從 目錄排除文字檔案； `**/*.txt`會從所有目錄和子目錄中排除文字檔案。
在 GDK CLI 1.5.0 版及更新版本中，當 `excludes` GDK 組態檔案中定義 時，您可能會在元件建置期間看到警告。若要停用此警告，請將環境變數`GDK_EXCLUDES_WARN_IGNORE`設定為 `true`。
GDK CLI 一律會從 zip 檔案排除下列檔案：
+ `gdk-config.json` 檔案
+ 配方檔案 (`recipe.json` 或 `recipe.yaml`)
+ 建置資料夾，例如 `greengrass-build`
預設會排除下列檔案。不過，您可以使用 `excludes`選項來控制哪些檔案遭到排除。
+ 任何以字首「測試」開頭的資料夾 (`test*`)
+ 所有隱藏的檔案
+ `node_modules` 資料夾
如果您指定 `excludes`選項，GDK CLI 只會排除您使用 `excludes`選項設定的檔案。如果您未指定 `excludes`選項，GDK CLI 會排除先前記下的預設檔案和資料夾。
`zip_name`
在建置過程中建立 zip 成品時要使用的 zip 檔案名稱。只有在 `build_system`為 時才有效`zip`。如果 `build_system`是空的，元件名稱會用於 zip 檔案名稱。
`publish`
用來將此元件發佈至 AWS IoT Greengrass 服務的組態。
如果您使用 GDK CLI 1.1.0 版或更新版本，您可以指定`--bucket`引數來指定 GDK CLI 上傳元件成品的 S3 儲存貯體。如果您未指定此引數，GDK CLI 會上傳到名稱為 的 S3 儲存貯體`bucket-region-accountId`，其中儲存*貯*體和*區域*是您在 中指定的值`gdk-config.json`，而 *accountId* 是您的 AWS 帳戶 ID。如果儲存貯體不存在，GDK CLI 會建立儲存貯體。
此物件包含下列資訊：
`bucket`
用來託管元件成品的 S3 儲存貯體名稱。
`region`
GDK CLI 發佈此元件 AWS 區域 的 。
如果您使用 GDK CLI 1.3.0 版或更新版本，則此屬性為選用。
`options`
（選用） 元件版本建立期間使用的其他組態選項。
此功能適用於 GDK CLI 1.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)類別。 *Boto3 *
`test-e2e`
（選用） 在元件的end-to-end測試期間使用的組態。此功能適用於 GDK CLI 1.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 專案時，做為end-to-end測試模組相依性的 Greengrass 測試架構 (GTF) 版本。此值必須是版本中的[其中一個 GTF ](https://github.com/aws-greengrass/aws-greengrass-testing/releases)版本。預設為 GTF 1.1.0 版。
`gtf_options`
（選用） 在元件的end-to-end測試期間使用的其他組態選項。
下列清單包含您可以搭配 GTF 1.1.0 版使用的選項。
+ `additional-plugins` – （選用） 其他小黃瓜外掛程式
+ `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 裝置憑證的現有憑證的生成。
+ `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 核元件的路徑。
+ `ggc-install-root` – 安裝 Greengrass 核元件的目錄。預設為 test.temp.path 和 test run 資料夾。
+ `ggc-log-level` – 設定測試執行的 Greengrass 核日誌層級。預設為「INFO」。
+ `ggc-tes-rolename` – Core AWS IoT Greengrass 將擔任以存取 AWS 服務的 IAM 角色。如果指定名稱的角色不存在，則會建立一個 和預設存取政策。
+ `ggc-trusted-plugins` – 需要新增至 Greengrass 的信任外掛程式路徑 （主機上） 的逗號分隔清單。若要提供 DUT 本身的路徑，請在路徑前面加上 'dut：'
+ `ggc-user-name` – Greengrass 核的 user：group posixUser 值。預設為目前登入的使用者名稱。
+ `ggc-version` – 覆寫執行中 Greengrass 核元件的版本。預設為 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 組態檔案範例
您可以參考下列 GDK CLI 組態檔案範例，協助您設定 Greengrass 元件環境。
### Hello World (Python)
下列 GDK CLI 組態檔案支援執行 Python 指令碼的 Hello World 元件。此組態檔案使用`zip`建置系統，將元件的 Python 指令碼封裝到 ZIP 檔案中，而 GDK CLI 會上傳為成品。
```
{
"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)
下列 GDK CLI 組態檔案支援執行 Java 應用程式的 Hello World 元件。此組態檔案使用`maven`建置系統，將元件的 Java 原始碼封裝到 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"
}
}
```
### 社群元件
[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
```