AWS IoT Greengrass 元件配方參考 - AWS IoT Greengrass
配方驗證食譜格式配方變數食譜示例

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

AWS IoT Greengrass 元件配方參考

元件方案是定義元件詳細資訊、相依性、人工因素和生命週期的檔案。例如，元件生命週期會指定要執行以安裝、執行和關閉元件的命令。 AWS IoT Greengrass 核心會使用您在方案中定義的生命週期來安裝和執行元件。當您部署元件時， AWS IoT Greengrass 服務會使用方案來識別要部署到核心裝置的相依性和成品。

在方案中，您可以為元件支援的每個平台定義唯一的相依性和生命週期。您可以使用此功能將元件部署到具有不同需求的多個平台的裝置。您也可以使用此功能 AWS IoT Greengrass 來防止在不支援元件的裝置上安裝元件。

每個配方都包含清單列表。每個資訊清單都會指定一組平台需求，以及用於平台符合這些需求的核心裝置的生命週期和成品。核心設備使用具有設備滿足的平台要求的第一個清單。指定沒有任何平台需求的清單以匹配任何核心設備。

您也可以指定不在資訊清單中的全域生命週期。在全域生命週期中，您可以使用選取鍵來識別生命週期的子區段。然後，您可以在資訊清單中指定這些選取鍵，除了資訊清單的生命週期之外，還可以使用全域生命週期的這些區段。僅當清單未定義生命週期時，核心設備才使用清單的選擇鍵。您可以使用資訊清單中的all選取項來比對全域生命週期的區段，而不需要選取索引鍵。

AWS IoT Greengrass 核心軟體選取符合核心裝置的資訊清單之後，會執行下列動作來識別要使用的生命週期步驟：

  • 如果選取的資訊清單定義了生命週期，則核心裝置會使用該生命週期。

  • 如果選取的資訊清單未定義生命週期，則核心裝置會使用全域生命週期。核心裝置會執行下列動作，以識別要使用的全域生命週期中的哪些區段：

    • 如果清單定義了選擇鍵，則核心設備將使用包含清單選擇鍵的全局生命週期的部分。

    • 如果資訊清單未定義選取金鑰，核心裝置會使用沒有選取金鑰的全域生命週期區段。此行為等同於定義all選取範圍的資訊清單。

重要

核心裝置必須符合至少一個資訊清單的平台需求，才能安裝元件。如果沒有資訊清單符合核心裝置，則 AWS IoT Greengrass Core 軟體不會安裝元件，且部署失敗。

您可以定義JSON或YAML格式化配方。食譜示例部分包括每種格式的食譜。

配方驗證

Greengrass 會在建立元件版本時驗證JSON或YAML元件方案。此方案驗證會檢查您JSON或YAML元件的配方是否有常見錯誤，以避免潛在的部署問題。驗證會檢查配方是否有常見錯誤 (例如，缺少逗號、大括號和欄位)，並確保配方格式正確。

如果您收到配方驗證錯誤訊息，請檢查您的方案是否有遺漏逗號、大括號或欄位。通過查看配方格式來確認您沒有缺少任何字段。

食譜格式

當您定義元件的方案時，您可以在 recipe 文件中指定下列資訊。相同的結構適用於YAML和JSON格式的配方。

RecipeFormatVersion

該配方的模板版本。選擇下列選項：

  • 2020-01-25

ComponentName

此方案定義的元件名稱。您在每個區域中的 AWS 帳戶 元件名稱必須是唯一的。

提示

  • 使用反向域名格式來避免公司內的名稱衝突。例如，如果您的公司擁有example.com並且您從事太陽能專案，您可以為 Hello World 元件命名com.example.solar.HelloWorld。這有助於避免公司內部的元件名稱衝突。

  • 避免在組件名稱中使用aws.greengrass前綴。 AWS IoT Greengrass 將此前綴用於其提供的公共組件。如果您選擇與公共組件相同的名稱，則組件將替換該組件。然後，當它部署具有依賴於該公共組件的組件時， AWS IoT Greengrass 提供您的組件而不是公共組件。此功能可讓您覆寫公用元件的行為，但如果您不打算覆寫公用元件，它也可能會中斷其他元件。

ComponentVersion

元件的版本。主要、次要和修正程式值的最大值為 999999。

注意

AWS IoT Greengrass 使用語義版本的組件。語義版本遵循一個主要的。 未成年人。 修補程式編號系統。例如，版本1.0.0代表元件的第一個主要發行版本。如需詳細資訊，請參閱語意版本規格。

ComponentDescription

(選擇性) 元件的說明。

ComponentPublisher

元件的發行者或作者。

ComponentConfiguration

(選擇性) 定義元件組態或參數的物件。您可以定義預設組態，然後在部署元件時，指定要提供給元件的組態物件。元件組態支援巢狀參數和結構。此物件包含下列資訊：

DefaultConfiguration

定義元件預設組態的物件。您可以定義此物件的結構。

注意

AWS IoT Greengrass 用JSON於組態值。JSON指定數字類型，但不區分整數和浮點數。因此，組態值可能會轉換為中 AWS IoT Greengrass的浮點數。若要確保您的元件使用正確的資料類型，建議您將數值組態值定義為字串。然後，讓你的組件將它們解析為整數或浮點數。這可確保您的組態值在組態和核心裝置上具有相同的類型。

ComponentDependencies

(選擇性) 物件字典，每個物件都會定義元件的元件相依性。每個物件的索引鍵會識別元件相依性的名稱。 AWS IoT Greengrass 安裝元件時會安裝元件相依性。 AWS IoT Greengrass 等待依賴關係在啟動組件之前啟動。每個物件都包含下列資訊：

VersionRequirement

npm-style 語意版本約束，用於定義此相依性的相容元件版本。您可以指定版本或版本範圍。如需詳細資訊，請參閱 npm 語意版本計算器。

DependencyType

(選擇性) 此相依性的類型。您可以從以下選項中選擇。

  • SOFT - 在相依性變更狀態時，元件不會重新啟動。

  • HARD - 在相依性變更狀態時，元件會重新啟動。

預設為 HARD。

ComponentType

(選擇性) 元件的類型。

注意

我們不建議您在方案中指定元件類型。 AWS IoT Greengrass 在建立元件時為您設定類型。

該類型可以是以下類型之一：

  • aws.greengrass.generic— 元件會執行命令或提供加工品。

  • aws.greengrass.lambda— 元件使用 Lambda 啟動器元件執行 Lambda 函數。此ComponentSource參數會指定此元件執行ARN的 Lambda 函數。

    我們不建議您使用此選項，因為它是在您從 Lambda 函數建立元件 AWS IoT Greengrass 時設定的。如需詳細資訊，請參閱執行AWS Lambda函數。

  • aws.greengrass.plugin— 元件在與 Greengrass 核相同的 Java 虛擬機器 (JVM) 中執行。如果您部署或重新啟動外掛程式元件，Greengrass 核心會重新啟動。

    插件組件使用與 Greengrass 核相同的日誌文件。如需詳細資訊，請參閱監控AWS IoT Greengrass日誌。

    我們不建議您在組件配方中使用此選項，因為它適用於使用 Java 編寫且直接與 Greengrass 核心連接的 AWS提供組件。如需有關哪些公用元件是外掛程式的詳細資訊，請參閱AWS-提供的組件。

  • aws.greengrass.nucleus— 細胞核成分. 如需詳細資訊，請參閱Greengrass 核。

    我們不建議您在組件配方中使用此選項。它適用於 Greengrass 核組件，它提供了核心軟件的最小功能。 AWS IoT Greengrass

aws.greengrass.generic當您從配方建立元件，或從 Lambda 函數建立元件aws.greengrass.lambda時，預設為。

如需詳細資訊，請參閱元件類型。

ComponentSource

(選用) 元件執行ARN的 Lambda 函數。

我們不建議您在方案中指定元件來源。 AWS IoT Greengrass 當您從 Lambda 函數建立元件時，會為您設定此參數。如需詳細資訊，請參閱執行AWS Lambda函數。

Manifests

物件清單，每個物件都會定義元件的生命週期、參數和平台需求。如果核心裝置符合多個資訊清單的平台需求，請 AWS IoT Greengrass 使用核心裝置符合的第一個資訊清單。若要確保核心裝置使用正確的資訊清單，請先定義具有更嚴格平台需求的資訊清單。適用於所有平台的資訊清單必須是清單中的最後一個資訊清單。

重要

核心裝置必須符合至少一個資訊清單的平台需求，才能安裝元件。如果沒有資訊清單符合核心裝置，則 AWS IoT Greengrass Core 軟體不會安裝元件，且部署失敗。

每個物件都包含下列資訊：

Name

(選擇性) 此資訊清單定義之平台的易記名稱。

如果您省略此參數，請從平台os和 AWS IoT Greengrass 建立名稱architecture。

Platform

(選擇性) 定義套用此資訊清單之平台的物件。省略此參數，以定義適用於所有平台的資訊清單。

此物件會指定有關核心裝置執行之平台的索引鍵值配對。當您部署此元件時， AWS IoT Greengrass Core 軟體會比較這些索引鍵值配對與核心裝置上的平台屬性。 AWS IoT Greengrass Core 軟件始終定義os和architecture，並且它可能會定義其他屬性。您可以在部署 Greengrass 核心元件時指定核心裝置的自訂平台屬性。如需詳細資訊，請參閱 Greengrass 核心元件的平台覆寫參數。

對於每個鍵值對，您可以指定下列其中一個值：

  • 精確的值，例如linux或windows。精確值必須以字母或數字開頭。

  • *，其符合任何值。當一個值不存在時，這也匹配。

  • Java 樣式的規則運算式，例如. /windows|linux/ 規則運算式必須以斜線字元 (/) 開頭和結尾。例如，規則運算式會/.+/比對任何非空白值。

此物件包含下列資訊：

os

(選擇性) 此資訊清單支援之平台的作業系統名稱。一般平台包含下列值：

  • linux

  • windows

  • darwin (macOS)

architecture

(選擇性) 此資訊清單支援之平台的處理器架構。通用架構包括以下值：

  • amd64

  • arm

  • aarch64

  • x86

architecture.detail

(選擇性) 此資訊清單支援之平台的處理器架構詳細資料。一般架構詳細資料包括下列值：

  • arm61

  • arm71

  • arm81

key

(選擇性) 您為此資訊清單定義的平台屬性。Replace (取代) key 與平台屬性的名稱。 AWS IoT Greengrass 核心軟體會將此平台屬性與您在 Greengrass 核心元件組態中指定的索引鍵值配對相符。如需詳細資訊，請參閱 Greengrass 核心元件的平台覆寫參數。

提示

使用反向域名格式來避免公司內的名稱衝突。例如，如果您的公司擁有example.com並且您在某個無線電專案上工作，您可以命名自訂平台屬性com.example.radio.RadioModule。這有助於避免公司內的平台屬性名稱衝突。

例如，您可以定義 platform 屬性com.example.radio.RadioModule，以根據核心裝置上可用的無線電模組來指定不同的資訊清單。每個資訊清單可以包含套用至不同硬體組態的不同成品，因此您可以將最小的軟體組合部署到核心裝置。

Lifecycle

定義如何在此資訊清單定義的平台上安裝及執行元件的物件或字串。您也可以定義適用於所有平台的全域生命週期。只有當要使用的資訊清單未指定生命週期時，核心裝置才會使用全域生命週期。

注意

您可以在資訊清單中定義此生命週期。您在此處指定的生命週期步驟僅適用於此資訊清單定義的平台。您也可以定義適用於所有平台的全域生命週期。

此物件或字串包含下列資訊：

Setenv

(選擇性) 提供給所有生命週期指令碼的環境變數字典。您可以Setenv在每個生命週期指令碼中覆寫這些環境變數。

install

(選擇性) 定義元件安裝時要執行之指令碼的物件或字串。 AWS IoT Greengrass 核心軟體也會在每次軟體啟動時執行此生命週期步驟。

如果指install令碼以成功碼結束，元件就會進入INSTALLED狀態。

此物件或字串包含下列資訊：

Script

要執行的指令碼。

RequiresPrivilege

(選擇性) 您可以使用 root 權限執行命令檔。如果您將此選項設定為true，則 AWS IoT Greengrass Core 軟體會以 root 身分執行此生命週期指令碼，而不是以您設定來執行此元件的系統使用者身分執行此生命週期指令碼。預設為 false。

Skipif

(選擇性) 決定是否要執行指令碼的檢查。您可以定義檢查可執行文件是否在路徑上或文件是否存在。如果輸出為 true，則 AWS IoT Greengrass 核心軟體會略過該步驟。選擇下列其中一項檢查：

  • 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

(選擇性) 您可以使用 root 權限執行命令檔。如果您將此選項設定為true，則 AWS IoT Greengrass Core 軟體會以 root 身分執行此生命週期指令碼，而不是以您設定來執行此元件的系統使用者身分執行此生命週期指令碼。預設為 false。

Skipif

(選擇性) 決定是否要執行指令碼的檢查。您可以定義檢查可執行文件是否在路徑上或文件是否存在。如果輸出為 true，則 AWS IoT Greengrass 核心軟體會略過該步驟。選擇下列其中一項檢查：

  • 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才能啟動相依元件。使用此UpdateStateIPC作業將組件的狀態設定為RUNNING或ERRORED當組件啟動未結束的指令碼時。例如，您可以定義啟動「我的SQL程序」的startup步驟/etc/init.d/mysqld start。

執行此生命週期步驟時，元件會進入STARTING狀態。如果指startup令碼以成功碼結束，元件就會進入RUNNING狀態。然後，從屬元件即可啟動。

當您部署具有startup生命週期的元件時，核心裝置可以在此生命週期指令碼結束或報告其狀態之後，將部署報告為完成。換句話說，部署的狀態是IN_PROGRESS直到所有元件的啟動指令碼結束或報告狀態為止。

注意

您只能定義一個startup或run生命週期。

此物件或字串包含下列資訊：

Script

要執行的指令碼。

RequiresPrivilege

(選擇性) 您可以使用 root 權限執行命令檔。如果您將此選項設定為true，則 AWS IoT Greengrass Core 軟體會以 root 身分執行此生命週期指令碼，而不是以您設定來執行此元件的系統使用者身分執行此生命週期指令碼。預設為 false。

Skipif

(選擇性) 決定是否要執行指令碼的檢查。您可以定義檢查可執行文件是否在路徑上或文件是否存在。如果輸出為 true，則 AWS IoT Greengrass 核心軟體會略過該步驟。選擇下列其中一項檢查：

  • 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步驟在元件關閉時停止該程序。例如，您可以定義停止「我的」SQL 程序的shutdown步驟/etc/init.d/mysqld stop。

指shutdown令碼會在元件進入STOPPING狀態後執行。如果指令碼順利完成，元件就會進入FINISHED狀態。

此物件或字串包含下列資訊：

Script

要執行的指令碼。

RequiresPrivilege

(選擇性) 您可以使用 root 權限執行命令檔。如果您將此選項設定為true，則 AWS IoT Greengrass Core 軟體會以 root 身分執行此生命週期指令碼，而不是以您設定來執行此元件的系統使用者身分執行此生命週期指令碼。預設為 false。

Skipif

(選擇性) 決定是否要執行指令碼的檢查。您可以定義檢查可執行文件是否在路徑上或文件是否存在。如果輸出為 true，則 AWS IoT Greengrass 核心軟體會略過該步驟。選擇下列其中一項檢查：

  • 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

(選擇性) 您可以使用 root 權限執行命令檔。如果您將此選項設定為true，則 AWS IoT Greengrass Core 軟體會以 root 身分執行此生命週期指令碼，而不是以您設定來執行此元件的系統使用者身分執行此生命週期指令碼。預設為 false。

Skipif

(選擇性) 決定是否要執行指令碼的檢查。您可以定義檢查可執行文件是否在路徑上或文件是否存在。如果輸出為 true，則 AWS IoT Greengrass 核心軟體會略過該步驟。選擇下列其中一項檢查：

  • 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 核心軟體或核心裝置重新啟動的指令碼的物件或字串。例如，這可讓您開發元件，在安裝作業系統更新或執行階段更新後執行重新啟動。

注意

若要安裝不需要 AWS IoT Greengrass 核心軟體或裝置重新啟動的更新或相依性，請使用安裝生命週期。

此生命週期步驟會在安裝生命週期步驟之前執行，在下列情況下， AWS IoT Greengrass 核心軟體部署元件時：

  • 元件會首次部署至核心裝置。

  • 元件版本會變更。

  • 啟動程序指令碼會隨著元件組態更新而變更。

在 AWS IoT Greengrass 核心軟體完成部署中具有啟動程序步驟之所有元件的啟動程序步驟之後，軟體便會重新啟動。

重要

您必須將 AWS IoT Greengrass Core 軟體設定為系統服務，才能重新啟動 AWS IoT Greengrass Core 軟體或核心裝置。如果您未將 AWS IoT Greengrass Core 軟體設定為系統服務，軟體就不會重新啟動。如需詳細資訊，請參閱將 Greengrass 核配置為系統服務。

此物件或字串包含下列資訊：

BootstrapOnRollback
注意

啟用此功能時，只BootstrapOnRollback會針對已完成或嘗試執行啟動程序生命週期步驟作為失敗目標部署的一部分的元件執行。此功能適用於 Greengrass 2.12.0 及更高版本。

(選擇性) 您可以執行啟動程序生命週期步驟，做為復原部署的一部分。如果將此選項設定為true，則會執行倒回部署中定義的啟動程序生命週期步驟。當部署失敗時，先前版本的元件啟動程序生命週期將在復原部署期間再次執行。

預設為 false。

Script

要執行的指令碼。這個腳本的退出代碼定義了 restart 指令。使用以下退出代碼：

  • 0— 不要重新啟動 AWS IoT Greengrass Core 軟件或核心設備。 AWS IoT Greengrass 核心軟件在所有組件引導後仍然重新啟動。

  • 100— 要求重新啟動 AWS IoT Greengrass 核心軟體。

  • 101— 請求重新啟動核心設備。

結束代碼 100 到 199 會保留用於特殊行為。其他結束代碼代表指令碼錯誤。

RequiresPrivilege

(選擇性) 您可以使用 root 權限執行命令檔。如果您將此選項設定為true，則 AWS IoT Greengrass Core 軟體會以 root 身分執行此生命週期指令碼，而不是以您設定來執行此元件的系統使用者身分執行此生命週期指令碼。預設為 false。

Timeout

(選擇性) 在 AWS IoT Greengrass Core 軟體終止處理程序之前，指令碼可以執行的時間上限 (以秒為單位)。

預設值：120 秒

Setenv

(選擇性) 要提供給指令集的環境變數字典。這些環境變數會覆寫您在中提供的變數Lifecycle.Setenv。

Selections

(選擇性) 選取索引鍵清單，指定要針對此資訊清單執行的全域生命週期區段。在全域生命週期中，您可以使用任何層級的選取鍵來定義生命週期步驟，以選取生命週期的子區段。然後，核心設備使用與此清單中的選擇鍵匹配的那些部分。如需詳細資訊，請參閱全域生命週期範例。

重要

只有在此資訊清單未定義生命週期時，核心裝置才會使用全域生命週期中的選取項目。

您可以指定all選取鍵來執行沒有選取鍵的全域生命週期區段。

Artifacts

(選擇性) 物件清單，每個物件都會定義此資訊清單所定義之平台上元件的二進位成品。例如，您可以將程式碼或影像定義為人工因素。

部署元件時， AWS IoT Greengrass 核心軟體會將成品下載至核心裝置上的資料夾。您也可以將人工因素定義為軟體下載後擷取的封存檔案。

您可以使用 recipe 變數取得成品安裝在核心裝置上的資料夾路徑。

  • 一般檔案 — 使用人工因素:path recipe 變數取得包含成品之資料夾的路徑。例如，{artifacts:path}/my_script.py在方案中指定以取得具有 URIs3://amzn-s3-demo-bucket/path/to/my_script.py.

  • 擷取的存檔 — 使用成品:decompressedPath recipe 變數取得包含已解壓縮歸檔加工品之資料夾的路徑。 AWS IoT Greengrass 核心軟體會將每個歸檔解壓縮到與歸檔名稱相同的資料夾中。例如，{artifacts:decompressedPath}/my_archive/my_script.py在方案中指定要my_script.py在具有 URIs3://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 核心軟體會將成品安裝至核心裝置上的資料夾。您可以使用人工因素:path recipe 變數來取得此資料夾的路徑。

  • ZIP— 該文件是ZIP存檔。 AWS IoT Greengrass 核心軟件將歸檔解壓縮到與歸檔名稱相同的文件夾中。您可以使用成品:decompressedPath recipe 變數來取得包含此資料夾之資料夾的路徑。

預設為 NONE。

Permission

(選擇性) 定義要為此成品檔案設定之存取權限的物件。您可以設定讀取權限和執行權限。

注意

您無法設定寫入權限，因為 AWS IoT Greengrass Core 軟體不允許元件編輯成品資料夾中的成品檔案。若要編輯元件中的人工因素檔案，請將其複製到其他位置，或發佈並部署新的人工因素檔案。

如果您將人工因素定義為要解壓縮的歸檔，則 AWS IoT Greengrass Core 軟體會對其從歸檔解壓縮的檔案設定這些存取權限。 AWS IoT Greengrass 核心軟體會將資料夾的存取權限設定ALL為Read和Execute。這允許組件查看文件夾中解壓縮的文件。若要設定封存中個別檔案的權限，您可以在安裝生命週期指令碼中設定權限。

此物件包含下列資訊：

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

定義如何安裝和執行元件的物件。只有當要使用的資訊清單未指定生命週期時，核心裝置才會使用全域生命週期。

注意

您可以在資訊清單外定義此生命週期。您也可以定義適用於符合該資訊清單的平台的資訊清單生命週期。

在全域生命週期中，您可以指定針對在每個資訊清單中指定的特定選取鍵執行的生命週期。選取索引鍵是字串，可識別要針對每個資訊清單執行的全域生命週期區段。

all選取鍵是沒有選取鍵的任何區段上的預設值。這表示您可以在資訊清單中指定all選取鍵，以執行全域生命週期的區段，而不需要選取索引鍵。您不需要在全域生命週期中指定all選取鍵。

如果清單未定義生命週期或選擇鍵，則核心設備默認使用該all選擇。這表示在這種情況下，核心裝置會使用不使用選取金鑰的全域生命週期區段。

此物件包含與資訊清單生命週期相同的資訊，但您可以在任何層級指定選取鍵來選取生命週期的子區段。

提示

建議您對每個選取鍵僅使用小寫字母，以避免選取鍵與生命週期金鑰之間發生衝突。生命週期金鑰以大寫字母開頭。

範例 具有最上層選取鍵的全域生命週期
Lifecycle:
  key1:
    install:
      Skipif: either onpath executable or exists file
      Script: command1
  key2:
    install:
      Script: command2
  all:
    install:
      Script: command3
範例 具有底層選取鍵的全域生命週期範例
Lifecycle:
  install:
    Script:
      key1: command1
      key2: command2
      all: command3
範例 具有多個選取鍵層級的全域生命週期範例
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

配方變數

配方變數會公開來自目前元件和原子核的資訊，供您在食譜中使用。例如，您可以使用 recipe 變數，將元件組態參數傳遞至您在生命週期指令碼中執行的應用程式。

您可以在組件配方的以下部分中使用 recipe 變量：

配方變量使用{recipe_variable}語法。大括號表示方法變數。

AWS IoT Greengrass 支援下列配方變數：

component_dependency_name:configuration:json_pointer

此方案所定義之元件的組態參數值，或此元件相依之元件的組態參數值。

您可以使用此變數，為在元件生命週期中執行的指令碼提供參數。

注意

AWS IoT Greengrass 僅在元件生命週期定義中支援此 recipe 變數。

此 recipe 變數具有下列輸入：

  • component_dependency_name— (選擇性) 要查詢的元件相依性名稱。省略此區段，即可查詢此方案定義的元件。您只能指定直接相依性。

  • json_pointer— JSON 指向要評估的模型組態值的指標。JSON指針以正斜線開始/。要識別巢狀零組件模型組態中的值，請使用正斜線 (/) 來分隔模型組態中每個層級的關鍵字。您可以使用數字作為鍵來指定列表中的索引。如需詳細資訊，請參閱JSON指標規格。

    AWS IoT Greengrass 核心使用JSON指針的YAML格式配方。

指JSON針可以引用以下節點類型：

  • 值節點。 AWS IoT Greengrass 核心替換配方變量與值的字符串表示。Null 值會轉換null為字串。

  • 物件節點。 AWS IoT Greengrass 核心用該對象的序列化JSON字符串表示替換 recipe 變量。

  • 沒有節點。 AWS IoT Greengrass 核心不會取代配方變數。

例如，{configuration:/Message}recipe 變數會擷取元件組態中的索Message引鍵值。{com.example.MyComponentDependency:configuration:/server/port}recipe 變數會擷取元件相依性port之server組態物件中的值。

component_dependency_name:artifacts:path

此方案所定義之元件的成品根路徑，或此元件相依之元件的根路徑。

安裝元件時，會將元件的成品 AWS IoT Greengrass 複製到此變數公開的資料夾中。例如，您可以使用此變數來識別要在元件生命週期中執行的指令碼位置。

此路徑上的資料夾是唯讀的。若要修改人工因素檔案，請將檔案複製到其他位置，例如目前工作目錄 ($PWD或.)。然後，在那裡修改文件。

若要從元件相依性讀取或執行成品，該成品Read或Execute權限必須為ALL。如需詳細資訊，請參閱您在元件方案中定義的成品權限。

此 recipe 變數具有下列輸入：

  • component_dependency_name— (選擇性) 要查詢的元件相依性名稱。省略此區段，即可查詢此方案定義的元件。您只能指定直接相依性。

component_dependency_name:artifacts:decompressedPath

此方案定義之元件或此元件相依之元件的解壓縮歸檔人工因素的根路徑。

安裝元件時，將元 AWS IoT Greengrass 件的封存加工品解壓至此變數公開的資料夾。例如，您可以使用此變數來識別要在元件生命週期中執行的指令碼位置。

每個成品都會解壓縮至解壓縮路徑內的資料夾，其中資料夾的名稱與成品相同，減去其副檔名。例如，名為的ZIP成品會models.zip解壓縮至{artifacts:decompressedPath}/models資料夾。

此路徑上的資料夾是唯讀的。若要修改人工因素檔案，請將檔案複製到其他位置，例如目前工作目錄 ($PWD或.)。然後，在那裡修改文件。

若要從元件相依性讀取或執行成品，該成品Read或Execute權限必須為ALL。如需詳細資訊，請參閱您在元件方案中定義的成品權限。

此 recipe 變數具有下列輸入：

  • component_dependency_name— (選擇性) 要查詢的元件相依性名稱。省略此區段，即可查詢此方案定義的元件。您只能指定直接相依性。

component_dependency_name:work:path

此功能適用於 v2.0.4 及更高版 Greeng rass 核組件。

此方案所定義之元件的工作路徑，或此元件相依之元件的工作路徑。此 recipe 變數的值等同於從元件內容執行時的$PWD環境變數和 pwd 命令的輸出。

您可以使用此 recipe 變數在元件和相依性之間共用檔案。

此路徑上的資料夾可由此配方定義的元件以及以相同使用者和群組身分執行的其他元件讀取和寫入。

此 recipe 變數具有下列輸入：

  • component_dependency_name— (選擇性) 要查詢的元件相依性名稱。省略此區段，即可查詢此方案定義的元件。您只能指定直接相依性。

kernel:rootPath

AWS IoT Greengrass 核心根路徑。

iot:thingName

此功能適用於 v2.3.0 及更高版 Greeng rass 核組件。

核心裝置的名稱。 AWS IoT

食譜示例

您可以參考下列配方範例，以協助您建立元件的配方。

AWS IoT Greengrass 策劃 Greengrass 組件的索引，稱為 Greengrass 軟件目錄。此目錄追蹤 Greengrass 社群所開發的 Greengrass 元件。您可以從此目錄下載、修改和部署元件，以建立 Greengrass 應用程式。如需詳細資訊，請參閱社群元件。

你好世界組件食譜

下列配方說明執行 Python 指令碼的「你好世界」元件。此元件支援所有平台，並接受作為引Message數 AWS IoT Greengrass 傳遞給 Python 指令碼的參數。這是在入門教程中 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'