本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Greengrass 開發套件 CLI 組態檔案
<a name="gdk-cli-configuration-file"></a>

 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 組態檔案格式
<a name="gdk-config-format"></a>

當您定義元件的 GDK CLI 組態檔案時，請以 JSON 格式指定下列資訊。

`gdk_version`  
與此元件相容的 GDK CLI 最低版本。此值必須是 [版本的](https://github.com/aws-greengrass/aws-greengrass-gdk-cli/releases)其中一個 GDK CLI 版本。

`component`  
此元件的組態。    
`componentName`    
`author`  
元件的作者或發佈者。  
`version`  
元件的版本。請指定下列其中一項：  <a name="gdk-cli-configuration-file-component-version-options"></a>
+ `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`   
要使用的建置系統。您可以從以下選項中選擇：  <a name="gdk-cli-configuration-file-component-build-system-options"></a>
+ `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 服務的組態。  
<a name="gdk-cli-s3-bucket-name-formation"></a>如果您使用 GDK CLI 1.1.0 版或更新版本，您可以指定`--bucket`引數來指定 GDK CLI 上傳元件成品的 S3 儲存貯體。<a name="gdk-cli-s3-bucket-name-formation-format"></a>如果您未指定此引數，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測試期間使用的其他組態選項。  
<a name="gtf_options"></a>下列清單包含您可以搭配 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 組態檔案範例
<a name="gdk-config-examples"></a>

您可以參考下列 GDK CLI 組態檔案範例，協助您設定 Greengrass 元件環境。

### Hello World (Python)
<a name="gdk-config-example-hello-world-python"></a>

下列 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)
<a name="gdk-config-example-hello-world-java"></a>

下列 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"
  }
}
```

### 社群元件
<a name="gdk-config-community-component-examples"></a>

[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
   ```