本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 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' ``` ------