建立 AWS IoT Greengrass 元件 - AWS IoT Greengrass

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

建立 AWS IoT Greengrass 元件

您可以在本機開發電腦或 Greengrass 核心裝置上開發自訂 AWS IoT Greengrass 元件。 AWS IoT Greengrass 提供AWS IoT Greengrass 開發套件命令列介面 (GDK CLI),協助您從預先定義的元件範本和社群元件建立、建置和發佈元件。您也可以執行內建 shell 命令來建立、建置和發佈元件。從下列選項中選擇以建立自訂 Greengrass 元件:

  • 使用格 Greengrass 開發工具包 CLI

    使用 GDK CLI 在本機開發電腦上開發元件。GDK CLI 會建置元件原始程式碼,並將其封裝到方案和成品中,您可以將其作為私有元件發佈至 AWS IoT Greengrass 服務。您可以將 GDK CLI 設定為在發佈元件時自動更新元件的版本和成品 URI,因此您不需要每次都更新配方。若要使用 GDK CLI 開發元件,您可以從 Greengr ass 軟體目錄中的範本或社群元件開始。如需詳細資訊,請參閱 AWS IoT Greengrass開發套件命令列介面

  • 執行內建殼層命令

    您可以執行內建的殼層命令,在本機開發電腦或 Greengrass 核心裝置上開發元件。您可以使用 shell 命令將組件源代碼複製或構建到成品中。每次建立元件的新版本時,都必須使用新的元件版本來建立或更新方案。當您將元件發佈至 AWS IoT Greengrass 服務時,必須更新方案中每個元件人工因素的 URI。

建立元件 (GDK CLI)

請遵循本節中的指示,使用 GDK CLI 建立和建置元件。

若要開發一個 Greengrass 元件 (GDK CLI)
  1. 如果您尚未安裝,請在開發電腦上安裝 GDK CLI。如需詳細資訊,請參閱 安裝或更新AWS IoT Greengrass開發套件命令列介面

  2. 切換至要在其中建立元件資料夾的資料夾。

    Linux or Unix
    mkdir ~/greengrassv2 cd ~/greengrassv2
    Windows Command Prompt (CMD)
    mkdir %USERPROFILE%\greengrassv2 cd %USERPROFILE%\greengrassv2
    PowerShell
    mkdir ~/greengrassv2 cd ~/greengrassv2
  3. 選擇要下載的元件範本或社群元件。GDK CLI 會下載範本或社群元件,因此您可以從功能範例開始。使用元件清單指令擷取可用樣板或社群元件的清單。

    • 若要列示元件樣板,請執行下列命令。回應中的每一行都包含範本的名稱和程式設計語言。

      gdk component list --template
    • 若要列出社群元件,請執行下列命令。

      gdk component list --repository
  4. 建立並變更為 GDK CLI 下載範本或社群元件的元件資料夾。以元件HelloWorld的名稱或其他可協助您識別此元件資料夾的名稱取代。

    Linux or Unix
    mkdir HelloWorld cd HelloWorld
    Windows Command Prompt (CMD)
    mkdir HelloWorld cd HelloWorld
    PowerShell
    mkdir HelloWorld cd HelloWorld
  5. 將範本或社群元件下載到目前的資料夾。使用組件初始化命令。

    • 若要從樣板建立元件資料夾,請執行下列指令。HelloWorld替換為模板的名稱,並用編程語言的名稱替換 python

      gdk component init --template HelloWorld --language python
    • 若要從社群元件建立元件資料夾,請執行下列指令。ComponentName以社群元件的名稱取代。

      gdk component init --repository ComponentName
    注意

    如果您使用 GDK CLI v1.0.0,則必須在空白資料夾中執行此命令。GDK CLI 會將範本或社群元件下載到目前的資料夾。

    如果您使用 GDK CLI v1.1.0 或更新版本,您可以指定--name引數來指定 GDK CLI 下載範本或社群元件的資料夾。如果您使用此引數,請指定不存在的資料夾。GDK CLI 會為您建立資料夾。如果您未指定此引數,GDK CLI 會使用目前的資料夾,該資料夾必須為空白。

  6. GDK CLI 會從名為的 GDK CLI 組態檔讀取gdk-config.json,以建置和發佈元件。此組態檔案存在於元件資料夾的根目錄中。上一步會為您建立此檔案。在此步驟中,您會更新gdk-config.json元件的相關資訊。請執行下列操作:

    1. 在文字編輯器中開啟 gdk-config.json

    2. (選擇性) 變更元件的名稱。元件名稱是component物件中的關鍵字。

    3. 變更元件的作者。

    4. (選擇性) 變更元件的版本。請指定下列其中一項:

      • 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 建立本機部署。

    5. (選擇性) 變更元件的組建組態。組建組態會定義 GDK CLI 如何將元件的來源建置成品。從下列選項中選擇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參數中指定自訂指令。

    6. 如果您指定custombuild_system,請將新增custom_build_commandbuild物件。在中custom_build_command,指定單一字串或字串清單,其中每個字串都是指令中的一個字。例如,若要執行 C++ 元件的自訂建置命令,您可以指定["cmake", "--build", "build", "--config", "Release"]

    7. 如果您使用 GDK CLI v1.1.0 或更新版本,則可以指定--bucket引數來指定 GDK CLI 上傳元件成品的 S3 儲存貯體。如果您未指定此引數,GDK CLI 會上傳至名稱為的 S3 儲存貯體bucket-region-accountId,其中儲存體和區域是您在中指定的值gdk-config.json,而 accountId 就是您 AWS 帳戶 的 ID。GDK CLI 會建立值區 (如果值區不存在)。

      變更元件的發佈規劃。請執行下列操作:

      1. 指定用於託管元件成品的 S3 儲存貯體名稱。

      2. 指定 GDK CLI 發佈元件的 AWS 區域 位置。

    完成此步驟後,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" }
  7. 更新名為recipe.yaml或的元件方案檔案recipe.json。請執行下列操作:

    1. 如果您下載了使用組zip建系統的範本或社群元件,請檢查 zip 成品名稱是否與元件資料夾的名稱相符。GDK CLI 會將元件資料夾壓縮成與元件資料夾名稱相同的 zip 檔案。方案會在元件人工因素清單以及使用 zip 加工品中檔案的生命週期指令碼中包含 zip 人工因素名稱。更新Artifacts和定Lifecycle義,使 zip 檔案名稱與元件資料夾的名稱相符。下列部分方案範例會強調顯示ArtifactsLifecycle定義中的 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}"
    2. (選擇性) 更新元件說明、預設組態、人工因素、生命週期指令碼和平台支援。如需詳細資訊,請參閱 AWS IoT Greengrass元件配方參考

    完成此步驟後,recipe 檔案看起來可能與下列範例類似。

    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}"
  8. 開發和構建 Greengrass 組件。元件建置指令會在元件資料夾的greengrass-build資料夾中產生配方和成品。執行下列命令。

    gdk component build

當您準備好測試元件時,請使用 GDK CLI 將其發佈到 AWS IoT Greengrass 服務。然後,您可以將該組件部署到 Greengrass 核心設備。如需詳細資訊,請參閱 發佈元件以部署至核心裝置

建立元件 (薄殼指令)

請遵循本節中的指示,建立包含多個元件之原始程式碼和人工因素的方案和人工因素資料夾。

若要開發 Greengrass 元件 (殼層指令)
  1. 使用配方和成品的子資料夾,為您的元件建立資料夾。在 Greengrass 核心裝置上執行下列命令,以建立這些資料夾並變更為元件資料夾。將 ~/greengrassv2 或% 使用者設定檔%\ Greengrassv2 取代為要用於本機開發的資料夾路徑。

    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
  2. 使用文字編輯器建立 recipe 檔案,以定義元件的中繼資料、參數、相依性、生命週期和平台功能。在 recipe 檔案名稱中包含元件版本,以便識別哪個方案反映哪個元件版本。您可以為您的食譜選擇 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 使用語義版本的組件。語義版本遵循一個主要的。 未成年人修補程式編號系統。例如,版本1.0.0代表元件的第一個主要發行版本。如需詳細資訊,請參閱語意版本規格

  3. 定義元件的配方。如需詳細資訊,請參閱 AWS IoT Greengrass元件配方參考

    您的食譜看起來可能類似於下列 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)
  4. 為要開發的元件版本建立資料夾。建議您為每個元件版本的成品使用不同的資料夾,以便識別每個元件版本的成品。執行下列命令。

    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/
  5. 在您在上一個步驟中建立的資料夾中建立元件的成品。成品可以包括軟體、影像,以及您的元件使用的任何其他二進位檔案。

    當您的組件準備就緒時,請測試您的組件