Greengrass 開發工具包 CLI 配置文件 - AWS IoT Greengrass

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

Greengrass 開發工具包 CLI 配置文件

開AWS IoT Greengrass發套件命令列介面 (GDK CLI) 會從名為建置和發佈元件gdk-config.json的設定檔讀取。此組態檔案必須存在於元件儲存庫的根目錄中。您可以使用 GDK CLI init 指令,以此設定檔初始化元件儲存庫。

GDK CLI 設定檔案格式

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

gdk_version

與此元件相容的 GDK CLI 的最低版本。此值必須是行版本的其中一個 GDK CLI 版本。

component

此零組件的模型組態。

componentName
author

元件的作者或發行者。

version

元件的版本。請指定下列其中一項:

  • NEXT_PATCH— 當您選擇此選項時,GDK CLI 會在您發佈元件時設定版本。GDK CLI 會查詢AWS IoT Greengrass服務,以識別元件的最新發佈版本。然後,它會將版本設定為該版本之後的下一個修補程式版本。如果您之前尚未發佈元件,GDK CLI 會使用版本1.0.0

    如果您選擇此選項,則無法使用 Greengrass CLI 在本機部署元件,並將元件測試到執行 Core 軟體的本機開發電腦。AWS IoT Greengrass若要啟用本機部署,您必須改為指定語意版本。

  • 語義版本,例如1.0.0. 語義版本使用一個主要的。 未成年人補丁編號系統。如需詳細資訊,請參閱語意版本規格

    如果您在要部署和測試元件的 Greengrass 核心裝置上開發元件,請選擇此選項。您必須使用特定版本建立元件,才能使用 Greengr ass CLI 建立本機部署。

build

用來將此元件的來源建置為成品的組態。此物件包含下列資訊:

build_system

要使用的建置系統。您可以從以下選項中選擇:

  • zip— 將元件的資料夾封裝至 ZIP 檔案,以定義為元件的唯一人工因素。針對下列類型的元件選擇此選項:

    • 使用解譯式程式設計語言的元件,例如 Python 或 JavaScript.

    • 封裝程式碼以外檔案的元件,例如機器學習模型或其他資源。

    GDK CLI 會將元件的資料夾壓縮成與元件資料夾名稱相同的 zip 檔案。例如,如果元件資料夾的名稱是HelloWorld,GDK CLI 會建立一個名HelloWorld.zip為的 zip 檔案。

    注意

    如果您在 Windows 裝置上使用 GDK CLI 1.0.0 版,元件資料夾和壓縮檔案名稱必須只包含小寫字母。

    當 GDK CLI 將元件的資料夾壓縮至 zip 檔案時,會略過下列檔案:

    • gdk-config.json 檔案

    • 配方文件(recipe.jsonrecipe.yaml

    • 建置資料夾,例如 greengrass-build

  • maven— 執行指mvn clean package令,將元件的來源建置為成品。針對使用 Maven 的元件 (例如 Java 元件) 選擇此選項。

    在視窗裝置上,此功能適用於 GDK CLI 1.1.0 版及更新版本。

  • gradle— 執行指gradle build令,將元件的來源建置為成品。對於使用搖籃的組件,請選擇此選項。此功能適用於 GDK CLI 1.1.0 版及更新版本。

    gradle構建系統支持 Kotlin DSL 作為構建文件。此功能適用於 GDK CLI 1.2.0 版及更新版本。

  • gradlew— 執行指gradlew令,將元件的來源建置為成品。針對使用 Gradle 包裝函式的元件選擇此選項。

    此功能適用於 GDK CLI 1.2.0 版及更新版本。

  • custom— 執行自訂命令,將元件的來源建置到配方和成品中。在custom_build_command參數中指定自訂指令。

custom_build_command

(選擇性) 要針對自訂建置系統執行的自訂建置命令。如果您指定custom為,則必須指定此參數build_system

重要

此指令必須在元件資料夾內的下列資料夾中建立方案和人工因素。當您執行元件建置命令時,GDK CLI 會為您建立這些資料夾。

  • 食譜資料夾:greengrass-build/recipes

  • 成品資料夾:greengrass-build/artifacts/componentName/componentVersion

    元件名稱取代元件名稱,並以元件版本或取代元件版本NEXT_PATCH

您可以指定單一字串或字串清單,其中每個字串都是指令中的一個字。例如,若要執行 C++ 元件的自訂建置命令,您可以指定cmake --build build --config Release["cmake", "--build", "build", "--config", "Release"]

要查看自定義構建系統的示例,請參閱(詳見) GitHub。aws.greengrass.labs.LocalWebServer community component

options

(選擇性) 在元件建置程序期間使用的其他組態選項。

此功能適用於 GDK CLI 1.2.0 版及更新版本。

excludes

glob 模式清單,用於定義在構建 zip 文件時從組件目錄中排除哪些文件。只有在是時才build_system有效zip

注意

在 GDK CLI 版本 1.4.0 及更早版本中,任何符合排除清單中項目的檔案都會從元件的所有子目錄中排除。若要在 GDK CLI 1.5.0 版及更新版本中達**/到相同的行為,請在排除清單中的現有項目前加上。例如,*.txt將僅從目錄中排除文本文件; **/*.txt 將從所有目錄和子目錄中排除文本文件。

在 GDK CLI 版本 1.5.0 及更新版本中,如果在 GDK 配置檔案中定義,您可能會在元件建置期間看到警告。excludes若要停用此警告,請將環境變數設定GDK_EXCLUDES_WARN_IGNOREtrue

GDK CLI 一律會從壓縮檔案中排除下列檔案:

  • gdk-config.json 檔案

  • 配方文件(recipe.jsonrecipe.yaml

  • 建置資料夾,例如 greengrass-build

依預設,會排除下列檔案。但是,您可以使用excludes此選項控制要排除哪些檔案。

  • 以前綴「test」(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 v1.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 v1.3.0 或更新版本,則此屬性是可選的。

options

(選擇性) 建立元件版本期間使用的其他組態選項。

此功能適用於 GDK CLI 1.2.0 版及更新版本。

file_upload_args

JSON 結構,其中包含將檔案上傳至儲存貯體時傳送至 Amazon S3 的引數,例如中繼資料和加密機制。如需允許引數的清單,請參閱 Boto3 文件中的S3Transfer類別。 。

test-e2e

(選擇性) 元件 end-to-end 測試期間要使用的組態。此功能適用於 GDK CLI 版本 1.3.0 及更新版本。

build

build_system— 要使用的建置系統。預設選項為maven。您可以從以下選項中選擇:

  • maven-運行命mvn package令以構建測試模塊。選擇此選項以建立使用 Maven 的測試模組。

  • gradle-運行命gradle build令以構建測試模塊。為使用 Gradle 的測試模塊選擇此選項。

gtf_version

(可選)當您使用 GTF 初始化 GDK 項目時,Greengrass 測試框架(GTF)的版本用作 end-to-end 測試模塊的依賴項。該值必須是行版本的 GTF 版本之一。默認設置為 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 裝置憑證的現有憑證的 arn。

  • feature-path— 包含其他功能檔案的檔案或目錄。預設值是不使用其他功能檔案。

  • gg-cli-version-覆寫格 Greengrass CLI 的版本。預設為在中找到的值ggc.version

  • gg-component-bucket— 容納 Greengrass 元件的現有 Amazon S3 儲存貯體的名稱。

  • gg-component-overrides-綠色組件覆蓋的列表。

  • gg-persist-測試運行後要持續存在的測試元素列表。默認行為是什麼都不堅持。接受的值為:aws.resourcesinstalled.software、和generated.files

  • gg-runtime— 影響測試與測試資源互動方式的值清單。這些值會取代參gg.persist數。如果默認值為空,則假定所有測試資源都由測試用例管理,包括安裝的 Greengrass 運行時。接受的值為:aws.resourcesinstalled.software、和generated.files

  • ggc-archive— 路徑歸檔的 Greengrass 核組件.

  • ggc-install-root— 安裝 Greengrass 核組件的目錄. 默認為測試 .temp.path 和測試運行文件夾。

  • ggc-log-level— 為測試運行設置 Greengrass 核日誌級別。預設值為「資訊」。

  • ggc-tes-rolename— AWS IoT Greengrass 核心將承擔存取AWS服務的 IAM 角色。如果具有給定名稱的角色不存在,則將創建一個並默認訪問策略。

  • ggc-trusted-plugins— 需要添加到 Greengrass 的受信任插件的路徑(在主機上)的逗號分隔列表。要提供 DUT 本身的路徑,請在路徑前加上「dut:」

  • ggc-user-name— 使用者:群組 Greengrass 核的 PosixUser 值。預設為目前登入的使用者名稱。

  • ggc-version— 覆寫正在執行的 Greengrass 核元件的版本。默認為在 ggc.archive 中找到的值。

  • log-level— 測試運行的日誌級別。默認為「信息」。

  • parallel-config— 設置批次索引和批次數作為 JSON 字符串。批處理索引的默認值為 0,批次數為 1。

  • proxy-url— 配置所有測試以通過此 URL 路由流量。

  • tags— 僅執行功能標籤。可以與 '&' 相交

  • test-id-prefix— 應用於所有測試特定資源(包括資AWS源名稱和標籤)的通用前綴。預設值為「gg」前置詞。

  • test-log-path— 將包含整個測試運行結果的目錄。默認為「測試結果」。

  • test-results-json— 用於確定產生的黃瓜 JSON 報告是否產生寫入磁碟的旗標。預設為 true。

  • test-results-log— 用於確定控制台輸出是否生成寫入磁盤的標誌。預設為 false。

  • test-results-xml— 用於判斷產生的 JUnit XML 報告是否已產生寫入磁碟的旗標。預設為 true。

  • test-temp-path— 產生本機測試成品的目錄。默認為以 gg-test 前綴的隨機臨時目錄。

  • timeout-multiplier— 提供給所有測試超時的乘數。預設值為 1.0。

GDK CLI 設定檔範例

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

你好世界 (Python)

下面的 GDK CLI 配置文件支持運行一個 Python 腳本你好世界組件。此組態檔案會使用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" } }

你好世界

下面的 GDK CLI 配置文件支持運行 Java 應用程序的你好世界組件。此組態檔案會使用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 軟體目錄中的幾個社群元件都使用 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
  2. 在下列 URL 開啟社群元件的 GitHub 儲存庫。取代community-component-name為上一個步驟中社群元件的名稱。

    https://github.com/awslabs/community-component-name