建立 AWS IoT Greengrass 元件

如果您尚未安裝，請在開發電腦上安裝 GDK CLI。如需詳細資訊，請參閱安裝或更新 AWS IoT Greengrass 開發套件命令列界面。

變更為您要建立元件資料夾的資料夾。

mkdir ~/greengrassv2
cd ~/greengrassv2

選擇要下載的元件範本或社群元件。GDK CLI 會下載範本或社群元件，因此您可以從功能範例開始。使用元件清單命令來擷取可用範本或社群元件的清單。

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

  gdk component list --template

• 若要列出社群元件，請執行下列命令。

  gdk component list --repository

建立元件資料夾，並變更為 GDK CLI 下載範本或社群元件的資料夾。將 HelloWorld 取代為元件名稱，或其他可協助您識別此元件資料夾的名稱。

mkdir HelloWorld
cd HelloWorld

將範本或社群元件下載至目前的資料夾。使用 元件 init 命令。

• 若要從範本建立元件資料夾，請執行下列命令。將 HelloWorld 取代為範本的名稱，並將 python 取代為程式設計語言的名稱。

  gdk component init --template HelloWorld --language python

• 若要從社群元件建立元件資料夾，請執行下列命令。將 ComponentName 取代為社群元件的名稱。

  gdk component init --repository ComponentName

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 將元件本機部署和測試到執行 AWS IoT Greengrass Core 軟體的本機開發電腦。若要啟用本機部署，您必須改為指定語意版本。

   • 語意版本，例如 1.0.0。語意版本使用 major.minor.patch 編號系統。如需詳細資訊，請參閱語意版本規格。

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

5. （選用） 變更元件的建置組態。建置組態定義 GDK CLI 如何將元件的來源建置為成品。請從下列選項中選擇 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 的元件選擇此選項，例如 Java 元件。

     在 Windows 裝置上，此功能適用於 GDK CLI 1.1.0 版及更新版本。

   • gradle – 執行 gradle build命令，將元件的來源建置為成品。針對使用 Gradle 的元件選擇此選項。此功能適用於 GDK CLI 1.1.0 版及更新版本。

     gradle 建置系統支援 Kotlin DSL 做為建置檔案。此功能適用於 GDK CLI 1.2.0 版及更新版本。

   • gradlew – 執行 gradlew命令，將元件的來源建置為成品。針對使用 Gradle Wrapper 的元件選擇此選項。

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

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

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

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

   變更元件的發佈組態。請執行下列操作：

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

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

當您完成此步驟時，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"
}

更新名為 recipe.yaml或 的元件配方檔案recipe.json。請執行下列操作：

1. 如果您下載使用zip建置系統的範本或社群元件，請檢查 zip 成品名稱是否符合元件資料夾的名稱。GDK CLI 會將元件資料夾壓縮成與元件資料夾名稱相同的 zip 檔案。配方包含元件成品清單中的 zip 成品名稱，以及使用 zip 成品中檔案的生命週期指令碼。更新 Artifacts和 Lifecycle定義，讓 zip 檔案名稱符合元件資料夾的名稱。下列部分配方範例會反白顯示 Artifacts和 Lifecycle定義中的 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}"

   anchoranchor
   • JSON
   • YAML

   {
     ...
     "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}"
         }
       }
     ]
   }

2. （選用） 更新元件描述、預設組態、成品、生命週期指令碼和平台支援。如需詳細資訊，請參閱AWS IoT Greengrass 元件配方參考。

當您完成此步驟時，配方檔案看起來可能會類似下列範例。

{
  "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}"
      }
    }
  ]
}

開發和建置 Greengrass 元件。元件建置命令會在元件greengrass-build資料夾中產生配方和成品。執行下列命令。

gdk component build

使用配方和成品的子資料夾為您的元件建立資料夾。在 Greengrass 核心裝置上執行下列命令，以建立這些資料夾並變更為元件資料夾。將 ~/greengrassv2 或 %USERPROFILE%\greengrassv2 取代為資料夾路徑，以用於本機開發。

mkdir -p ~/greengrassv2/{recipes,artifacts}
cd ~/greengrassv2

使用文字編輯器來建立配方檔案，定義元件的中繼資料、參數、相依性、生命週期和平台功能。在配方檔案名稱中包含元件版本，以便您可以識別哪個配方會反映哪個元件版本。您可以選擇配方的 YAML 或 JSON 格式。

例如，在以 Linux 為基礎的系統上，您可以執行下列命令來使用 GNU nano 來建立 檔案。

nano recipes/com.example.HelloWorld-1.0.0.json

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

您的配方看起來可能類似於下列 Hello World 範例配方。

{
  "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)

為要開發的元件版本建立資料夾。建議您針對每個元件版本的成品使用不同的資料夾，以便識別每個元件版本有哪些成品。執行下列命令。

mkdir -p artifacts/com.example.HelloWorld/1.0.0

artifacts/componentName/componentVersion/

在您在上一個步驟中建立的資料夾中，為您的元件建立成品。成品可以包含軟體、映像和元件使用的任何其他二進位檔。

當您的元件準備就緒時，請測試您的元件。