本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 開發 AWS IoT Greengrass 元件 您可以在 Greengrass 核心裝置上開發和測試元件。因此，您可以建立和重複您的 AWS IoT Greengrass 軟體，而無需與 互動 AWS 雲端。當您完成元件的版本時，您可以在雲端 AWS IoT Greengrass 中將其上傳至 ，以便您和您的團隊可以將元件部署到機群中的其他裝置。如需如何部署元件的詳細資訊，請參閱[將 AWS IoT Greengrass 元件部署至裝置](manage-deployments.md)。 每個元件都由*配方*和*成品*組成。 + **配方** 每個元件都包含配方檔案，定義其中繼資料。配方也會指定元件的組態參數、元件相依性、生命週期和平台相容性。元件生命週期會定義安裝、執行和關閉元件的命令。如需詳細資訊，請參閱[AWS IoT Greengrass 元件配方參考](component-recipe-reference.md)。 您可以定義 [JSON](https://en.wikipedia.org/wiki/JSON) 或 [YAML](https://en.wikipedia.org/wiki/YAML) 格式的配方。 + **成品** 元件可以有任意數量的成品，這些成品是元件二進位檔。成品可以包含指令碼、編譯程式碼、靜態資源，以及元件使用的任何其他檔案。元件也可以使用元件相依性的成品。 AWS IoT Greengrass 提供預先建置的元件，您可以在應用程式中使用，並部署到裝置。例如，您可以使用串流管理員元件將資料上傳至各種 AWS 服務，或使用 CloudWatch 指標元件將自訂指標發佈至 Amazon CloudWatch。如需詳細資訊，請參閱[AWS提供的元件](public-components.md)。 AWS IoT Greengrass 策劃 Greengrass 元件的索引，稱為 Greengrass 軟體目錄。此目錄會追蹤由 Greengrass 社群開發的 Greengrass 元件。您可以從此目錄中下載、修改和部署元件，以建立 Greengrass 應用程式。如需詳細資訊，請參閱[社群元件](greengrass-software-catalog.md)。 AWS IoT Greengrass 核心軟體會以您在核心裝置上設定的系統使用者和群組身分執行元件`ggc_group`，例如 `ggc_user`和 。這表示元件具有該系統使用者的許可。如果您使用沒有主目錄的系統使用者，則元件無法使用使用主目錄的執行命令或程式碼。這表示您無法使用 `pip install some-library --user`命令來安裝 Python 套件。如果您遵循[入門教學](getting-started.md)來設定核心裝置，則您的系統使用者沒有主目錄。如需如何設定執行元件之使用者和群組的詳細資訊，請參閱[設定執行元件的使用者](configure-greengrass-core-v2.md#configure-component-user)。 **注意** AWS IoT Greengrass 使用元件的語意版本。語意版本遵循 *major*.*minor*.*patch* 號碼系統。例如，版本`1.0.0`代表元件的第一個主要版本。如需詳細資訊，請參閱[語意版本規格](https://semver.org/)。 **Topics** + [元件生命週期](#component-lifecycle) + [元件類型](#component-types) + [建立 AWS IoT Greengrass 元件](create-components.md) + [使用本機部署測試 AWS IoT Greengrass 元件](test-components.md) + [發佈元件以部署到您的核心裝置](publish-components.md) + [與 AWS 服務互動](interact-with-aws-services.md) + [執行 Docker 容器](run-docker-container.md) + [AWS IoT Greengrass 元件配方參考](component-recipe-reference.md) + [元件環境變數參考](component-environment-variables.md) ## 元件生命週期 *元件生命週期*會定義 AWS IoT Greengrass Core 軟體用來安裝和執行元件的階段。每個階段都會定義指令碼和其他資訊，以指定元件的行為方式。例如，當您安裝元件時， AWS IoT Greengrass Core 軟體會執行該元件的`install`生命週期指令碼。核心裝置上的元件具有下列生命週期狀態： + `NEW` – 元件的配方和成品會載入核心裝置上，但元件並未安裝。元件進入此狀態後，會執行其[安裝指令碼](component-recipe-reference.md#install-lifecycle-definition)。 + `INSTALLED` – 元件安裝在核心裝置上。元件在執行其[安裝指令碼](component-recipe-reference.md#install-lifecycle-definition)後會進入此狀態。 + `STARTING` – 元件正在核心裝置上啟動。元件會在執行其[啟動指令碼](component-recipe-reference.md#startup-lifecycle-definition)時進入此狀態。如果啟動成功，元件會進入 `RUNNING` 狀態。 + `RUNNING` – 元件正在核心裝置上執行。元件在執行其[執行指令碼](component-recipe-reference.md#run-lifecycle-definition)時，或從其啟動指令碼中具有作用中背景程序時，會進入此狀態。 + `FINISHED` – 元件已成功執行並完成其執行。 + `STOPPING` – 元件正在停止。元件在執行其[關機指令碼](component-recipe-reference.md#shutdown-lifecycle-definition)時進入此狀態。 + `ERRORED` – 元件發生錯誤。當元件進入此狀態時，它會執行[復原指令碼](component-recipe-reference.md#recover-lifecycle-definition)。然後，元件會重新啟動，嘗試恢復正常使用。如果元件在未成功執行的情況下進入 `ERRORED` 狀態三次，則元件會變成 `BROKEN`。 + `BROKEN` – 元件多次發生錯誤，無法復原。您必須再次部署元件才能修正。 ## 元件類型 *元件類型*指定 AWS IoT Greengrass Core 軟體如何執行元件。元件可以有下列類型： + **Nucleus** (`aws.greengrass.nucleus`) Greengrass 核是提供 AWS IoT Greengrass Core 軟體最低功能的元件。如需詳細資訊，請參閱[Greengrass 核](greengrass-nucleus-component.md)。 + **外掛程式 **(`aws.greengrass.plugin`) Greengrass 核會在與核相同的 Java 虛擬機器 (JVM) 中執行外掛程式元件。當您變更核心裝置上的外掛程式元件版本時， 核會重新啟動。若要安裝和執行外掛程式元件，您必須設定 Greengrass 核以系統服務的形式執行。如需詳細資訊，請參閱[將 Greengrass 核設定為系統服務](configure-greengrass-core-v2.md#configure-system-service)。 提供的數個元件 AWS 是外掛程式元件，可讓它們直接與 Greengrass 核連接。外掛程式元件使用與 Greengrass 核相同的日誌檔案。如需詳細資訊，請參閱[監控 AWS IoT Greengrass 日誌](monitor-logs.md)。 + **一般** (`aws.greengrass.generic`) 如果元件定義生命週期，Greengrass 核會執行一般元件的生命週期指令碼。 此類型是自訂元件的預設類型。 + **Lambda** (`aws.greengrass.lambda`) Greengrass 核會使用 Lambda [啟動器元件執行 Lambda 函數元件](lambda-launcher-component.md)。 當您從 Lambda 函數建立元件時，該元件具有此類型。如需詳細資訊，請參閱[執行 AWS Lambda 函數](run-lambda-functions.md)。 **注意** 我們不建議您在 recipe 中指定元件類型。當您建立元件時， 會為您 AWS IoT Greengrass 設定 類型。 # 建立 AWS IoT Greengrass 元件 您可以在本機開發電腦或 Greengrass 核心裝置上開發自訂 AWS IoT Greengrass 元件。 AWS IoT Greengrass 提供[AWS IoT Greengrass 開發套件命令列界面 (GDK CLI)](greengrass-development-kit-cli.md)，協助您從預先定義的元件範本和[社群元件](greengrass-software-catalog.md)建立、建置和發佈元件。您也可以執行內建 shell 命令來建立、建置和發佈元件。從下列選項中選擇，以建立自訂 Greengrass 元件： + **使用 Greengrass 開發套件 CLI** 使用 GDK CLI 在本機開發電腦上開發元件。GDK CLI 會將元件原始程式碼建置並封裝到配方和成品中，您可以將其做為私有元件發佈至 AWS IoT Greengrass 服務。您可以設定 GDK CLI，以便在發佈元件時自動更新元件的版本和成品 URIs，因此您不需要每次更新配方。若要使用 GDK CLI 開發元件，您可以從範本或 [Greengrass 軟體目錄中](greengrass-software-catalog.md)的社群元件開始。如需詳細資訊，請參閱[AWS IoT Greengrass 開發套件命令列介面](greengrass-development-kit-cli.md)。 + **執行內建 shell 命令** 您可以執行內建 shell 命令，在本機開發電腦或 Greengrass 核心裝置上開發元件。您可以使用 shell 命令將元件原始程式碼複製或建置為成品。每次建立新版本的元件時，您必須使用新的元件版本建立或更新配方。當您將元件發佈至服務時 AWS IoT Greengrass ，您必須將 URI 更新為配方中的每個元件成品。 **Topics** + [建立元件 (GDK CLI)](#create-component-gdk-cli) + [建立元件 (shell 命令）](#create-component-shell-commands) ## 建立元件 (GDK CLI) 遵循本節中的指示，使用 GDK CLI 建立和建置元件。 **開發 Greengrass 元件 (GDK CLI)** 1. 如果您尚未安裝，請在開發電腦上安裝 GDK CLI。如需詳細資訊，請參閱[安裝或更新 AWS IoT Greengrass 開發套件命令列界面](install-greengrass-development-kit-cli.md)。 1. 將 變更為您要建立元件資料夾的資料夾。 ------ #### [ Linux or Unix ] ``` mkdir ~/greengrassv2 cd ~/greengrassv2 ``` ------ #### [ Windows Command Prompt (CMD) ] ``` mkdir %USERPROFILE%\greengrassv2 cd %USERPROFILE%\greengrassv2 ``` ------ #### [ PowerShell ] ``` mkdir ~/greengrassv2 cd ~/greengrassv2 ``` ------ 1. 選擇要下載的元件範本或社群元件。GDK CLI 會下載範本或社群元件，因此您可以從功能範例開始。使用[元件清單](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-list)命令來擷取可用範本或社群元件的清單。 + 若要列出元件範本，請執行下列命令。回應中的每一行都包含範本的名稱和程式設計語言。 ``` gdk component list --template ``` + 若要列出社群元件，請執行下列命令。 ``` gdk component list --repository ``` 1. 建立並變更為 GDK CLI 下載範本或社群元件的元件資料夾。將 *HelloWorld* 取代為元件名稱，或另一個可協助您識別此元件資料夾的名稱。 ------ #### [ Linux or Unix ] ``` mkdir HelloWorld cd HelloWorld ``` ------ #### [ Windows Command Prompt (CMD) ] ``` mkdir HelloWorld cd HelloWorld ``` ------ #### [ PowerShell ] ``` mkdir HelloWorld cd HelloWorld ``` ------ 1. 將範本或社群元件下載至目前的資料夾。使用 [元件 init](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-init) 命令。 + 若要從範本建立元件資料夾，請執行下列命令。將 *HelloWorld* 取代為範本的名稱，並將 *python* 取代為程式設計語言的名稱。 ``` gdk component init --template HelloWorld --language python ``` + 若要從社群元件建立元件資料夾，請執行下列命令。將 *ComponentName* 取代為社群元件的名稱。 ``` gdk component init --repository ComponentName ``` **注意** 如果您使用 GDK CLI 1.0.0 版，您必須在空的資料夾中執行此命令。GDK CLI 會將範本或社群元件下載到目前的資料夾。 如果您使用 GDK CLI 1.1.0 版或更新版本，您可以指定 `--name` 引數來指定 GDK CLI 下載範本或社群元件的資料夾。如果您使用此引數，請指定不存在的資料夾。GDK CLI 會為您建立 資料夾。如果您未指定此引數，GDK CLI 會使用目前的資料夾，該資料夾必須是空的。 1. GDK CLI 會從名為 的 [GDK CLI 組態檔案](gdk-cli-configuration-file.md)讀取`gdk-config.json`，以建置和發佈元件。此組態檔案存在於元件資料夾的根目錄中。上一個步驟會為您建立此檔案。在此步驟中，您會`gdk-config.json`使用 元件的相關資訊進行更新。請執行下列操作： 1. 在文字編輯器中開啟 `gdk-config.json`。 1. （選用） 變更元件的名稱。元件名稱是 `component` 物件中的金鑰。 1. 變更元件的作者。 1. （選用） 變更元件的版本。請指定下列其中一項： + `NEXT_PATCH` – 當您選擇此選項時，GDK CLI 會在您發佈元件時設定版本。GDK CLI 會查詢 AWS IoT Greengrass 服務，以識別元件的最新發佈版本。然後，它會將版本設定為該版本之後的下一個修補程式版本。如果您之前尚未發佈元件，GDK CLI 會使用版本 `1.0.0`。 如果您選擇此選項，則無法使用 [Greengrass CLI](greengrass-cli-component.md) 在本機部署和測試元件到執行 AWS IoT Greengrass 核心軟體的本機開發電腦。若要啟用本機部署，您必須改為指定語意版本。 + 語意版本，例如 **1.0.0**。語意版本使用 *major*.*minor*.*patch* 編號系統。如需詳細資訊，請參閱[語意版本規格](https://semver.org/)。 如果您在想要部署和測試元件的 Greengrass 核心裝置上開發元件，請選擇此選項。您必須使用特定版本建置元件，才能使用 [Greengrass CLI ](greengrass-cli-component.md)建立本機部署。 1. （選用） 變更元件的建置組態。建置組態定義 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](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` 參數中指定自訂命令。 1. 如果您`custom`為 指定 `build_system`，請將 `custom_build_command`新增至 `build` 物件。在 中`custom_build_command`，指定單一字串或字串清單，其中每個字串都是 命令中的字詞。例如，若要執行 C\$1\$1 元件的自訂建置命令，您可以指定 **["cmake", "--build", "build", "--config", "Release"]**。 1. 如果您使用 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 儲存貯體名稱。 1. 指定 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" } ``` 1. 更新名為 `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}" ``` ------ 1. （選用） 更新元件描述、預設組態、成品、生命週期指令碼和平台支援。如需詳細資訊，請參閱[AWS IoT Greengrass 元件配方參考](component-recipe-reference.md)。 完成此步驟後，配方檔案看起來可能會類似下列範例。 ------ #### [ 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}" ``` ------ 1. 開發和建置 Greengrass 元件。[元件建置](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-build)命令會在元件`greengrass-build`資料夾中產生配方和成品。執行下列命令。 ``` gdk component build ``` 當您準備好測試元件時，請使用 GDK CLI 將其發佈至服務 AWS IoT Greengrass 。然後，您可以將元件部署到 Greengrass 核心裝置。如需詳細資訊，請參閱[發佈元件以部署到您的核心裝置](publish-components.md)。 ## 建立元件 (shell 命令） 遵循本節中的指示，建立配方和成品資料夾，其中包含多個元件的原始程式碼和成品。 **開發 Greengrass 元件 (shell 命令）** 1. 使用配方和成品的子資料夾為您的元件建立資料夾。在 Greengrass 核心裝置上執行下列命令，以建立這些資料夾並變更為元件資料夾。將 *\$1/greengrassv2* 或 *%USERPROFILE%\$1greengrassv2* 取代為資料夾的路徑，以用於本機開發。 ------ #### [ 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 ``` ------ 1. 使用文字編輯器來建立配方檔案，定義元件的中繼資料、參數、相依性、生命週期和平台功能。在配方檔案名稱中包含元件版本，以便您可以識別哪個配方反映哪個元件版本。您可以為您的配方選擇 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 使用元件的語意版本。語意版本遵循 *major*.*minor*.*patch* 號碼系統。例如，版本`1.0.0`代表元件的第一個主要版本。如需詳細資訊，請參閱[語意版本規格](https://semver.org/)。 1. 定義元件的配方。如需詳細資訊，請參閱[AWS IoT Greengrass 元件配方參考](component-recipe-reference.md)。 您的配方可能看起來類似下列 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) ``` 1. 為要開發的元件版本建立資料夾。建議您針對每個元件版本的成品使用個別資料夾，以便識別每個元件版本適用的成品。執行下列命令。 ------ #### [ 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/ ``` 1. 在您在上一個步驟中建立的 資料夾中，為元件建立成品。成品可以包含軟體、映像和元件使用的任何其他二進位檔。 當您的元件準備就緒時，請[測試您的元件](test-components.md)。 # 使用本機部署測試 AWS IoT Greengrass 元件 如果您在核心裝置上開發 Greengrass 元件，您可以建立本機部署來安裝和測試它。遵循本節中的步驟來建立本機部署。 如果您在不同的電腦上開發元件，例如本機開發電腦，則無法建立本機部署。相反地，請將元件發佈至 AWS IoT Greengrass 服務，以便您可以將其部署至 Greengrass 核心裝置進行測試。如需詳細資訊，請參閱 [發佈元件以部署到您的核心裝置](publish-components.md) 和 [將 AWS IoT Greengrass 元件部署至裝置](manage-deployments.md)。 **在 Greengrass 核心裝置上測試元件** 1. 核心裝置會記錄事件，例如元件更新。您可以檢視此日誌檔案，以探索元件的錯誤並進行故障診斷，例如無效的配方。此日誌檔案也會顯示您的元件列印到標準輸出 (stdout) 的訊息。建議您在核心裝置上開啟額外的終端機工作階段，以即時觀察新的日誌訊息。開啟新的終端機工作階段，例如透過 SSH，並執行下列命令來檢視日誌。`/greengrass/v2` 將 取代為 AWS IoT Greengrass 根資料夾的路徑。 ------ #### [ Linux or Unix ] ``` sudo tail -f /greengrass/v2/logs/greengrass.log ``` ------ #### [ PowerShell ] ``` gc C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait ``` ------ 您也可以檢視元件的日誌檔案。 ------ #### [ Linux or Unix ] ``` sudo tail -f /greengrass/v2/logs/com.example.HelloWorld.log ``` ------ #### [ PowerShell ] ``` gc C:\greengrass\v2\logs\com.example.HelloWorld.log -Tail 10 -Wait ``` ------ 1. 在原始終端機工作階段中，執行下列命令以使用 元件更新核心裝置。`/greengrass/v2` 將 取代為 AWS IoT Greengrass 根資料夾的路徑，並將 *\$1/greengrassv2* 取代為本機開發資料夾的路徑。 ------ #### [ Linux or Unix ] ``` sudo /greengrass/v2/bin/greengrass-cli deployment create \ --recipeDir ~/greengrassv2/recipes \ --artifactDir ~/greengrassv2/artifacts \ --merge "com.example.HelloWorld=1.0.0" ``` ------ #### [ Windows Command Prompt (CMD) ] ``` C:\greengrass\v2\bin\greengrass-cli deployment create ^ --recipeDir %USERPROFILE%\greengrassv2\recipes ^ --artifactDir %USERPROFILE%\greengrassv2\artifacts ^ --merge "com.example.HelloWorld=1.0.0" ``` ------ #### [ PowerShell ] ``` C:\greengrass\v2\bin\greengrass-cli deployment create ` --recipeDir ~/greengrassv2/recipes ` --artifactDir ~/greengrassv2/artifacts ` --merge "com.example.HelloWorld=1.0.0" ``` ------ **注意** 您也可以使用 `greengrass-cli deployment create`命令來設定元件組態參數的值。如需詳細資訊，請參閱[建立](gg-cli-deployment.md#deployment-create)。 1. 使用 `greengrass-cli deployment status`命令來監控元件部署的進度。 ------ #### [ Unix or Linux ] ``` sudo /greengrass/v2/bin/greengrass-cli deployment status \ -i deployment-id ``` ------ #### [ Windows Command Prompt (CMD) ] ``` C:\greengrass\v2\bin\greengrass-cli deployment status ^ -i deployment-id ``` ------ #### [ PowerShell ] ``` C:\greengrass\v2\bin\greengrass-cli deployment status ` -i deployment-id ``` ------ 1. 在 Greengrass 核心裝置上執行元件時進行測試。當您完成此版本的元件時，您可以將其上傳至 AWS IoT Greengrass 服務。然後，您可以將元件部署到其他核心裝置。如需詳細資訊，請參閱[發佈元件以部署到您的核心裝置](publish-components.md)。 # 發佈元件以部署到您的核心裝置 建置或完成元件版本後，您可以將其發佈至 AWS IoT Greengrass 服務。然後，您可以將它部署到 Greengrass 核心裝置。 如果您使用 [Greengrass 開發套件 CLI (GDK CLI)](greengrass-development-kit-cli.md) 來[開發和建置元件](create-components.md)，您可以使用 [GDK CLI](#publish-component-gdk-cli) 將元件發佈到 AWS 雲端。否則，[請使用內建 shell 命令和 AWS CLI](#publish-component-shell-commands) 來發佈元件。 您也可以使用 從 範本 AWS CloudFormation 建立元件和其他 AWS 資源。如需詳細資訊，請參閱 *AWS CloudFormation 使用者指南*[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-greengrassv2-componentversion.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-greengrassv2-componentversion.html)中的[什麼是 AWS CloudFormation？](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) 和 。 **Topics** + [發佈元件 (GDK CLI)](#publish-component-gdk-cli) + [發佈元件 (shell 命令）](#publish-component-shell-commands) ## 發佈元件 (GDK CLI) 遵循本節中的指示，使用 GDK CLI 發佈元件。GDK CLI 會將建置成品上傳至 S3 儲存貯體、更新配方中的成品 URIs，以及從配方建立元件。您可以指定要在 [GDK CLI 組態檔案中](gdk-cli-configuration-file.md)使用的 S3 儲存貯體和區域。 如果您使用 GDK CLI 1.1.0 版或更新版本，您可以指定`--bucket`引數來指定 GDK CLI 上傳元件成品的 S3 儲存貯體。如果您未指定此引數，GDK CLI 會上傳至名稱為 的 S3 儲存貯體`bucket-region-accountId`，其中儲存*貯*體和*區域*是您在 中指定的值`gdk-config.json`，而 *accountId* 是您的 AWS 帳戶 ID。如果儲存貯體不存在，GDK CLI 會建立儲存貯體。 **重要** 根據預設，核心裝置角色不允許存取 S3 儲存貯體。如果這是您第一次使用此 S3 儲存貯體，您必須將許可新增至角色，以允許核心裝置從此 S3 儲存貯體擷取元件成品。如需詳細資訊，請參閱[允許存取元件成品的 S3 儲存貯體](device-service-role.md#device-service-role-access-s3-bucket)。 **發佈 Greengrass 元件 (GDK CLI)** 1. 在命令提示字元或終端機中開啟元件資料夾。 1. 如果您尚未建立 Greengrass 元件，請建置 元件。[元件建置](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-build)命令會在元件`greengrass-build`資料夾中產生配方和成品。執行下列命令。 ``` gdk component build ``` 1. 將元件發佈至 AWS 雲端。[元件發佈](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-publish)命令會將元件的成品上傳至 Amazon S3，並使用每個成品的 URI 更新元件的配方。然後，它會在 AWS IoT Greengrass 服務中建立元件。 **注意** AWS IoT Greengrass 當您建立元件時， 會計算每個成品的摘要。這表示在建立元件之後，您無法修改 S3 儲存貯體中的成品檔案。如果您這樣做，包含此元件的部署將會失敗，因為檔案摘要不相符。如果您修改成品檔案，則必須建立新的元件版本。 如果您`NEXT_PATCH`為 GDK CLI 組態檔案中的元件版本指定 ，則 GDK CLI 會使用 AWS IoT Greengrass 服務中尚不存在的下一個修補程式版本。 執行下列命令。 ``` gdk component publish ``` 輸出會告訴您 GDK CLI 建立的元件版本。 發佈元件之後，您可以將元件部署到核心裝置。如需詳細資訊，請參閱[將 AWS IoT Greengrass 元件部署至裝置](manage-deployments.md)。 ## 發佈元件 (shell 命令） 使用下列程序，使用 shell 命令和 AWS Command Line Interface () 發佈元件AWS CLI。當您發佈元件時，請執行下列動作： 1. 將元件成品發佈至 S3 儲存貯體。 1. 將每個成品的 Amazon S3 URI 新增至元件配方。 1. AWS IoT Greengrass 從元件配方在 中建立元件版本。 **注意** 您上傳的每個元件版本都必須是唯一的。請確定您上傳正確的元件版本，因為上傳之後就無法編輯。 您可以依照下列步驟，從您的開發電腦或 Greengrass 核心裝置發佈元件。 **發佈元件 (shell 命令）** 1. 如果元件使用 AWS IoT Greengrass 服務中存在的版本，則必須變更元件的版本。在文字編輯器中開啟配方、增加版本，並儲存檔案。選擇反映您對元件所做的變更的新版本。 **注意** AWS IoT Greengrass 使用元件的語意版本。語意版本遵循 *major*.*minor*.*patch* 號碼系統。例如，版本`1.0.0`代表元件的第一個主要版本。如需詳細資訊，請參閱[語意版本規格](https://semver.org/)。 1. 如果您的元件有成品，請執行下列動作： 1. 將元件的成品發佈到 中的 S3 儲存貯體 AWS 帳戶。 **提示** 我們建議您在 S3 儲存貯體成品路徑中包含元件名稱和版本。此命名機制可協助您維護先前元件版本使用的成品，因此您可以繼續支援先前的元件版本。 執行下列命令，將成品檔案發佈至 S3 儲存貯體。將 amzn-s3-demo-bucket 取代為儲存貯體的名稱，並將 *artifacts/com.example.HelloWorld/1.0.0/artifact.py* 取代為成品檔案的路徑。 ``` aws s3 cp artifacts/com.example.HelloWorld/1.0.0/artifact.py s3://amzn-s3-demo-bucket/artifacts/com.example.HelloWorld/1.0.0/artifact.py ``` **重要** 根據預設，核心裝置角色不允許存取 S3 儲存貯體。如果這是您第一次使用此 S3 儲存貯體，您必須將許可新增至角色，以允許核心裝置從此 S3 儲存貯體擷取元件成品。如需詳細資訊，請參閱[允許存取元件成品的 S3 儲存貯體](device-service-role.md#device-service-role-access-s3-bucket)。 1. 如果沒有名為 的清單，請`Artifacts`將其新增至元件配方。`Artifacts` 清單會出現在每個資訊清單中，定義元件在其支援的每個平台上的需求 （或元件對所有平台的預設需求）。 1. 將每個成品新增至成品清單，或更新現有成品的 URI。Amazon S3 URI 由儲存貯體名稱和儲存貯體中成品物件的路徑組成。成品的 Amazon S3 URIs 看起來應該類似下列範例。 ``` s3://amzn-s3-demo-bucket/artifacts/com.example.HelloWorld/1.0.0/artifact.py ``` 完成這些步驟後，您的配方應該會有如下所示的`Artifacts`清單。 ------ #### [ JSON ] ``` { ... "Manifests": [ { "Lifecycle": { ... }, "Artifacts": [ { "URI": "s3://amzn-s3-demo-bucket/artifacts/MyGreengrassComponent/1.0.0/artifact.py", "Unarchive": "NONE" } ] } ] } ``` **注意** 您可以新增 ZIP 成品`"Unarchive": "ZIP"`選項，以設定 AWS IoT Greengrass 核心軟體在元件部署時解壓縮成品。 ------ #### [ YAML ] ``` ... Manifests: - Lifecycle: ... Artifacts: - URI: s3://amzn-s3-demo-bucket/artifacts/MyGreengrassComponent/1.0.0/artifact.py Unarchive: NONE ``` **注意** 您可以使用 `Unarchive: ZIP`選項來設定 AWS IoT Greengrass 核心軟體，以在元件部署時解壓縮 ZIP 成品。如需如何在元件中使用 ZIP 成品的詳細資訊，請參閱 [artifacts：decompressedPath 配方變數](component-recipe-reference.md#component-recipe-artifacts-decompressed-path)。 ------ 如需配方的詳細資訊，請參閱[AWS IoT Greengrass 元件配方參考](component-recipe-reference.md)。 1. 使用 AWS IoT Greengrass 主控台從配方檔案建立元件。 執行下列命令，從配方檔案建立元件。此命令會建立元件，並將其發佈為 中的私有 AWS IoT Greengrass 元件 AWS 帳戶。將 *path/to/recipeFile* 取代為配方檔案的路徑。 ``` aws greengrassv2 create-component-version --inline-recipe fileb://path/to/recipeFile ``` `arn` 從回應中複製 ，以在下一個步驟中檢查元件的狀態。 **注意** AWS IoT Greengrass 當您建立元件時， 會計算每個成品的摘要。這表示在建立元件之後，您無法修改 S3 儲存貯體中的成品檔案。如果您這樣做，包含此元件的部署將會失敗，因為檔案摘要不相符。如果您修改成品檔案，則必須建立新的元件版本。 1. AWS IoT Greengrass 服務中的每個元件都有 狀態。執行下列命令以確認您在此程序中發佈的元件版本狀態。將 *com.example.HelloWorld* 和 *1.0.0* 取代為要查詢的元件版本。將 取代`arn`為上一個步驟的 ARN。 ``` aws greengrassv2 describe-component --arn "arn:aws:greengrass:region:account-id:components:com.example.HelloWorld:versions:1.0.0" ``` 操作會傳回包含元件中繼資料的回應。中繼資料包含`status`物件，其中包含元件狀態和任何錯誤，如適用。 當元件狀態為 時`DEPLOYABLE`，您可以將元件部署到裝置。如需詳細資訊，請參閱[將 AWS IoT Greengrass 元件部署至裝置](manage-deployments.md)。 # 與 AWS 服務互動 Greengrass 核心裝置使用 X.509 憑證， AWS IoT Core 使用 TLS 相互身分驗證通訊協定連線至 。這些憑證可讓裝置 AWS IoT 在沒有 AWS 登入資料的情況下與 互動，通常包含存取金鑰 ID 和私密存取金鑰。其他服務 AWS 需要 AWS 登入資料，而不是 X.509 憑證，才能呼叫服務端點的 API 操作。 AWS IoT Core 具有登入資料提供者，可讓裝置使用其 X.509 憑證來驗證 AWS 請求。 AWS IoT 登入資料提供者會使用 X.509 憑證來驗證裝置，並以臨時、有限權限的安全字符的形式發出 AWS 登入資料。裝置可以使用此字符來簽署和驗證任何 AWS 請求。這不需要在 Greengrass 核心裝置上存放 AWS 登入資料。如需詳細資訊，請參閱《 *AWS IoT Core 開發人員指南*》中的[授權對 AWS 服務的直接呼叫](https://docs.aws.amazon.com/iot/latest/developerguide/authorizing-direct-aws.html)。 若要從中擷取登入資料 AWS IoT，Greengrass 核心裝置會使用指向 IAM AWS IoT 角色的角色別名。此 IAM 角色稱為*字符交換角色*。您可以在安裝 AWS IoT Greengrass Core 軟體時建立角色別名和字符交換角色。若要指定核心裝置使用的角色別名，請設定 的 `iotRoleAlias` 參數[Greengrass 核](greengrass-nucleus-component.md)。 AWS IoT 登入資料提供者會代表您擔任權杖交換角色，以提供 AWS 登入資料給核心裝置。您可以將適當的 IAM 政策連接到此角色，以允許核心裝置存取您的 AWS 資源，例如 S3 儲存貯體中的元件成品。如需如何設定字符交換角色的詳細資訊，請參閱[授權核心裝置與 AWS 服務互動](device-service-role.md)。 Greengrass 核心裝置會將 AWS 登入資料存放在記憶體中，而且登入資料預設會在一小時後過期。如果 AWS IoT Greengrass 核心軟體重新啟動，則必須再次擷取登入資料。您可以使用 [UpdateRoleAlias](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateRoleAlias.html) 操作來設定憑證有效的持續時間。 AWS IoT Greengrass 提供公有元件，也就是權杖交換服務元件，您可以在自訂元件中將其定義為與 AWS 服務互動的相依性。權杖交換服務為您的元件提供環境變數 `AWS_CONTAINER_CREDENTIALS_FULL_URI`，此變數會將 URI 定義為提供 AWS 憑證的本機伺服器。當您建立 AWS SDK 用戶端時，用戶端會檢查此環境變數，並連線至本機伺服器以擷取 AWS 登入資料，並使用它們來簽署 API 請求。這可讓您使用 AWS SDKs和其他工具來呼叫元件中的 AWS 服務。如需詳細資訊，請參閱[字符交換服務](token-exchange-service-component.md)。 **重要** 2016 年 7 月 13 日， AWS SDKs 已新增以這種方式取得 AWS 憑證的支援。您的元件必須使用在該日期或之後建立的 AWS SDK 版本。如需詳細資訊，請參閱《*Amazon Elastic Container Service 開發人員指南*》中的[使用支援的 AWS SDK](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html#task-iam-roles-minimum-sdk)。 若要在自訂元件中取得 AWS 登入資料，請在元件配方中定義 `aws.greengrass.TokenExchangeService`做為相依性。下列範例配方會定義安裝 [boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) 並執行 Python 指令碼的元件，該指令碼使用字符交換服務的 AWS 登入資料來列出 Amazon S3 儲存貯體。 **注意** 若要執行此範例元件，您的裝置必須具有 `s3:ListAllMyBuckets`許可。如需詳細資訊，請參閱[授權核心裝置與 AWS 服務互動](device-service-role.md)。 ------ #### [ JSON ] ``` { "RecipeFormatVersion": "2020-01-25", "ComponentName": "com.example.ListS3Buckets", "ComponentVersion": "1.0.0", "ComponentDescription": "A component that uses the token exchange service to list S3 buckets.", "ComponentPublisher": "Amazon", "ComponentDependencies": { "aws.greengrass.TokenExchangeService": { "VersionRequirement": "^2.0.0", "DependencyType": "HARD" } }, "Manifests": [ { "Platform": { "os": "linux" }, "Lifecycle": { "install": "pip3 install --user boto3", "Run": "python3 -u {artifacts:path}/list_s3_buckets.py" } }, { "Platform": { "os": "windows" }, "Lifecycle": { "install": "pip3 install --user boto3", "Run": "py -3 -u {artifacts:path}/list_s3_buckets.py" } } ] } ``` ------ #### [ YAML ] ``` --- RecipeFormatVersion: '2020-01-25' ComponentName: com.example.ListS3Buckets ComponentVersion: '1.0.0' ComponentDescription: A component that uses the token exchange service to list S3 buckets. ComponentPublisher: Amazon ComponentDependencies: aws.greengrass.TokenExchangeService: VersionRequirement: '^2.0.0' DependencyType: HARD Manifests: - Platform: os: linux Lifecycle: install: pip3 install --user boto3 Run: |- python3 -u {artifacts:path}/list_s3_buckets.py - Platform: os: windows Lifecycle: install: pip3 install --user boto3 Run: |- py -3 -u {artifacts:path}/list_s3_buckets.py ``` ------ 此範例元件會執行下列 Python 指令碼，`list_s3_buckets.py`其中會列出 Amazon S3 儲存貯體。 ``` import boto3 import os try: print("Creating boto3 S3 client...") s3 = boto3.client('s3') print("Successfully created boto3 S3 client") except Exception as e: print("Failed to create boto3 s3 client. Error: " + str(e)) exit(1) try: print("Listing S3 buckets...") response = s3.list_buckets() for bucket in response['Buckets']: print(f'\t{bucket["Name"]}') print("Successfully listed S3 buckets") except Exception as e: print("Failed to list S3 buckets. Error: " + str(e)) exit(1) ``` # 執行 Docker 容器 您可以將 AWS IoT Greengrass 元件設定為從存放在下列位置的映像執行 [Docker](https://www.docker.com/) 容器： + Amazon Elastic Container Registry (Amazon ECR) 中的公有和私有映像儲存庫 + 公有 Docker Hub 儲存庫 + 公有 Docker 信任的登錄檔 + S3 bucket (S3 儲存貯體) 在您的自訂元件中，包含 Docker 映像 URI 做為擷取映像並在核心裝置上執行的成品。對於 Amazon ECR 和 Docker Hub 映像，您可以使用 [Docker 應用程式管理員](docker-application-manager-component.md)元件來下載映像並管理私有 Amazon ECR 儲存庫的登入資料。 **Topics** + [要求](#run-docker-container-requirements) + [從 Amazon ECR 或 Docker Hub 中的公有映像執行 Docker 容器](#run-docker-container-public-ecr-dockerhub) + [從 Amazon ECR 中的私有映像執行 Docker 容器](#run-docker-container-private-ecr) + [從 Amazon S3 中的映像執行 Docker 容器](#run-docker-container-s3) + [在 Docker 容器元件中使用程序間通訊](#docker-container-ipc) + [在 Docker 容器元件 (Linux) 中使用 AWS 登入資料](#docker-container-token-exchange-service) + [在 Docker 容器元件 (Linux) 中使用串流管理員](#docker-container-stream-manager) ## 要求 若要在元件中執行 Docker 容器，您需要下列項目： + Greengrass 核心裝置。如果您沒有帳戶，請參閱 [教學課程：入門 AWS IoT Greengrass V2](getting-started.md)。 + [Docker 引擎](https://docs.docker.com/engine/) 1.9.1 或更新版本安裝在 Greengrass 核心裝置上。20.10 版是經過驗證可與 AWS IoT Greengrass Core 軟體搭配使用的最新版本。您必須先直接在核心裝置上安裝 Docker，才能部署執行 Docker 容器的元件。 **提示** 您也可以設定核心裝置，以在元件安裝時安裝 Docker Engine。例如，下列安裝指令碼會在載入 Docker 映像之前安裝 Docker 引擎。此安裝指令碼適用於 Debian 型 Linux 發行版本，例如 Ubuntu。如果您設定 元件使用此命令安裝 Docker Engine，您可能需要在生命週期指令碼`true`中`RequiresPrivilege`將 設定為 ，才能執行安裝和`docker`命令。如需詳細資訊，請參閱[AWS IoT Greengrass 元件配方參考](component-recipe-reference.md)。 ``` apt-get install docker-ce docker-ce-cli containerd.io && docker load -i {artifacts:path}/hello-world.tar ``` + 執行 Docker 容器元件的系統使用者必須具有根或管理員許可，或者您必須將 Docker 設定為以非根或非註冊使用者身分執行。 + 在 Linux 裝置上，您可以將使用者新增至 `docker`群組，在沒有 的情況下呼叫`docker`命令`sudo`。 + 在 Windows 裝置上，您可以將使用者新增至 `docker-users`群組，以呼叫沒有管理員權限的`docker`命令。 ------ #### [ Linux or Unix ] 若要將 `ggc_user`或您用來執行 Docker 容器元件的非根使用者新增至 `docker`群組，請執行下列命令。 ``` sudo usermod -aG docker ggc_user ``` 如需詳細資訊，請參閱[以非根使用者的身分管理 Docker](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)。 ------ #### [ Windows Command Prompt (CMD) ] 若要將 `ggc_user`或您用來執行 Docker 容器元件的使用者新增至 `docker-users`群組，請以管理員身分執行下列命令。 ``` net localgroup docker-users ggc_user /add ``` ------ #### [ Windows PowerShell ] 若要將 `ggc_user`或您用來執行 Docker 容器元件的使用者新增至 `docker-users`群組，請以管理員身分執行下列命令。 ``` Add-LocalGroupMember -Group docker-users -Member ggc_user ``` ------ + Docker 容器元件存取的檔案會[掛載為 Docker 容器中的磁碟](https://docs.docker.com/storage/volumes/)區。 + 如果您[將 AWS IoT Greengrass Core 軟體設定為使用網路代理](configure-greengrass-core-v2.md#configure-alpn-network-proxy)，則必須[將 Docker 設定為使用相同的代理伺服器](https://docs.docker.com/network/proxy/)。 除了這些要求之外，如果適用於您的環境，您還必須符合下列要求： + 若要使用 [Docker Compose](https://docs.docker.com/compose/) 建立和啟動 Docker 容器，請在 Greengrass 核心裝置上安裝 Docker Compose，並將 Docker Compose 檔案上傳至 S3 儲存貯體。您必須將 Compose 檔案存放在與 元件相同的 S3 AWS 帳戶 AWS 區域 儲存貯體中。如需在自訂元件中使用 `docker-compose up`命令的範例，請參閱 [從 Amazon ECR 或 Docker Hub 中的公有映像執行 Docker 容器](#run-docker-container-public-ecr-dockerhub)。 + 如果您在網路代理 AWS IoT Greengrass 之後執行 ，請將 Docker 協助程式設定為使用[代理伺服器](https://docs.docker.com/network/proxy/)。 + 如果您的 Docker 映像存放在 Amazon ECR 或 Docker Hub 中，請在 [Docker 容器元件中包含 Docker 元件管理員](docker-application-manager-component.md)元件做為相依性。您必須先在核心裝置上啟動 Docker 協助程式，才能部署元件。 此外，請包含影像 URIs做為元件成品。映像 URIs 的格式必須`docker:registry/image[:tag|@digest]`如下列範例所示： + 私有 Amazon ECR 映像： `docker:account-id.dkr.ecr.region.amazonaws.com/repository/image[:tag|@digest]` + 公有 Amazon ECR 映像： `docker:public.ecr.aws/repository/image[:tag|@digest]` + 公有 Docker Hub 映像： `docker:name[:tag|@digest]` 如需從存放在公有儲存庫中的映像執行 Docker 容器的詳細資訊，請參閱 [從 Amazon ECR 或 Docker Hub 中的公有映像執行 Docker 容器](#run-docker-container-public-ecr-dockerhub)。 + 如果您的 Docker 映像存放在 Amazon ECR 私有儲存庫中，則必須在 Docker 容器元件中包含字符交換服務元件做為相依性。此外，[Greengrass 裝置角色](device-service-role.md)必須允許 `ecr:GetAuthorizationToken`、 `ecr:BatchGetImage`和 `ecr:GetDownloadUrlForLayer`動作，如下列範例 IAM 政策所示。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "ecr:GetAuthorizationToken", "ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer" ], "Resource": [ "*" ], "Effect": "Allow" } ] } ``` ------ 如需有關從存放在 Amazon ECR 私有儲存庫中的映像執行 Docker 容器的資訊，請參閱 [從 Amazon ECR 中的私有映像執行 Docker 容器](#run-docker-container-private-ecr)。 + 若要使用存放在 Amazon ECR 私有儲存庫中的 Docker 映像，私有儲存庫必須與核心裝置 AWS 區域 位於相同的 中。 + 如果您的 Docker 映像或 Compose 檔案存放在 S3 儲存貯體中，[Greengrass 裝置角色](device-service-role.md)必須允許 `s3:GetObject`許可，以允許核心裝置將映像下載為元件成品，如下列範例 IAM 政策所示。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "s3:GetObject" ], "Resource": [ "*" ], "Effect": "Allow" } ] } ``` ------ 如需有關從存放在 Amazon S3 中的映像執行 Docker 容器的資訊，請參閱 [從 Amazon S3 中的映像執行 Docker 容器](#run-docker-container-s3)。 + 若要在 Docker 容器元件中使用程序間通訊 (IPC) AWS 、登入資料或串流管理員，您必須在執行 Docker 容器時指定其他選項。如需詳細資訊，請參閱下列內容： + [在 Docker 容器元件中使用程序間通訊](#docker-container-ipc) + [在 Docker 容器元件 (Linux) 中使用 AWS 登入資料](#docker-container-token-exchange-service) + [在 Docker 容器元件 (Linux) 中使用串流管理員](#docker-container-stream-manager) ## 從 Amazon ECR 或 Docker Hub 中的公有映像執行 Docker 容器 本節說明如何建立使用 Docker Compose 從存放 Amazon ECR 和 Docker Hub 的 Docker 映像檔執行 Docker 容器的自訂元件。 **使用 Docker Compose 執行 Docker 容器** 1. 建立 Docker Compose 檔案並將其上傳至 Amazon S3 儲存貯體。確定 [Greengrass 裝置角色](device-service-role.md)允許 `s3:GetObject` 許可，讓裝置存取 Compose 檔案。下列範例中顯示的 Compose 檔案範例包括來自 Amazon ECR 的 Amazon CloudWatch Agent 映像和來自 Docker Hub 的 MySQL 映像。 ``` version: "3" services: cloudwatchagent: image: "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest" mysql: image: "mysql:8.0" ``` 1. 在 AWS IoT Greengrass 核心裝置上[建立自訂元件](create-components.md)。下列範例中顯示的範例配方具有下列屬性： + Docker 應用程式管理員元件做為相依性。此元件可讓 從公 AWS IoT Greengrass 有 Amazon ECR 和 Docker Hub 儲存庫下載映像。 + 元件成品，指定公有 Amazon ECR 儲存庫中的 Docker 映像。 + 元件成品，指定公有 Docker Hub 儲存庫中的 Docker 映像。 + 元件成品，指定包含您要執行之 Docker 映像容器的 Docker Compose 檔案。 + 生命週期執行指令碼，使用 [docker-compose up](https://docs.docker.com/compose/reference/up/) 從指定的映像建立和啟動容器。 ------ #### [ JSON ] ``` { "RecipeFormatVersion": "2020-01-25", "ComponentName": "com.example.MyDockerComposeComponent", "ComponentVersion": "1.0.0", "ComponentDescription": "A component that uses Docker Compose to run images from public Amazon ECR and Docker Hub.", "ComponentPublisher": "Amazon", "ComponentDependencies": { "aws.greengrass.DockerApplicationManager": { "VersionRequirement": "~2.0.0" } }, "Manifests": [ { "Platform": { "os": "all" }, "Lifecycle": { "Run": "docker-compose -f {artifacts:path}/docker-compose.yaml up" }, "Artifacts": [ { "URI": "docker:public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest" }, { "URI": "docker:mysql:8.0" }, { "URI": "s3://amzn-s3-demo-bucket/folder/docker-compose.yaml" } ] } ] } ``` ------ #### [ YAML ] ``` --- RecipeFormatVersion: '2020-01-25' ComponentName: com.example.MyDockerComposeComponent ComponentVersion: '1.0.0' ComponentDescription: 'A component that uses Docker Compose to run images from public Amazon ECR and Docker Hub.' ComponentPublisher: Amazon ComponentDependencies: aws.greengrass.DockerApplicationManager: VersionRequirement: ~2.0.0 Manifests: - Platform: os: all Lifecycle: Run: docker-compose -f {artifacts:path}/docker-compose.yaml up Artifacts: - URI: "docker:public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest" - URI: "docker:mysql:8.0" - URI: "s3://amzn-s3-demo-bucket/folder/docker-compose.yaml" ``` ------ **注意** 若要在 Docker 容器元件中使用程序間通訊 (IPC) AWS 、登入資料或串流管理員，您必須在執行 Docker 容器時指定其他選項。如需詳細資訊，請參閱下列內容： [在 Docker 容器元件中使用程序間通訊](#docker-container-ipc) [在 Docker 容器元件 (Linux) 中使用 AWS 登入資料](#docker-container-token-exchange-service) [在 Docker 容器元件 (Linux) 中使用串流管理員](#docker-container-stream-manager) 1. [測試元件](test-components.md)以驗證其是否如預期般運作。 **重要** 您必須先安裝和啟動 Docker 協助程式，才能部署元件。 在本機部署元件之後，您可以執行 [Docker 容器 ls](https://docs.docker.com/engine/reference/commandline/container_ls/) 命令，以驗證您的容器是否執行。 ``` docker container ls ``` 1. 當元件準備就緒時，將元件上傳至 AWS IoT Greengrass 以部署到其他核心裝置。如需詳細資訊，請參閱[發佈元件以部署到您的核心裝置](publish-components.md)。 ## 從 Amazon ECR 中的私有映像執行 Docker 容器 本節說明如何建立自訂元件，從存放在 Amazon ECR 中私有儲存庫中的 Docker 映像執行 Docker 容器。 **執行 Docker 容器** 1. 在 AWS IoT Greengrass 核心裝置上[建立自訂元件](create-components.md)。使用下列範例配方，其具有下列屬性： + Docker 應用程式管理員元件做為相依性。此元件可讓 AWS IoT Greengrass 管理登入資料，以從私有儲存庫下載映像。 + 權杖交換服務元件做為相依性。此元件可讓 AWS IoT Greengrass 擷取 AWS 登入資料以與 Amazon ECR 互動。 + 元件成品，指定私有 Amazon ECR 儲存庫中的 Docker 映像。 + 生命週期執行指令碼，使用 [docker run](https://docs.docker.com/engine/reference/commandline/run/) 從映像建立和啟動容器。 ------ #### [ JSON ] ``` { "RecipeFormatVersion": "2020-01-25", "ComponentName": "com.example.MyPrivateDockerComponent", "ComponentVersion": "1.0.0", "ComponentDescription": "A component that runs a Docker container from a private Amazon ECR image.", "ComponentPublisher": "Amazon", "ComponentDependencies": { "aws.greengrass.DockerApplicationManager": { "VersionRequirement": "~2.0.0" }, "aws.greengrass.TokenExchangeService": { "VersionRequirement": "~2.0.0" } }, "Manifests": [ { "Platform": { "os": "all" }, "Lifecycle": { "Run": "docker run account-id.dkr.ecr.region.amazonaws.com/repository[:tag|@digest]" }, "Artifacts": [ { "URI": "docker:account-id.dkr.ecr.region.amazonaws.com/repository[:tag|@digest]" } ] } ] } ``` ------ #### [ YAML ] ``` --- RecipeFormatVersion: '2020-01-25' ComponentName: com.example.MyPrivateDockerComponent ComponentVersion: '1.0.0' ComponentDescription: 'A component that runs a Docker container from a private Amazon ECR image.' ComponentPublisher: Amazon ComponentDependencies: aws.greengrass.DockerApplicationManager: VersionRequirement: ~2.0.0 aws.greengrass.TokenExchangeService: VersionRequirement: ~2.0.0 Manifests: - Platform: os: all Lifecycle: Run: docker run account-id.dkr.ecr.region.amazonaws.com/repository[:tag|@digest] Artifacts: - URI: "docker:account-id.dkr.ecr.region.amazonaws.com/repository[:tag|@digest]" ``` ------ **注意** 若要在 Docker 容器元件中使用程序間通訊 (IPC) AWS 、登入資料或串流管理員，您必須在執行 Docker 容器時指定其他選項。如需詳細資訊，請參閱下列內容： [在 Docker 容器元件中使用程序間通訊](#docker-container-ipc) [在 Docker 容器元件 (Linux) 中使用 AWS 登入資料](#docker-container-token-exchange-service) [在 Docker 容器元件 (Linux) 中使用串流管理員](#docker-container-stream-manager) 1. [測試元件](test-components.md)以驗證其是否如預期般運作。 **重要** 您必須先安裝和啟動 Docker 協助程式，才能部署元件。 在本機部署元件之後，您可以執行 [Docker 容器 ls](https://docs.docker.com/engine/reference/commandline/container_ls/) 命令，以驗證您的容器是否執行。 ``` docker container ls ``` 1. 將元件上傳至 AWS IoT Greengrass 以部署至其他核心裝置。如需詳細資訊，請參閱[發佈元件以部署到您的核心裝置](publish-components.md)。 ## 從 Amazon S3 中的映像執行 Docker 容器 本節說明如何從存放在 Amazon S3 的 Docker 映像在元件中執行 Docker 容器。 **從 Amazon S3 中的映像在元件中執行 Docker 容器** 1. 執行 [docker save](https://docs.docker.com/engine/reference/commandline/save/) 命令來建立 Docker 容器的備份。您提供此備份做為執行容器的元件成品 AWS IoT Greengrass。將 *hello-world* 取代為映像的名稱，並將 *hello-world.tar* 取代為要建立的封存檔案名稱。 ``` docker save hello-world > artifacts/com.example.MyDockerComponent/1.0.0/hello-world.tar ``` 1. 在 AWS IoT Greengrass 核心裝置上[建立自訂元件](create-components.md)。使用下列範例配方，其具有下列屬性： + 使用 [Docker 載入](https://docs.docker.com/engine/reference/commandline/load/)從封存載入 Docker 映像的生命週期安裝指令碼。 + 生命週期執行指令碼，使用 [docker run](https://docs.docker.com/engine/reference/commandline/run/) 從映像建立和啟動容器。`--rm` 選項會在容器結束時清除容器。 ------ #### [ JSON ] ``` { "RecipeFormatVersion": "2020-01-25", "ComponentName": "com.example.MyS3DockerComponent", "ComponentVersion": "1.0.0", "ComponentDescription": "A component that runs a Docker container from an image in an S3 bucket.", "ComponentPublisher": "Amazon", "Manifests": [ { "Platform": { "os": "linux" }, "Lifecycle": { "install": { "Script": "docker load -i {artifacts:path}/hello-world.tar" }, "Run": { "Script": "docker run --rm hello-world" } } } ] } ``` ------ #### [ YAML ] ``` --- RecipeFormatVersion: '2020-01-25' ComponentName: com.example.MyS3DockerComponent ComponentVersion: '1.0.0' ComponentDescription: 'A component that runs a Docker container from an image in an S3 bucket.' ComponentPublisher: Amazon Manifests: - Platform: os: linux Lifecycle: install: Script: docker load -i {artifacts:path}/hello-world.tar Run: Script: docker run --rm hello-world ``` ------ **注意** 若要在 Docker 容器元件中使用程序間通訊 (IPC) AWS 、登入資料或串流管理員，您必須在執行 Docker 容器時指定其他選項。如需詳細資訊，請參閱下列內容： [在 Docker 容器元件中使用程序間通訊](#docker-container-ipc) [在 Docker 容器元件 (Linux) 中使用 AWS 登入資料](#docker-container-token-exchange-service) [在 Docker 容器元件 (Linux) 中使用串流管理員](#docker-container-stream-manager) 1. [測試元件](test-components.md)以驗證其是否如預期般運作。 在本機部署元件之後，您可以執行 [Docker 容器 ls](https://docs.docker.com/engine/reference/commandline/container_ls/) 命令，以驗證您的容器是否執行。 ``` docker container ls ``` 1. 當元件就緒時，將 Docker 映像封存上傳至 S3 儲存貯體，然後將其 URI 新增至元件配方。然後，您可以將元件上傳至 AWS IoT Greengrass 以部署至其他核心裝置。如需詳細資訊，請參閱[發佈元件以部署到您的核心裝置](publish-components.md)。 完成後，元件配方應如下所示。 ------ #### [ JSON ] ``` { "RecipeFormatVersion": "2020-01-25", "ComponentName": "com.example.MyS3DockerComponent", "ComponentVersion": "1.0.0", "ComponentDescription": "A component that runs a Docker container from an image in an S3 bucket.", "ComponentPublisher": "Amazon", "Manifests": [ { "Platform": { "os": "linux" }, "Lifecycle": { "install": { "Script": "docker load -i {artifacts:path}/hello-world.tar" }, "Run": { "Script": "docker run --rm hello-world" } }, "Artifacts": [ { "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.MyDockerComponent/1.0.0/hello-world.tar" } ] } ] } ``` ------ #### [ YAML ] ``` --- RecipeFormatVersion: '2020-01-25' ComponentName: com.example.MyS3DockerComponent ComponentVersion: '1.0.0' ComponentDescription: 'A component that runs a Docker container from an image in an S3 bucket.' ComponentPublisher: Amazon Manifests: - Platform: os: linux Lifecycle: install: Script: docker load -i {artifacts:path}/hello-world.tar Run: Script: docker run --rm hello-world Artifacts: - URI: s3://amzn-s3-demo-bucket/artifacts/com.example.MyDockerComponent/1.0.0/hello-world.tar ``` ------ ## 在 Docker 容器元件中使用程序間通訊 您可以使用 中的 Greengrass 處理程序間通訊 (IPC) 程式庫 AWS IoT Device SDK ，與 Greengrass 核、其他 Greengrass 元件和 進行通訊 AWS IoT Core。如需詳細資訊，請參閱[使用 AWS IoT Device SDK 與 Greengrass 核、其他元件和 通訊 AWS IoT Core與 Greengrass 核、其他元件和 通訊 AWS IoT Core](interprocess-communication.md)。 若要在 Docker 容器元件中使用 IPC，您必須使用下列參數執行 Docker 容器： + 在容器中掛載 IPC 通訊端。Greengrass 核提供`AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT`環境變數中的 IPC 通訊端檔案路徑。 + 將 `SVCUID`和 `AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT`環境變數設定為 Greengrass 核提供給元件的值。您的元件使用這些環境變數來驗證與 Greengrass 核的連線。 **Example 範例配方：發佈 MQTT 訊息至 AWS IoT Core (Python)** 下列配方定義發佈 MQTT 訊息的 Docker 容器元件範例 AWS IoT Core。此配方具有下列屬性： + 允許元件在所有主題 AWS IoT Core 上發佈 MQTT 訊息至 的授權政策 (`accessControl`)。如需詳細資訊，請參閱 [授權元件執行 IPC 操作](interprocess-communication.md#ipc-authorization-policies)和 [AWS IoT Core MQTT IPC 授權](ipc-iot-core-mqtt.md#ipc-iot-core-mqtt-authorization)。 + 元件成品，指定 Docker 影像做為 Amazon S3 中的 TAR 封存。 + 生命週期安裝指令碼，可從 TAR 封存檔載入 Docker 映像。 + 從映像執行 Docker 容器的生命週期執行指令碼。[Docker run](https://docs.docker.com/engine/reference/run/) 命令具有下列引數： + `-v` 引數會將 Greengrass IPC 通訊端掛載在容器中。 + 前兩個`-e`引數會在 Docker 容器中設定所需的環境變數。 + 其他`-e`引數會設定此範例所使用的環境變數。 + `--rm` 引數會在容器結束時清除容器。 ``` { "RecipeFormatVersion": "2020-01-25", "ComponentName": "com.example.python.docker.PublishToIoTCore", "ComponentVersion": "1.0.0", "ComponentDescription": "Uses interprocess communication to publish an MQTT message to IoT Core.", "ComponentPublisher": "Amazon", "ComponentConfiguration": { "DefaultConfiguration": { "topic": "test/topic/java", "message": "Hello, World!", "qos": "1", "accessControl": { "aws.greengrass.ipc.mqttproxy": { "com.example.python.docker.PublishToIoTCore:pubsub:1": { "policyDescription": "Allows access to publish to IoT Core on all topics.", "operations": [ "aws.greengrass#PublishToIoTCore" ], "resources": [ "*" ] } } } } }, "Manifests": [ { "Platform": { "os": "all" }, "Lifecycle": { "install": "docker load -i {artifacts:path}/publish-to-iot-core.tar", "Run": "docker run -v $AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT:$AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT -e SVCUID -e AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT -e MQTT_TOPIC=\"{configuration:/topic}\" -e MQTT_MESSAGE=\"{configuration:/message}\" -e MQTT_QOS=\"{configuration:/qos}\" --rm publish-to-iot-core" }, "Artifacts": [ { "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.PublishToIoTCore/1.0.0/publish-to-iot-core.tar" } ] } ] } ``` ``` RecipeFormatVersion: '2020-01-25' ComponentName: com.example.python.docker.PublishToIoTCore ComponentVersion: 1.0.0 ComponentDescription: Uses interprocess communication to publish an MQTT message to IoT Core. ComponentPublisher: Amazon ComponentConfiguration: DefaultConfiguration: topic: 'test/topic/java' message: 'Hello, World!' qos: '1' accessControl: aws.greengrass.ipc.mqttproxy: 'com.example.python.docker.PublishToIoTCore:pubsub:1': policyDescription: Allows access to publish to IoT Core on all topics. operations: - 'aws.greengrass#PublishToIoTCore' resources: - '*' Manifests: - Platform: os: all Lifecycle: install: 'docker load -i {artifacts:path}/publish-to-iot-core.tar' Run: | docker run \ -v $AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT:$AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT \ -e SVCUID \ -e AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT \ -e MQTT_TOPIC="{configuration:/topic}" \ -e MQTT_MESSAGE="{configuration:/message}" \ -e MQTT_QOS="{configuration:/qos}" \ --rm publish-to-iot-core Artifacts: - URI: s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.PublishToIoTCore/1.0.0/publish-to-iot-core.tar ``` ## 在 Docker 容器元件 (Linux) 中使用 AWS 登入資料 您可以使用[字符交換服務元件](token-exchange-service-component.md)與 Greengrass 元件中的 AWS 服務互動。此元件會使用本機容器伺服器，從核心裝置的[字符交換角色](device-service-role.md)提供 AWS 登入資料。如需詳細資訊，請參閱[與 AWS 服務互動](interact-with-aws-services.md)。 **注意** 本節中的範例僅適用於 Linux 核心裝置。 若要在 Docker 容器元件中使用字符交換服務的 AWS 憑證，您必須使用下列參數執行 Docker 容器： + 使用 `--network=host`引數提供主機網路的存取權。此選項可讓 Docker 容器連線至本機字符交換服務，以擷取 AWS 憑證。此引數僅適用於 Docker for Linux。 **警告** 此選項可讓容器存取主機上的所有本機網路介面，因此此選項比沒有主機網路存取權的情況下執行 Docker 容器更不安全。當您開發和執行使用此選項的 Docker 容器元件時，請考慮這一點。如需詳細資訊，請參閱 *Docker 文件*中的[網路：主機](https://docs.docker.com/engine/reference/run/#network-host)。 + 將 `AWS_CONTAINER_CREDENTIALS_FULL_URI`和 `AWS_CONTAINER_AUTHORIZATION_TOKEN`環境變數設定為 Greengrass 核提供給 components 的值。 AWS SDKs使用這些環境變數來擷取 AWS 登入資料。 **Example 範例配方：列出 Docker 容器元件中的 S3 儲存貯體 (Python)** 下列配方會定義範例 Docker 容器元件，列出 中的 S3 儲存貯體 AWS 帳戶。此配方具有下列屬性： + 做為相依性的字符交換服務元件。此相依性可讓 元件擷取 AWS 登入資料，以與其他 AWS 服務互動。 + 元件成品，指定 Docker 影像做為 Amazon S3 中的 tar 封存。 + 生命週期安裝指令碼，可從 TAR 封存檔載入 Docker 映像。 + 從映像執行 Docker 容器的生命週期執行指令碼。[Docker run](https://docs.docker.com/engine/reference/run/) 命令具有下列引數： + `--network=host` 引數提供容器對主機網路的存取權，讓容器可以連線至字符交換服務。 + `-e` 引數會在 Docker 容器中設定所需的環境變數。 + `--rm` 引數會在容器結束時清除容器。 ``` { "RecipeFormatVersion": "2020-01-25", "ComponentName": "com.example.python.docker.ListS3Buckets", "ComponentVersion": "1.0.0", "ComponentDescription": "Uses the token exchange service to lists your S3 buckets.", "ComponentPublisher": "Amazon", "ComponentDependencies": { "aws.greengrass.TokenExchangeService": { "VersionRequirement": "^2.0.0", "DependencyType": "HARD" } }, "Manifests": [ { "Platform": { "os": "linux" }, "Lifecycle": { "install": "docker load -i {artifacts:path}/list-s3-buckets.tar", "Run": "docker run --network=host -e AWS_CONTAINER_AUTHORIZATION_TOKEN -e AWS_CONTAINER_CREDENTIALS_FULL_URI --rm list-s3-buckets" }, "Artifacts": [ { "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.ListS3Buckets/1.0.0/list-s3-buckets.tar" } ] } ] } ``` ``` RecipeFormatVersion: '2020-01-25' ComponentName: com.example.python.docker.ListS3Buckets ComponentVersion: 1.0.0 ComponentDescription: Uses the token exchange service to lists your S3 buckets. ComponentPublisher: Amazon ComponentDependencies: aws.greengrass.TokenExchangeService: VersionRequirement: ^2.0.0 DependencyType: HARD Manifests: - Platform: os: linux Lifecycle: install: 'docker load -i {artifacts:path}/list-s3-buckets.tar' Run: | docker run \ --network=host \ -e AWS_CONTAINER_AUTHORIZATION_TOKEN \ -e AWS_CONTAINER_CREDENTIALS_FULL_URI \ --rm list-s3-buckets Artifacts: - URI: s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.ListS3Buckets/1.0.0/list-s3-buckets.tar ``` ## 在 Docker 容器元件 (Linux) 中使用串流管理員 您可以使用[串流管理員元件](stream-manager-component.md)來管理 Greengrass 元件中的資料串流。此元件可讓您處理資料串流並將大量 IoT 資料傳輸至 AWS 雲端。 AWS IoT Greengrass 提供串流管理員 SDK，讓您用來與串流管理員元件互動。如需詳細資訊，請參閱[管理 Greengrass 核心裝置上的資料串流](manage-data-streams.md)。 **注意** 本節中的範例僅適用於 Linux 核心裝置。 若要在 Docker 容器元件中使用串流管理員 SDK，您必須使用下列參數執行 Docker 容器： + 使用 `--network=host`引數提供主機網路的存取權。此選項可讓 Docker 容器透過本機 TLS 連線與串流管理員元件互動。此引數僅適用於適用於 Linux 的 Docker **警告** 此選項可讓容器存取主機上的所有本機網路介面，因此此選項比沒有主機網路存取權的情況下執行 Docker 容器更不安全。當您開發和執行使用此選項的 Docker 容器元件時，請考慮這一點。如需詳細資訊，請參閱 *Docker 文件*中的[網路：主機](https://docs.docker.com/engine/reference/run/#network-host)。 + 如果您將串流管理員元件設定為需要身分驗證，這是預設行為，請將`AWS_CONTAINER_CREDENTIALS_FULL_URI`環境變數設定為 Greengrass 核提供給元件的值。如需詳細資訊，請參閱[串流管理員組態](stream-manager-component.md#stream-manager-component-configuration)。 + 如果您將串流管理員元件設定為使用非預設連接埠，請使用[程序間通訊 (IPC)](interprocess-communication.md) 從串流管理員元件組態取得連接埠。您必須使用其他選項來執行 Docker 容器，才能使用 IPC。如需詳細資訊，請參閱下列內容： + [連線至應用程式程式碼中的串流管理員](use-stream-manager-in-custom-components.md#connect-to-stream-manager) + [在 Docker 容器元件中使用程序間通訊](#docker-container-ipc) **Example 範例配方：將檔案串流到 Docker 容器元件 (Python) 中的 S3 儲存貯體** 下列配方定義範例 Docker 容器元件，可建立檔案並將其串流至 S3 儲存貯體。此配方具有下列屬性： + 串流管理員元件做為相依性。此相依性可讓元件使用串流管理員 SDK 與串流管理員元件互動。 + 元件成品，指定 Docker 影像做為 Amazon S3 中的 TAR 封存。 + 生命週期安裝指令碼，可從 TAR 封存檔載入 Docker 映像。 + 從映像執行 Docker 容器的生命週期執行指令碼。[Docker run](https://docs.docker.com/engine/reference/run/) 命令具有下列引數： + `--network=host` 引數提供容器對主機網路的存取權，讓容器可以連線至串流管理員元件。 + 第一個`-e`引數會在 Docker 容器中設定所需的`AWS_CONTAINER_AUTHORIZATION_TOKEN`環境變數。 + 其他`-e`引數會設定此範例所使用的環境變數。 + `-v` 引數會將元件[的工作資料夾](component-recipe-reference.md#component-recipe-work-path)掛載在容器中。此範例會在工作資料夾中建立 檔案，以使用串流管理員將該檔案上傳至 Amazon S3。 + `--rm` 引數會在容器結束時清除容器。 ``` { "RecipeFormatVersion": "2020-01-25", "ComponentName": "com.example.python.docker.StreamFileToS3", "ComponentVersion": "1.0.0", "ComponentDescription": "Creates a text file and uses stream manager to stream the file to S3.", "ComponentPublisher": "Amazon", "ComponentDependencies": { "aws.greengrass.StreamManager": { "VersionRequirement": "^2.0.0", "DependencyType": "HARD" } }, "ComponentConfiguration": { "DefaultConfiguration": { "bucketName": "" } }, "Manifests": [ { "Platform": { "os": "linux" }, "Lifecycle": { "install": "docker load -i {artifacts:path}/stream-file-to-s3.tar", "Run": "docker run --network=host -e AWS_CONTAINER_AUTHORIZATION_TOKEN -e BUCKET_NAME=\"{configuration:/bucketName}\" -e WORK_PATH=\"{work:path}\" -v {work:path}:{work:path} --rm stream-file-to-s3" }, "Artifacts": [ { "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.StreamFileToS3/1.0.0/stream-file-to-s3.tar" } ] } ] } ``` ``` RecipeFormatVersion: '2020-01-25' ComponentName: com.example.python.docker.StreamFileToS3 ComponentVersion: 1.0.0 ComponentDescription: Creates a text file and uses stream manager to stream the file to S3. ComponentPublisher: Amazon ComponentDependencies: aws.greengrass.StreamManager: VersionRequirement: ^2.0.0 DependencyType: HARD ComponentConfiguration: DefaultConfiguration: bucketName: '' Manifests: - Platform: os: linux Lifecycle: install: 'docker load -i {artifacts:path}/stream-file-to-s3.tar' Run: | docker run \ --network=host \ -e AWS_CONTAINER_AUTHORIZATION_TOKEN \ -e BUCKET_NAME="{configuration:/bucketName}" \ -e WORK_PATH="{work:path}" \ -v {work:path}:{work:path} \ --rm stream-file-to-s3 Artifacts: - URI: s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.StreamFileToS3/1.0.0/stream-file-to-s3.tar ``` # AWS IoT Greengrass 元件配方參考 元件配方是定義元件詳細資訊、相依性、成品和生命週期的檔案。例如，元件*生命週期*會指定要執行的命令來安裝、執行和關閉元件。 AWS IoT Greengrass 核心使用您在配方中定義的生命週期來安裝和執行元件。當您部署元件時， AWS IoT Greengrass 此服務會使用配方來識別要部署至核心裝置的相依性和成品。 在配方中，您可以為元件支援的每個平台定義唯一的相依性和生命週期。您可以使用此功能，將元件部署到具有不同需求的多個平台的裝置。您也可以使用此功能來 AWS IoT Greengrass 防止 在不支援它的裝置上安裝元件。 每個配方都包含*資訊清單*清單。每個資訊清單都會指定一組平台需求，以及用於其平台符合這些需求之核心裝置的生命週期和成品。核心裝置使用第一個資訊清單，其中包含裝置符合的平台需求。指定沒有任何平台需求的資訊清單，以符合任何核心裝置。 您也可以指定不在資訊清單中的全域生命週期。在 全球生命週期中，您可以使用*選取索引鍵*來識別生命週期的子區段。然後，您可以在資訊清單中指定這些選取索引鍵，以在資訊清單的生命週期之外，使用全域生命週期的這些區段。只有在資訊清單未定義生命週期時，核心裝置才會使用資訊清單的選擇索引鍵。您可以使用資訊清單中的`all`選取項目來比對全域生命週期的區段，無需選取索引鍵。 AWS IoT Greengrass 核心軟體選取符合核心裝置的資訊清單後，會執行下列動作來識別要使用的生命週期步驟： + 如果選取的資訊清單定義生命週期，核心裝置會使用該生命週期。 + 如果選取的資訊清單未定義生命週期，核心裝置會使用全域生命週期。核心裝置會執行下列動作，以識別要使用的全域生命週期區段： + 如果資訊清單定義選取索引鍵，核心裝置會使用包含資訊清單選取索引鍵的全域生命週期區段。 + 如果資訊清單未定義選取索引鍵，核心裝置會使用沒有選取索引鍵的全域生命週期區段。此行為等同於定義`all`選取的資訊清單。 **重要** 核心裝置必須符合至少一個資訊清單的平台需求，才能安裝元件。如果沒有資訊清單符合核心裝置，則 AWS IoT Greengrass Core 軟體不會安裝元件，且部署會失敗。 您可以 [JSON](https://en.wikipedia.org/wiki/JSON) 或 [YAML](https://en.wikipedia.org/wiki/YAML) 格式定義配方。配方範例區段包含每種格式的配方。 **Topics** + [配方驗證](#recipe-validation) + [配方格式](#recipe-format) + [配方變數](#recipe-variables) + [配方範例](#recipe-examples) ## 配方驗證 Greengrass 會在建立元件版本時驗證 JSON 或 YAML 元件配方。此配方驗證會檢查您的 JSON 或 YAML 元件配方是否有常見錯誤，以防止潛在的部署問題。驗證會檢查配方是否有常見錯誤 （例如缺少逗號、括號和欄位），並確保配方格式正確。 如果您收到配方驗證錯誤訊息，請檢查您的配方是否有任何遺漏的逗號、括號或欄位。查看[配方格式](#recipe-format)，確認您未遺漏任何欄位。 ## 配方格式 當您定義元件的配方時，您可以在配方文件中指定下列資訊。相同的結構適用於 YAML 和 JSON 格式的配方。 `RecipeFormatVersion` 配方的範本版本。選擇下列選項： + `2020-01-25` `ComponentName` 此配方定義的元件名稱。元件名稱 AWS 帳戶 在每個區域中的 中必須是唯一的。 **提示** + 使用反向網域名稱格式，以避免公司內發生名稱衝突。例如，如果您的公司擁有`example.com`並處理太陽能專案，您可以將 Hello World 元件命名為 `com.example.solar.HelloWorld`。這有助於避免貴公司內的元件名稱衝突。 + 避免在元件名稱中使用`aws.greengrass`字首。 AWS IoT Greengrass 會針對其提供的[公有元件](public-components.md)使用此字首。如果您選擇與公有元件相同的名稱，您的元件會取代該元件。然後，在部署與該公有元件相依的元件時， AWS IoT Greengrass 提供您的元件而非公有元件。此功能可讓您覆寫公有元件的行為，但如果您不打算覆寫公有元件，也可能會破壞其他元件。 `ComponentVersion` 元件的版本。主要、次要和修補程式值的最大值為 999999。 AWS IoT Greengrass 使用元件的語意版本。語意版本遵循 *major*.*minor*.*patch* 號碼系統。例如，版本`1.0.0`代表元件的第一個主要版本。如需詳細資訊，請參閱[語意版本規格](https://semver.org/)。 `ComponentDescription` （選用） 元件的描述。 `ComponentPublisher` 元件的發佈者或作者。 `ComponentConfiguration` （選用） 定義元件組態或參數的物件。您可以定義預設組態，然後在部署元件時，指定要提供給元件的組態物件。元件組態支援巢狀參數和結構。此物件包含下列資訊： `DefaultConfiguration` 定義元件預設組態的物件。您可以定義此物件的結構。 AWS IoT Greengrass 使用 JSON 做為組態值。JSON 會指定數字類型，但不會區分整數和浮點數。因此，組態值可能會轉換為浮點數 AWS IoT Greengrass。為了確保您的元件使用正確的資料類型，建議您將數值組態值定義為字串。然後，讓您的元件將它們剖析為整數或浮點數。這可確保您的組態值在組態和核心裝置上具有相同的類型。 `ComponentDependencies` （選用） 物件的字典，每個物件都會定義元件的元件相依性。每個物件的 索引鍵可識別元件相依性的名稱。 AWS IoT Greengrass 當元件安裝時， 安裝元件相依性。在啟動元件之前 AWS IoT Greengrass 等待相依性啟動。每個物件都包含下列資訊： `VersionRequirement` 定義此相依性的相容元件版本的 npm 樣式語意版本限制。您可以指定版本或一系列版本。如需詳細資訊，請參閱 [npm 語意版本計算器](https://semver.npmjs.com/)。 `DependencyType` （選用） 此相依性的類型。您可以從以下選項中選擇。 + `SOFT` - 在相依性變更狀態時，元件不會重新啟動。 + `HARD` - 在相依性變更狀態時，元件會重新啟動。 預設為 `HARD`。 `ComponentType` （選用） 元件的類型。 我們不建議您在 recipe 中指定元件類型。當您建立元件時， 會為您 AWS IoT Greengrass 設定 類型。 類型可以是下列類型之一： + `aws.greengrass.generic` – 元件會執行命令或提供成品。 + `aws.greengrass.lambda` – 元件會使用 Lambda [啟動器元件執行 Lambda](lambda-launcher-component.md) 函數。`ComponentSource` 參數指定此元件執行之 Lambda 函數的 ARN。 我們不建議您使用此選項，因為當您從 Lambda 函數建立元件 AWS IoT Greengrass 時，它會由 設定。如需詳細資訊，請參閱[執行 AWS Lambda 函數](run-lambda-functions.md)。 + `aws.greengrass.plugin` – 元件在與 Greengrass 核相同的 Java 虛擬機器 (JVM) 中執行。如果您部署或重新啟動外掛程式元件，Greengrass 核會重新啟動。 外掛程式元件使用與 Greengrass 核相同的日誌檔案。如需詳細資訊，請參閱[監控 AWS IoT Greengrass 日誌](monitor-logs.md)。 我們不建議您在元件配方中使用此選項，因為它適用於以 Java AWS編寫且直接與 Greengrass 核界面的元件。如需哪些公有元件是外掛程式的詳細資訊，請參閱 [AWS提供的元件](public-components.md)。 + `aws.greengrass.nucleus` – 核心元件。如需詳細資訊，請參閱[Greengrass 核](greengrass-nucleus-component.md)。 我們不建議您在元件配方中使用此選項。它適用於 Greengrass 核元件，可提供 AWS IoT Greengrass Core 軟體的最低功能。 `aws.greengrass.generic` 當您從配方建立元件，或從 Lambda 函數建立元件`aws.greengrass.lambda`時，預設為 。 如需詳細資訊，請參閱[元件類型](develop-greengrass-components.md#component-types)。 `ComponentSource` （選用） 元件執行的 Lambda 函數 ARN。 我們不建議您在 recipe 中指定元件來源。當您從 Lambda 函數建立元件時， 會為您 AWS IoT Greengrass 設定此參數。如需詳細資訊，請參閱[執行 AWS Lambda 函數](run-lambda-functions.md)。 `Manifests` 各定義元件生命週期、參數和平台需求的物件清單。如果核心裝置符合多個資訊清單的平台需求， AWS IoT Greengrass 會使用核心裝置符合的第一個資訊清單。為了確保核心裝置使用正確的資訊清單，請先定義具有更嚴格平台需求的資訊清單。適用於所有平台的資訊清單必須是清單中的最後一個資訊清單。 核心裝置必須符合至少一個資訊清單的平台需求，才能安裝元件。如果沒有資訊清單符合核心裝置，則 AWS IoT Greengrass Core 軟體不會安裝元件，且部署會失敗。 每個物件都包含下列資訊： `Name` （選用） 此資訊清單定義之平台的易記名稱。 如果您省略此參數， 會從平台`os`和 AWS IoT Greengrass 建立名稱`architecture`。 `Platform` （選用） 定義適用此資訊清單之平台的物件。省略此參數，以定義適用於所有平台的資訊清單。 此物件會指定核心裝置執行所在的平台的鍵/值對。當您部署此元件時， AWS IoT Greengrass 核心軟體會將這些鍵/值對與核心裝置上的平台屬性進行比較。 AWS IoT Greengrass 核心軟體一律定義 `os`和 `architecture`，且可能定義其他屬性。您可以在部署 Greengrass 核元件時指定核心裝置的自訂平台屬性。如需詳細資訊，請參閱 [平台覆寫 Greengrass 核元件的參數](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-platform-overrides)。 [Greengrass 核](greengrass-nucleus-component.md) 對於每個鍵/值對，您可以指定下列其中一個值： + 確切的值，例如 `linux`或 `windows`。確切值必須以字母或數字開頭。 + `*`，符合任何值。當值不存在時，這也符合。 + Java 樣式的規則表達式，例如 `/windows|linux/`。規則表達式必須以斜線字元 () 開頭和結尾`/`。例如，規則表達式`/.+/`符合任何非空白值。 此物件包含下列資訊： `runtime` 此資訊清單支援的平台的 [Greengrass 核執行時間](https://docs.aws.amazon.com/greengrass/v2/developerguide/how-it-works.html#concept-overview)。使用平台 定義多個資訊清單時`runtime`，配方中支援的執行時間值僅為 `aws_nucleus_lite`和 `*`。若要以傳統裝置為目標，不得在配方中指定執行時間欄位。支援的 Greengrass Nucleus 執行時間包括下列值： + `*` + `aws_nucleus_lite` `os` （選用） 此資訊清單支援的平台的作業系統名稱。常見的平台包括下列值： + `linux` + `windows` + `darwin` (macOS) `architecture` （選用） 此資訊清單支援的平台的處理器架構。常見的架構包括下列值： + `amd64` + `arm` + `aarch64` + `x86` `architecture.detail` （選用） 此資訊清單支援的平台的處理器架構詳細資訊。常見的架構詳細資訊包括下列值： + `arm61` + `arm71` + `arm81` `key` （選用） 您為此資訊清單定義的平台屬性。將*金鑰*取代為平台屬性的名稱。Core AWS IoT Greengrass 軟體會比對此平台屬性與您在 Greengrass 核元件組態中指定的鍵值對。如需詳細資訊，請參閱 [平台覆寫 Greengrass 核元件的參數](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-platform-overrides)。 [Greengrass 核](greengrass-nucleus-component.md) 使用反向網域名稱格式，以避免公司內發生名稱衝突。例如，如果您的公司擁有`example.com`並處理無線電專案，您可以命名自訂平台屬性 `com.example.radio.RadioModule`。這有助於避免您公司內的平台屬性名稱衝突。 例如，您可以定義平台屬性 `com.example.radio.RadioModule`，根據核心裝置上可用的無線電模組來指定不同的資訊清單。每個資訊清單可以包含套用至不同硬體組態的不同成品，以便您將最少的軟體集部署到核心裝置。 `Lifecycle` 物件或字串，定義如何在此資訊清單定義的平台上安裝和執行 元件。您也可以定義適用於所有平台的[全域生命週期](#global-lifecycle-definition)。只有在要使用的資訊清單未指定生命週期時，核心裝置才會使用全域生命週期。 您可以在資訊清單中定義此生命週期。您在此處指定的生命週期步驟僅適用於此資訊清單定義的平台。您也可以定義適用於所有平台的[全域生命週期](#global-lifecycle-definition)。 此物件或字串包含下列資訊： `Setenv` （選用） 要提供給所有生命週期指令碼的環境變數字典。您可以在每個生命週期指令碼`Setenv`中使用 覆寫這些環境變數。 `install` （選用） 物件或字串，定義元件安裝時要執行的指令碼。 AWS IoT Greengrass 核心軟體也會在每次軟體啟動時執行此生命週期步驟。 如果`install`指令碼以成功代碼結束，元件會進入 `INSTALLED` 狀態。 此物件或字串包含下列資訊： `Script` 要執行的指令碼。 `RequiresPrivilege` （選用） 您可以使用根權限執行指令碼。如果您將此選項設定為 `true`，則 AWS IoT Greengrass Core 軟體會執行此生命週期指令碼做為根目錄，而不是您設定為執行此元件的系統使用者。預設為 `false`。 `Skipif` （選用） 檢查以判斷是否執行指令碼。您可以定義 來檢查可執行檔是否在路徑上，或檔案是否存在。如果輸出為 true，則 AWS IoT Greengrass Core 軟體會略過 步驟。選擇下列其中一個檢查： + `onpath runnable` – 檢查可執行檔是否在系統路徑上。例如，如果 Python 3 可用，請使用 **onpath python3**略過此生命週期步驟。 + `exists file` – 檢查檔案是否存在。例如，如果 `/tmp/my-configuration.db` 存在，請使用 **exists /tmp/my-configuration.db**略過此生命週期步驟。 `Timeout` （選用） 在 AWS IoT Greengrass Core 軟體終止程序之前，指令碼可執行的時間上限，以秒為單位。 預設：120 秒 `Setenv` （選用） 要提供給指令碼的環境變數字典。這些環境變數會覆寫您在 中提供的變數`Lifecycle.Setenv`。 `run` （選用） 物件或字串，定義元件啟動時要執行的指令碼。 此生命週期步驟執行時，元件會進入 `RUNNING` 狀態。如果`run`指令碼以成功碼結束，元件會進入 `STOPPING` 狀態。如果指定`shutdown`指令碼，則會執行；否則元件會進入 `FINISHED` 狀態。 相依於此元件的元件會在此生命週期步驟執行時啟動。若要執行背景程序，例如相依元件使用的服務，請改用`startup`生命週期步驟。 當您使用`run`生命週期部署元件時，核心裝置可以在此生命週期指令碼執行後立即報告部署。因此，即使`run`生命週期指令碼在執行後很快失敗，部署也可以完成且成功。如果您希望部署狀態取決於元件啟動指令碼的結果，請改用`startup`生命週期步驟。 您只能定義一個 `startup`或 `run`生命週期。 此物件或字串包含下列資訊： `Script` 要執行的指令碼。 `RequiresPrivilege` （選用） 您可以使用根權限執行指令碼。如果您將此選項設定為 `true`，則 AWS IoT Greengrass Core 軟體會執行此生命週期指令碼做為根目錄，而不是您設定為執行此元件的系統使用者。預設為 `false`。 `Skipif` （選用） 檢查以判斷是否執行指令碼。您可以定義 來檢查可執行檔是否在路徑上，或檔案是否存在。如果輸出為 true，則 AWS IoT Greengrass Core 軟體會略過 步驟。選擇下列其中一個檢查： + `onpath runnable` – 檢查可執行檔是否在系統路徑上。例如，如果 Python 3 可用，請使用 **onpath python3**略過此生命週期步驟。 + `exists file` – 檢查檔案是否存在。例如，如果 `/tmp/my-configuration.db` 存在，請使用 **exists /tmp/my-configuration.db**略過此生命週期步驟。 `Timeout` （選用） 在 AWS IoT Greengrass Core 軟體終止程序之前，指令碼可執行的時間上限，以秒為單位。 根據預設，此生命週期步驟不會逾時。如果您省略此逾時，`run`指令碼會執行直到結束為止。 `Setenv` （選用） 要提供給指令碼的環境變數字典。這些環境變數會覆寫您在 中提供的變數`Lifecycle.Setenv`。 `startup` （選用） 物件或字串，定義元件啟動時要執行的背景程序。 使用 `startup`執行命令，該命令必須成功結束，或將元件的狀態更新為 `RUNNING`，然後相依元件才能啟動。使用 [UpdateState](ipc-component-lifecycle.md#ipc-operation-updatestate) IPC 操作，將元件的狀態設定為 `RUNNING`或當元件啟動未結束的指令碼`ERRORED`時。例如，您可以定義使用 啟動 MySQL 程序`startup`的步驟`/etc/init.d/mysqld start`。 此生命週期步驟執行時，元件會進入 `STARTING` 狀態。如果`startup`指令碼以成功碼結束，元件會進入 `RUNNING` 狀態。然後，相依元件可以啟動。 當您使用`startup`生命週期部署元件時，核心裝置可以在此生命週期指令碼結束或報告其狀態後，將部署報告為完成。換句話說，部署的狀態是直到所有元件的啟動指令碼結束或報告狀態`IN_PROGRESS`為止。 您只能定義一個 `startup`或 `run`生命週期。 此物件或字串包含下列資訊： `Script` 要執行的指令碼。 `RequiresPrivilege` （選用） 您可以使用根權限執行指令碼。如果您將此選項設定為 `true`，則 AWS IoT Greengrass 核心軟體會執行此生命週期指令碼做為根目錄，而不是您設定為執行此元件的系統使用者。預設為 `false`。 `Skipif` （選用） 檢查以判斷是否執行指令碼。您可以定義 來檢查可執行檔是否在路徑上，或檔案是否存在。如果輸出為 true，則 AWS IoT Greengrass Core 軟體會略過 步驟。選擇下列其中一項檢查： + `onpath runnable` – 檢查可執行檔是否在系統路徑上。例如，如果 Python 3 可用，請使用 **onpath python3**略過此生命週期步驟。 + `exists file` – 檢查檔案是否存在。例如，如果 `/tmp/my-configuration.db` 存在，請使用 **exists /tmp/my-configuration.db**略過此生命週期步驟。 `Timeout` （選用） 在 AWS IoT Greengrass Core 軟體終止程序之前，指令碼可執行的時間上限，以秒為單位。 預設：120 秒 `Setenv` （選用） 要提供給指令碼的環境變數字典。這些環境變數會覆寫您在 中提供的變數`Lifecycle.Setenv`。 `shutdown` （選用） 物件或字串，定義元件關閉時要執行的指令碼。使用關閉生命週期來執行您希望在元件處於 `STOPPING` 狀態時執行的程式碼。關機生命週期可用來停止由 `startup`或 `run`指令碼啟動的程序。 如果您在 中啟動背景程序`startup`，請使用 `shutdown` 步驟在元件關閉時停止該程序。例如，您可以定義使用 停止 MySQL 程序`shutdown`的步驟`/etc/init.d/mysqld stop`。 `shutdown` 指令碼會在元件進入 `STOPPING` 狀態後執行。如果指令碼成功完成，元件會進入 `FINISHED` 狀態。 此物件或字串包含下列資訊： `Script` 要執行的指令碼。 `RequiresPrivilege` （選用） 您可以使用根權限執行指令碼。如果您將此選項設定為 `true`，則 AWS IoT Greengrass 核心軟體會執行此生命週期指令碼做為根目錄，而不是您設定為執行此元件的系統使用者。預設為 `false`。 `Skipif` （選用） 檢查以判斷是否執行指令碼。您可以定義 來檢查可執行檔是否在路徑上，或檔案是否存在。如果輸出為 true，則 AWS IoT Greengrass Core 軟體會略過 步驟。選擇下列其中一項檢查： + `onpath runnable` – 檢查可執行檔是否在系統路徑上。例如，如果 Python 3 可用，請使用 **onpath python3**略過此生命週期步驟。 + `exists file` – 檢查檔案是否存在。例如，如果 `/tmp/my-configuration.db` 存在，請使用 **exists /tmp/my-configuration.db**略過此生命週期步驟。 `Timeout` （選用） 在 AWS IoT Greengrass Core 軟體終止程序之前，指令碼可執行的時間上限，以秒為單位。 預設：15 秒。 `Setenv` （選用） 要提供給指令碼的環境變數字典。這些環境變數會覆寫您在 中提供的變數`Lifecycle.Setenv`。 `recover` （選用） 物件或字串，定義元件發生錯誤時要執行的指令碼。 此步驟會在元件進入 `ERRORED` 狀態時執行。如果元件變成`ERRORED`三次但未成功復原，則元件會變更為 `BROKEN` 狀態。若要修正`BROKEN`元件，您必須再次部署。 此物件或字串包含下列資訊： `Script` 要執行的指令碼。 `RequiresPrivilege` （選用） 您可以使用根權限執行指令碼。如果您將此選項設定為 `true`，則 AWS IoT Greengrass 核心軟體會執行此生命週期指令碼做為根目錄，而不是您設定為執行此元件的系統使用者。預設為 `false`。 `Skipif` （選用） 檢查以判斷是否執行指令碼。您可以定義 來檢查可執行檔是否在路徑上，或檔案是否存在。如果輸出為 true，則 AWS IoT Greengrass Core 軟體會略過 步驟。選擇下列其中一項檢查： + `onpath runnable` – 檢查可執行檔是否在系統路徑上。例如，如果 Python 3 可用，請使用 **onpath python3**略過此生命週期步驟。 + `exists file` – 檢查檔案是否存在。例如，如果 `/tmp/my-configuration.db` 存在，請使用 **exists /tmp/my-configuration.db**略過此生命週期步驟。 `Timeout` （選用） 在 AWS IoT Greengrass Core 軟體終止程序之前，指令碼可執行的時間上限，以秒為單位。 預設：60 秒。 `Setenv` （選用） 要提供給指令碼的環境變數字典。這些環境變數會覆寫您在 中提供的變數`Lifecycle.Setenv`。 `bootstrap` （選用） 物件或字串，定義需要 AWS IoT Greengrass Core 軟體或核心裝置重新啟動的指令碼。這可讓您開發元件，在安裝作業系統更新或執行時間更新後執行重新啟動。 若要安裝不需要 AWS IoT Greengrass Core 軟體或裝置重新啟動的更新或相依性，請使用[安裝生命週期](#install-lifecycle-definition)。 在 AWS IoT Greengrass Core 軟體部署元件的下列情況下，此生命週期步驟會在安裝生命週期步驟之前執行： + 元件第一次部署到核心裝置。 + 元件版本會變更。 + 引導指令碼會隨著元件組態更新而變更。 AWS IoT Greengrass 核心軟體完成部署中具有引導步驟之所有元件的引導步驟後，軟體會重新啟動。 您必須將 AWS IoT Greengrass Core 軟體設定為系統服務，才能重新啟動 AWS IoT Greengrass Core 軟體或核心裝置。如果您未將 AWS IoT Greengrass Core 軟體設定為系統服務，則軟體不會重新啟動。如需詳細資訊，請參閱[將 Greengrass 核設定為系統服務](configure-greengrass-core-v2.md#configure-system-service)。 此物件或字串包含下列資訊： `BootstrapOnRollback` 啟用此功能時， `BootstrapOnRollback`只會針對已完成或嘗試執行引導生命週期步驟的元件執行，做為失敗目標部署的一部分。此功能適用於 Greengrass 核版本 2.12.0 和更新版本。 （選用） 您可以在轉返部署中執行引導生命週期步驟。如果您將此選項設定為 `true`，則會執行復原部署中定義的引導生命週期步驟。部署失敗時，元件引導生命週期的先前版本會在復原部署期間再次執行。 預設為 `false`。 `Script` 要執行的指令碼。此指令碼的結束程式碼定義重新啟動指示。使用下列結束代碼： + `0` – 請勿重新啟動 AWS IoT Greengrass Core 軟體或核心裝置。 AWS IoT Greengrass 核心軟體仍會在所有元件啟動後重新啟動。 + `100` – 請求重新啟動 AWS IoT Greengrass Core 軟體。 + `101` – 請求重新啟動核心裝置。 出口代碼 100 到 199 保留給特殊行為。其他結束代碼代表指令碼錯誤。 `RequiresPrivilege` （選用） 您可以使用根權限執行指令碼。如果您將此選項設定為 `true`，則 AWS IoT Greengrass 核心軟體會執行此生命週期指令碼做為根目錄，而不是您設定為執行此元件的系統使用者。預設為 `false`。 `Timeout` （選用） 在 AWS IoT Greengrass Core 軟體終止程序之前，指令碼可執行的時間上限，以秒為單位。 預設：120 秒 `Setenv` （選用） 要提供給指令碼的環境變數字典。這些環境變數會覆寫您在 中提供的變數`Lifecycle.Setenv`。 `Selections` （選用） 選取索引鍵清單，指定要為此資訊清單執行的[全域生命週期](#global-lifecycle-definition)區段。在全域生命週期中，您可以使用任何層級的選擇索引鍵來定義生命週期步驟，以選取生命週期的子區段。然後，核心裝置會使用符合此資訊清單中選取索引鍵的這些區段。如需詳細資訊，請參閱 [全域生命週期範例](#global-lifecycle-definition)。 只有在此資訊清單未定義生命週期時，核心裝置才會使用全域生命週期中的選擇。 您可以指定`all`選取金鑰，以執行沒有選取金鑰的全域生命週期區段。 `Artifacts` （選用） 物件清單，每個物件都會為此資訊清單定義的平台上的元件定義二進位成品。例如，您可以將程式碼或影像定義為成品。 當元件部署時， AWS IoT Greengrass 核心軟體會將成品下載到核心裝置上的資料夾。您也可以將成品定義為軟體下載後擷取的封存檔案。 您可以使用[配方變數](#recipe-variables)來取得成品安裝在核心裝置上的資料夾路徑。 + 一般檔案 – 使用 [artifacts：path 配方變數](#component-recipe-artifacts-path)來取得包含成品之資料夾的路徑。例如，在配方`{artifacts:path}/my_script.py`中指定 ，以取得具有 URI 的成品路徑`s3://amzn-s3-demo-bucket/path/to/my_script.py`。 + 擷取的封存 – 使用 [artifacts：decompressedPath 配方變數](#component-recipe-artifacts-decompressed-path)來取得包含擷取的封存成品之資料夾的路徑。Core AWS IoT Greengrass 軟體會將每個封存擷取到與封存同名的資料夾。例如，在配方`{artifacts:decompressedPath}/my_archive/my_script.py`中指定 ，以在具有 URI 的封存成品`my_script.py`中取得 的路徑`s3://amzn-s3-demo-bucket/path/to/my_archive.zip`。 當您在本機核心裝置上開發具有封存成品的元件時，您可能沒有該成品的 URI。若要使用擷取成品`Unarchive`的選項測試元件，請指定檔案名稱符合封存成品檔案名稱的 URI。您可以指定預期上傳封存成品的 URI，也可以指定新的預留位置 URI。例如，若要在本機部署期間擷取`my_archive.zip`成品，您可以指定 `s3://amzn-s3-demo-bucket/my_archive.zip`。 每個物件都包含下列資訊： `Uri` S3 儲存貯體中成品的 URI。 AWS IoT Greengrass 核心軟體會在元件安裝時從此 URI 擷取成品，除非成品已存在於裝置上。每個成品在每個資訊清單中都必須具有唯一的檔案名稱。 `Unarchive` （選用） 要解壓縮的封存類型。您可以從以下選項中選擇： + `NONE` – 檔案不是要解壓縮的封存。 AWS IoT Greengrass 核心軟體會將成品安裝到核心裝置上的資料夾。您可以使用 [artifacts：path 配方變數](#component-recipe-artifacts-path)來取得此資料夾的路徑。 + `ZIP` – 檔案是 ZIP 封存檔。Core AWS IoT Greengrass 軟體會將封存擷取到與封存同名的資料夾。您可以使用 [artifacts：decompressedPath 配方變數](#component-recipe-artifacts-decompressed-path)，取得包含此資料夾的資料夾路徑。 預設為 `NONE`。 `Permission` （選用） 定義要為此成品檔案設定的存取許可的物件。您可以設定讀取許可和執行許可。 您無法設定寫入許可，因為 AWS IoT Greengrass Core 軟體不允許元件編輯成品資料夾中的成品檔案。若要編輯元件中的成品檔案，請將其複製到另一個位置，或發佈和部署新的成品檔案。 如果您將成品定義為要解壓縮的封存，則 AWS IoT Greengrass Core 軟體會針對從封存解壓縮的檔案設定這些存取許可。Core AWS IoT Greengrass 軟體會將資料夾的存取許可設定為`ALL`適用於 `Read`和 的 `Execute`。這可讓元件檢視 資料夾中的解壓縮檔案。若要設定封存中個別檔案的許可，您可以在[安裝生命週期指令碼](#install-lifecycle-definition)中設定許可。 此物件包含下列資訊： `Read` （選用） 為此成品檔案設定的讀取許可。若要允許其他元件存取此成品，例如相依於此元件的元件，請指定 `ALL`。您可以從以下選項中選擇： + `NONE` – 檔案無法讀取。 + `OWNER` – 您設定為執行此元件的系統使用者可讀取該檔案。 + `ALL` – 所有使用者都可讀取檔案。 預設為 `OWNER`。 `Execute` （選用） 為此成品檔案設定的執行許可。`Execute` 許可表示 `Read`許可。例如，如果您`ALL`為 指定 `Execute`，則所有使用者都可以讀取和執行此成品檔案。 您可以從以下選項中選擇： + `NONE` – 檔案無法執行。 + `OWNER` – 檔案可由您設定為執行元件的系統使用者執行。 + `ALL` – 所有使用者皆可執行 檔案。 預設為 `NONE`。 `Digest` （唯讀） 成品的密碼編譯摘要雜湊。當您建立元件時， AWS IoT Greengrass 會使用雜湊演算法來計算成品檔案的雜湊。然後，當您部署元件時，Greengrass 核會計算下載成品的雜湊，並將雜湊與此摘要進行比較，以在安裝之前驗證成品。如果雜湊不符合摘要，則部署會失敗。 如果您設定此參數， 會 AWS IoT Greengrass 取代您在建立元件時設定的值。 `Algorithm` （唯讀） AWS IoT Greengrass 用來計算成品摘要雜湊的雜湊演算法。 如果您設定此參數， 會 AWS IoT Greengrass 取代您在建立元件時設定的值。 `Lifecycle` 定義如何安裝和執行元件的物件。只有在要使用的資訊[清單](#manifest-definition)未指定生命週期時，核心裝置才會使用全域生命週期。 您可以在資訊清單之外定義此生命週期。您也可以定義資訊[清單生命週期](#manifest-lifecycle-definition)，套用至符合該資訊清單的平台。 在全域生命週期中，您可以指定針對每個資訊清單中指定的特定[選取索引鍵](#manifest-selections-definition)執行的生命週期。選擇索引鍵是字串，可識別要針對每個資訊清單執行的全域生命週期區段。 `all` 選擇索引鍵是任何沒有選擇索引鍵區段的預設值。這表示您可以在資訊清單中指定`all`選取金鑰，以執行全域生命週期的區段，而無需選取金鑰。您不需要在全域生命週期中指定`all`選取索引鍵。 如果資訊清單未定義生命週期或選取項目索引鍵，核心裝置會預設為使用`all`選取項目。這表示在此情況下，核心裝置會使用未使用選取金鑰的全域生命週期區段。 此物件包含的資訊與[資訊清單生命週期](#manifest-lifecycle-definition)相同，但您可以在任何層級指定選取索引鍵，以選取生命週期的子區段。 我們建議您針對每個選擇索引鍵僅使用小寫字母，以避免選擇索引鍵與生命週期索引鍵之間發生衝突。生命週期金鑰以大寫字母開頭。 **Example 具有最上層選取索引鍵的全域生命週期範例** ``` Lifecycle: key1: install: SkipIf: either onpath executable or exists file Script: command1 key2: install: Script: command2 all: install: Script: command3 ``` **Example 具有底層選取索引鍵的全域生命週期範例** ``` Lifecycle: install: Script: key1: command1 key2: command2 all: command3 ``` **Example 具有多個選擇索引鍵層級的全域生命週期範例** ``` Lifecycle: key1: install: SkipIf: either onpath executable or exists file Script: command1 key2: install: Script: command2 all: install: Script: key3: command3 key4: command4 all: command5 ``` ## 配方變數 配方變數會公開目前元件和核心中的資訊，供您在配方中使用。例如，您可以使用配方變數，將元件組態參數傳遞至您在生命週期指令碼中執行的應用程式。 您可以在元件配方的下列區段中使用配方變數： + 生命週期定義。 + 元件組態定義，如果您使用 [Greengrass 核 v](greengrass-nucleus-component.md)2.6.0 或更新版本，並將 [interpolateComponentConfiguration](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-interpolate-component-configuration) 組態選項設定為 `true`。您也可以在[部署元件組態更新](update-component-configurations.md#merge-configuration-update-recipe-variables)時使用配方變數。 配方變數使用`{recipe_variable}`語法。大括號表示配方變數。 AWS IoT Greengrass 支援下列配方變數： `component_dependency_name:configuration:json_pointer` 此配方定義之元件的組態參數值，或此元件所依賴之元件的組態參數值。 您可以使用此變數，為您在元件生命週期中執行的指令碼提供參數。 AWS IoT Greengrass 僅在元件生命週期定義中支援此配方變數。 此配方變數具有下列輸入： + `component_dependency_name` – （選用） 要查詢的元件相依性名稱。省略此區段以查詢此配方定義的元件。您只能指定直接相依性。 + `json_pointer` – 要評估之組態值的 JSON 指標。JSON 指標以正斜線 開頭`/`。若要識別巢狀元件組態中的值，請使用斜線 (`/`) 來分隔組態中每個層級的索引鍵。您可以使用數字做為索引鍵，在清單中指定索引。如需詳細資訊，請參閱 [JSON 指標規格](https://tools.ietf.org/html/rfc6901)。 AWS IoT Greengrass Core 對 YAML 格式的配方使用 JSON 指標。 JSON 指標可以參考下列節點類型： + value node. AWS IoT Greengrass Core 會將配方變數取代為值的字串表示法。Null 值`null`會轉換為字串。 + 物件節點。 AWS IoT Greengrass Core 會將配方變數取代為該物件的序列化 JSON 字串表示法。 + 無 node. AWS IoT Greengrass Core 不會取代配方變數。 例如，`{configuration:/Message}`配方變數會擷取元件組態中`Message`金鑰的值。`{com.example.MyComponentDependency:configuration:/server/port}` 配方變數會在元件相依性的`server`組態物件`port`中擷取 的值。 `component_dependency_name:artifacts:path` 此配方定義元件的成品根路徑，或此元件所依賴的元件的成品根路徑。 當元件安裝時， 會將元件的成品 AWS IoT Greengrass 複製到此變數公開的資料夾。您可以使用此變數來識別要在元件生命週期中執行的指令碼位置，例如 。 此路徑的資料夾為唯讀。若要修改成品檔案，請將檔案複製到另一個位置，例如目前的工作目錄 (`$PWD` 或 `.`)。然後，修改其中的檔案。 若要從元件相依性讀取或執行成品，該成品的 `Read`或 `Execute`許可必須是 `ALL`。如需詳細資訊，請參閱您在元件配方中定義的[成品許可](#component-artifact-permission)。 此配方變數具有下列輸入： + `component_dependency_name` – （選用） 要查詢的元件相依性名稱。省略此區段以查詢此配方定義的元件。您只能指定直接相依性。 `component_dependency_name:artifacts:decompressedPath` 此配方定義之元件的解壓縮封存成品根路徑，或此元件所依賴之元件的解壓縮封存成品根路徑。 當元件安裝時， 會將元件的封存成品 AWS IoT Greengrass 解壓縮至此變數公開的資料夾。您可以使用此變數來識別要在元件生命週期中執行的指令碼位置，例如 。 每個成品都會解壓縮到解壓縮路徑中的資料夾，其中資料夾的名稱與成品的名稱相同，減去其副檔名。例如，名為 `models.zip` 的 ZIP 成品會解壓縮至 `{artifacts:decompressedPath}/models` 資料夾。 此路徑的資料夾為唯讀。若要修改成品檔案，請將檔案複製到另一個位置，例如目前的工作目錄 (`$PWD` 或 `.`)。然後，修改其中的檔案。 若要從元件相依性讀取或執行成品，該成品的 `Read`或 `Execute`許可必須是 `ALL`。如需詳細資訊，請參閱您在元件配方中定義的[成品許可](#component-artifact-permission)。 此配方變數具有下列輸入： + `component_dependency_name` – （選用） 要查詢的元件相依性名稱。省略此區段以查詢此配方定義的元件。您只能指定直接相依性。 `component_dependency_name:work:path` 此功能適用於 [Greengrass 核元件](greengrass-nucleus-component.md)的 v2.0.4 和更新版本。 此配方定義之元件的工作路徑，或此元件所依賴之元件的工作路徑。此配方變數的值等同於從元件內容執行時`$PWD`環境變數和 [pwd](https://en.wikipedia.org/wiki/Pwd) 命令的輸出。 您可以使用此配方變數，在元件與相依性之間共用檔案。 此路徑的資料夾可由此配方定義的元件以及以相同使用者和群組身分執行的其他元件讀取和寫入。 此配方變數具有下列輸入： + `component_dependency_name` – （選用） 要查詢的元件相依性名稱。省略此區段以查詢此配方定義的元件。您只能指定直接相依性。 `kernel:rootPath` AWS IoT Greengrass 核心根路徑。 `iot:thingName` 此功能適用於 [Greengrass 核元件](greengrass-nucleus-component.md)的 v2.3.0 和更新版本。 核心裝置 AWS IoT 物件的名稱。 ## 配方範例 您可以參考下列配方範例，協助您建立元件的配方。 AWS IoT Greengrass 策劃 Greengrass 元件的索引，稱為 Greengrass 軟體目錄。此目錄會追蹤由 Greengrass 社群開發的 Greengrass 元件。您可以從此目錄中下載、修改和部署元件，以建立 Greengrass 應用程式。如需詳細資訊，請參閱[社群元件](greengrass-software-catalog.md)。 **Topics** + [Hello World 元件配方](#recipe-example-hello-world) + [Python 執行期元件範例](#recipe-example-python-runtime) + [指定數個欄位的元件配方](#recipe-example-all-fields) ### Hello World 元件配方 下列配方說明執行 Python 指令碼的 Hello World 元件。此元件支援所有平台，並接受將 `Message` AWS IoT Greengrass 參數做為引數傳遞至 Python 指令碼。這是[入門教學](getting-started.md)課程中 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}" ``` ------ ### Python 執行期元件範例 下列配方說明安裝 Python 的元件。此元件支援 64 位元 Linux 裝置。 ------ #### [ JSON ] ``` { "RecipeFormatVersion": "2020-01-25", "ComponentName": "com.example.PythonRuntime", "ComponentDescription": "Installs Python 3.7", "ComponentPublisher": "Amazon", "ComponentVersion": "3.7.0", "Manifests": [ { "Platform": { "os": "linux", "architecture": "amd64" }, "Lifecycle": { "install": "apt-get update\napt-get install python3.7" } } ] } ``` ------ #### [ YAML ] ``` --- RecipeFormatVersion: '2020-01-25' ComponentName: com.example.PythonRuntime ComponentDescription: Installs Python 3.7 ComponentPublisher: Amazon ComponentVersion: '3.7.0' Manifests: - Platform: os: linux architecture: amd64 Lifecycle: install: | apt-get update apt-get install python3.7 ``` ------ ### 指定數個欄位的元件配方 下列元件配方使用數個配方欄位。 ------ #### [ JSON ] ``` { "RecipeFormatVersion": "2020-01-25", "ComponentName": "com.example.FooService", "ComponentDescription": "Complete recipe for AWS IoT Greengrass components", "ComponentPublisher": "Amazon", "ComponentVersion": "1.0.0", "ComponentConfiguration": { "DefaultConfiguration": { "TestParam": "TestValue" } }, "ComponentDependencies": { "BarService": { "VersionRequirement": "^1.1.0", "DependencyType": "SOFT" }, "BazService": { "VersionRequirement": "^2.0.0" } }, "Manifests": [ { "Platform": { "os": "linux", "architecture": "amd64" }, "Lifecycle": { "install": { "Skipif": "onpath git", "Script": "sudo apt-get install git" }, "Setenv": { "environment_variable1": "variable_value1", "environment_variable2": "variable_value2" } }, "Artifacts": [ { "Uri": "s3://amzn-s3-demo-bucket/hello_world.zip", "Unarchive": "ZIP" }, { "Uri": "s3://amzn-s3-demo-bucket/hello_world_linux.py" } ] }, { "Lifecycle": { "install": { "Skipif": "onpath git", "Script": "sudo apt-get install git", "RequiresPrivilege": "true" } }, "Artifacts": [ { "Uri": "s3://amzn-s3-demo-bucket/hello_world.py" } ] } ] } ``` ------ #### [ YAML ] ``` --- RecipeFormatVersion: '2020-01-25' ComponentName: com.example.FooService ComponentDescription: Complete recipe for AWS IoT Greengrass components ComponentPublisher: Amazon ComponentVersion: 1.0.0 ComponentConfiguration: DefaultConfiguration: TestParam: TestValue ComponentDependencies: BarService: VersionRequirement: ^1.1.0 DependencyType: SOFT BazService: VersionRequirement: ^2.0.0 Manifests: - Platform: os: linux architecture: amd64 Lifecycle: install: SkipIf: onpath git Script: sudo apt-get install git SetEnv: environment_variable1: variable_value1 environment_variable2: variable_value2 Artifacts: - Uri: 's3://amzn-s3-demo-bucket/hello_world.zip' Unarchive: ZIP - Uri: 's3://amzn-s3-demo-bucket/hello_world_linux.py' - Lifecycle: install: SkipIf: onpath git Script: sudo apt-get install git RequiresPrivilege: 'true' Artifacts: - Uri: 's3://amzn-s3-demo-bucket/hello_world.py' ``` ------ # 元件環境變數參考 AWS IoT Greengrass 核心軟體會在執行元件的生命週期指令碼時設定環境變數。您可以在元件中取得這些環境變數，以取得物件名稱 AWS 區域和 Greengrass 核版本。軟體也會設定您的元件使用[程序間通訊 SDK](interprocess-communication.md) 和 [與 AWS 服務互動](interact-with-aws-services.md)所需的環境變數。 您也可以為元件的生命週期指令碼設定自訂環境變數。如需詳細資訊，請參閱 [Setenv](component-recipe-reference.md#lifecycle-setenv-definition)。 Core AWS IoT Greengrass 軟體會設定下列環境變數： `AWS_IOT_THING_NAME` 代表此 Greengrass 核心裝置的 AWS IoT 物件名稱。 `AWS_REGION` 此 Greengrass 核心裝置運作 AWS 區域 所在的 。 AWS SDKs 使用此環境變數來識別要使用的預設區域。此變數等同於 `AWS_DEFAULT_REGION`。 `AWS_DEFAULT_REGION` 此 Greengrass 核心裝置運作 AWS 區域 所在的 。 AWS CLI 使用此環境變數來識別要使用的預設區域。此變數等同於 `AWS_REGION`。 `GGC_VERSION` 在此 [Greengrass 核心裝置上執行的 Greengrass 核元件](greengrass-nucleus-component.md)版本。 `GG_ROOT_CA_PATH` 此功能適用於 [Greengrass 核元件](greengrass-nucleus-component.md)的 v2.5.5 和更新版本。 Greengrass 核使用的根憑證授權機構 (CA) 憑證路徑。 `AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT` 元件用來與 AWS IoT Greengrass Core 軟體通訊的 IPC 通訊端路徑。如需詳細資訊，請參閱[使用 AWS IoT Device SDK 與 Greengrass 核、其他元件和 通訊 AWS IoT Core與 Greengrass 核、其他元件和 通訊 AWS IoT Core](interprocess-communication.md)。 `SVCUID` 元件用來連線至 IPC 通訊端並與 AWS IoT Greengrass Core 軟體通訊的秘密字符。如需詳細資訊，請參閱[使用 AWS IoT Device SDK 與 Greengrass 核、其他元件和 通訊 AWS IoT Core與 Greengrass 核、其他元件和 通訊 AWS IoT Core](interprocess-communication.md)。 `AWS_CONTAINER_AUTHORIZATION_TOKEN` 元件用來從字符[交換服務元件擷取憑證的秘密字符](token-exchange-service-component.md)。 `AWS_CONTAINER_CREDENTIALS_FULL_URI` 元件請求從[字符交換服務元件](token-exchange-service-component.md)擷取憑證的 URI。