Amazon IoT Greengrass组件配方参考 - Amazon IoT Greengrass
食谱验证食谱格式食谱变量食谱示例
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

Amazon IoT Greengrass组件配方参考

组件配方是一个定义组件的详细信息、依赖关系、工件和生命周期的文件。例如，组件生命周期指定要运行的安装、运行和关闭组件的命令。内Amazon IoT Greengrass核使用您在配方中定义的生命周期来安装和运行组件。部署组件时，该Amazon IoT Greengrass服务使用配方来识别要部署到核心设备的依赖项和工件。

在配方中，您可以为组件支持的每个平台定义唯一的依赖关系和生命周期。您可以使用此功能将组件部署到具有不同要求的多个平台的设备上。您还可以使用它来Amazon IoT Greengrass防止在不支持组件的设备上安装该组件。

每个食谱都包含一份清单清单。每个清单都指定了一组平台要求以及平台满足这些要求的核心设备要使用的生命周期和工件。核心设备使用第一份清单，其中包含该设备满足的平台要求。指定没有任何平台要求的清单，以匹配任何核心设备。

您还可以指定清单中没有的全局生命周期。在全球生命周期中，您可以使用选择键来标识生命周期的子部分。然后，您可以在清单中指定这些选择密钥，以便在清单的生命周期之外使用全局生命周期中的这些部分。仅当清单未定义生命周期时，核心设备才会使用清单的选择密钥。您可以使用清单中的all选择来匹配全局生命周期的各个部分，而无需选择键。

在Amazon IoT Greengrass核心软件选择与核心设备匹配的清单后，它会执行以下操作来确定要使用的生命周期步骤：

  • 如果所选清单定义了生命周期，则核心设备将使用该生命周期。

  • 如果所选清单未定义生命周期，则核心设备将使用全局生命周期。核心设备执行以下操作来确定要使用全球生命周期的哪些部分：

    • 如果清单定义了选择密钥，则核心设备将使用全局生命周期中包含清单选择密钥的部分。

    • 如果清单未定义选择密钥，则核心设备将使用全局生命周期中没有选择密钥的部分。此行为等同于定义all选择内容的清单。

重要

核心设备必须满足至少一个清单的平台要求才能安装该组件。如果没有清单与核心设备匹配，则Amazon IoT Greengrass核心软件不会安装该组件，部署将失败。

你可以用 JSON 或 YAML 格式定义配方。食谱示例部分包括每种格式的食谱。

食谱验证

Greengrass 在创建组件版本时会验证 JSON 或 YAML 组件配方。此配方验证会检查您的 JSON 或 YAML 组件配方中是否存在常见错误，以防止出现潜在的部署问题。验证会检查配方中是否存在常见错误（例如，缺少逗号、大括号和字段），并确保配方格式正确。

如果您收到食谱验证错误消息，请检查您的食谱中是否有任何缺少逗号、大括号或字段。查看食谱格式，确认您没有遗漏任何字段。

食谱格式

在为组件定义配方时，需要在配方文档中指定以下信息。同样的结构适用于 YAML 和 JSON 格式的配方。

RecipeFormatVersion

食谱的模板版本。选择以下选项：

  • 2020-01-25

ComponentName

此配方定义的组件的名称。在每个区域中，组件名称必须是唯一的Amazon Web Services 账户。

提示

  • 使用反向域名格式以避免公司内部的域名冲突。例如，如果您的公司拥有一个太阳能项目，example.com并且您从事该项目，则可以命名您的 Hello World 组件com.example.solar.HelloWorld。这有助于避免公司内部的组件名称冲突。

  • 避免在组件名称中使用aws.greengrass前缀。 Amazon IoT Greengrass将此前缀用于它提供的公共组件。如果您选择与公共组件相同的名称，则您的组件将替换该组件。然后，在部署依赖于该公共组件的组件时，Amazon IoT Greengrass提供您的组件而不是公共组件。此功能使您可以覆盖公共组件的行为，但如果您不打算覆盖公共组件，它也可能会破坏其他组件。

ComponentVersion

组件版本。主要、次要和补丁值的最大值为 999999。

注意

Amazon IoT Greengrass使用组件的语义版本。语义版本遵循 major.minor.patch 编号系统。例如，版本1.0.0表示组件的第一个主要版本。有关更多信息，请参阅语义版本规范。

ComponentDescription

（可选）组件的描述。

ComponentPublisher

组件的发布者或作者。

ComponentConfiguration

（可选）定义组件配置或参数的对象。您可以定义默认配置，然后在部署组件时，可以指定要提供给组件的配置对象。组件配置支持嵌套参数和结构。该对象包含以下信息：

DefaultConfiguration

定义组件默认配置的对象。您可以定义此对象的结构。

注意

Amazon IoT Greengrass使用 JSON 作为配置值。JSON 指定了数字类型，但不区分整数和浮点数。因此，配置值可能会转换为浮点数。Amazon IoT Greengrass为确保您的组件使用正确的数据类型，我们建议您将数字配置值定义为字符串。然后，让你的组件将它们解析为整数或浮点数。这样可以确保您的配置值在配置和核心设备上具有相同的类型。

ComponentDependencies

（可选）一个对象字典，每个对象都定义了组件的组件依赖关系。每个对象的密钥标识组件依赖关系的名称。 Amazon IoT Greengrass安装组件时安装组件依赖关系。 Amazon IoT Greengrass等待依赖关系启动后再启动组件。每个对象都包含以下信息：

VersionRequirement

npm 风格的语义版本约束，用于定义此依赖项的兼容组件版本。您可以指定一个版本或一系列版本。有关更多信息，请参阅 npm 语义版本计算器。

DependencyType

（可选）此依赖项的类型。从以下选项中进行选择。

  • SOFT – 如果依赖项更改状态，组件不会重新启动。

  • HARD – 如果依赖项更改状态，组件将会重新启动。

默认值为 HARD。

ComponentType

（可选）组件的类型。

注意

我们不建议您在配方中指定组件类型。 Amazon IoT Greengrass在创建组件时为您设置类型。

该类型可以是以下类型之一：

  • aws.greengrass.generic— 该组件运行命令或提供工件。

  • aws.greengrass.lambda— 该组件使用 Lambda 启动器组件运行 Lambda 函数。该ComponentSource参数指定此组件运行的 Lambda 函数的 ARN。

    我们不建议您使用此选项，因为它是在您通过 Lambda 函数创建组件Amazon IoT Greengrass时设置的。有关更多信息，请参阅 运行Amazon Lambda函数。

  • aws.greengrass.plugin— 该组件与 Greengrass 核心在同一 Java 虚拟机 (JVM) 中运行。如果您部署或重启插件组件，Greengrass 核心将重新启动。

    插件组件使用与 Greengrass 核心相同的日志文件。有关更多信息，请参阅 监控Amazon IoT Greengrass日志。

    我们不建议您在组件配方中使用此选项，因为它适用于Amazon由 Java 编写的、直接与 Greengrass 核心接口的组件。有关哪些公共组件是插件的更多信息，请参阅Amazon-提供的组件。

  • aws.greengrass.nucleus— 原子核成分。有关更多信息，请参阅 Greengrass 核。

    我们不建议您在组件配方中使用此选项。它适用于Greengrass nucleus组件，该组件提供了核心软件的最低功能。Amazon IoT Greengrass

aws.greengrass.generic当您使用配方创建组件时，或者从 Lambda 函数创建组件aws.greengrass.lambda时，默认为。

有关更多信息，请参阅 组件类型。

ComponentSource

（可选）组件运行的 Lambda 函数的 ARN。

我们不建议您在配方中指定组件来源。 Amazon IoT Greengrass当您通过 Lambda 函数创建组件时，为您设置此参数。有关更多信息，请参阅 运行Amazon Lambda函数。

Manifests

对象列表，每个对象都定义了组件的生命周期、参数和平台要求。如果核心设备符合多个清单的平台要求，则Amazon IoT Greengrass使用与核心设备匹配的第一个清单。为确保核心设备使用正确的清单，请先定义具有更严格平台要求的清单。适用于所有平台的清单必须是列表中的最后一个清单。

重要

核心设备必须满足至少一个清单的平台要求才能安装该组件。如果没有清单与核心设备匹配，则Amazon IoT Greengrass核心软件不会安装该组件，部署将失败。

每个对象都包含以下信息：

Name

（可选）此清单定义的平台的友好名称。

如果省略此参数，则会从平台Amazon IoT Greengrass创建名称，os然后。architecture

Platform

（可选）一个对象，用于定义此清单所适用的平台。省略此参数可定义适用于所有平台的清单。

此对象指定有关核心设备运行平台的键值对。部署此组件时，Amazon IoT GreengrassCore 软件会将这些键值对与核心设备上的平台属性进行比较。C Amazon IoT Greengrass ore 软件始终定义os和architecture，它可能会定义其他属性。在部署 Greengrass nucleus 组件时，您可以为核心设备指定自定义平台属性。有关更多信息，请参阅 Gre engrass nucleus 组件的平台覆盖参数。

对于每个键值对，您可以指定以下值之一：

  • 一个精确的值，例如linux或windows。精确值必须以字母或数字开头。

  • *，它与任何值匹配。当值不存在时，这也会匹配。

  • Java 风格的正则表达式，例如。/windows|linux/正则表达式必须以斜杠字符 (/) 开头和结尾。例如，正则表达式/.+/匹配任何非空值。

该对象包含以下信息：

os

（可选）此清单支持的平台的操作系统的名称。常用平台包括以下值：

  • linux

  • windows

  • darwin (macOS)

architecture

（可选）此清单支持的平台的处理器架构。常见架构包括以下值：

  • amd64

  • arm

  • aarch64

  • x86

architecture.detail

（可选）此清单支持的平台的处理器架构详细信息。常见的架构细节包括以下值：

  • arm61

  • arm71

  • arm81

key

（可选）您为此清单定义的平台属性。将密钥替换为平台属性的名称。Amazon IoT GreengrassCore 软件将此平台属性与您在 Greengrass nucleus 组件配置中指定的键值对进行匹配。有关更多信息，请参阅 Gre engrass nucleus 组件的平台覆盖参数。

提示

使用反向域名格式以避免公司内部的域名冲突。例如，如果您的公司拥有一个广播项目，example.com而您从事广播项目，则可以命名自定义平台属性com.example.radio.RadioModule。这有助于避免公司内部的平台属性名称冲突。

例如，您可以定义平台属性com.example.radio.RadioModule，根据核心设备上可用的无线电模块来指定不同的清单。每个清单可以包含适用于不同硬件配置的不同构件，因此您可以将最少的软件集部署到核心设备。

Lifecycle

一个对象或字符串，用于定义如何在此清单定义的平台上安装和运行组件。您还可以定义适用于所有平台的全球生命周期。只有在要使用的清单未指定生命周期时，核心设备才会使用全局生命周期。

注意

你可以在清单中定义这个生命周期。您在此处指定的生命周期步骤仅适用于此清单所定义的平台。您还可以定义适用于所有平台的全球生命周期。

此对象或字符串包含以下信息：

Setenv

（可选）提供给所有生命周期脚本的环境变量字典。您可以在每个生命周期脚本Setenv中使用覆盖这些环境变量。

install

（可选）定义组件安装时要运行的脚本的对象或字符串。每次软件启动时，Amazon IoT GreengrassCore 软件也会运行此生命周期步骤。

如果install脚本以成功代码退出，则组件将进入INSTALLED状态。

此对象或字符串包含以下信息：

Script

要运行的脚本。

RequiresPrivilege

（可选）您可以使用 root 权限运行脚本。如果将此选项设置为true，则 Amazon IoT Greengrass Core 软件将以 root 用户身份运行此生命周期脚本，而不是以您配置为运行此组件的系统用户的身份运行此生命周期脚本。默认值为 false。

Skipif

（可选）用于确定是否运行脚本的检查。您可以定义以检查路径上是否有可执行文件或文件是否存在。如果输出为真，则 Amazon IoT Greengrass Core 软件将跳过该步骤。选择以下支票之一：

  • onpath runnable— 检查系统路径上是否有可运行对象。例如，如果 Python 3 可用，则使用onpath python3跳过此生命周期步骤。

  • exists file— 检查文件是否存在。例如，如果/tmp/my-configuration.db存在此生命周期步骤，则使用exists /tmp/my-configuration.db可跳过此生命周期步骤。

Timeout

（可选）在Amazon IoT Greengrass核心软件终止进程之前，脚本可以运行的最大时间（以秒为单位）。

默认值：120 秒

Setenv

（可选）要提供给脚本的环境变量字典。这些环境变量会覆盖您在中提供的变量Lifecycle.Setenv。

run

（可选）定义组件启动时要运行的脚本的对象或字符串。

当此生命周期步骤运行时，组件进入RUNNING状态。如果run脚本以成功代码退出，则组件将进入STOPPING状态。如果指定了shutdown脚本，则它会运行；否则组件进入FINISHED状态。

依赖此组件的组件将在此生命周期步骤运行时启动。要运行后台进程，例如依赖组件使用的服务，请改用startup生命周期步骤。

当您部署具有run生命周期的组件时，核心设备可以在此生命周期脚本运行后立即报告部署已完成。因此，即使run生命周期脚本在运行后不久就失败了，部署也可以完成并成功。如果您希望部署状态取决于组件启动脚本的结果，请改用startup生命周期步骤。

注意

您只能定义一个startup或run生命周期。

此对象或字符串包含以下信息：

Script

要运行的脚本。

RequiresPrivilege

（可选）您可以使用 root 权限运行脚本。如果将此选项设置为true，则 Amazon IoT Greengrass Core 软件将以 root 用户身份运行此生命周期脚本，而不是以您配置为运行此组件的系统用户的身份运行此生命周期脚本。默认值为 false。

Skipif

（可选）用于确定是否运行脚本的检查。您可以定义以检查路径上是否有可执行文件或文件是否存在。如果输出为真，则 Amazon IoT Greengrass Core 软件将跳过该步骤。选择以下支票之一：

  • onpath runnable— 检查系统路径上是否有可运行对象。例如，如果 Python 3 可用，则使用onpath python3跳过此生命周期步骤。

  • exists file— 检查文件是否存在。例如，如果/tmp/my-configuration.db存在此生命周期步骤，则使用exists /tmp/my-configuration.db可跳过此生命周期步骤。

Timeout

（可选）在Amazon IoT Greengrass核心软件终止进程之前，脚本可以运行的最大时间（以秒为单位）。

默认情况下，此生命周期步骤不会超时。如果省略此超时，run脚本将一直运行直到退出。

Setenv

（可选）要提供给脚本的环境变量字典。这些环境变量会覆盖您在中提供的变量Lifecycle.Setenv。

startup

（可选）定义组件启动时要运行的后台进程的对象或字符串。

startup用于运行必须成功退出或将组件状态更新为RUNNING才能启动依赖组件的命令。使用 UpdateStateIPC 操作将组件的状态设置为RUNNING或ERRORED当组件启动未退出的脚本时。例如，您可以定义一个用于启动 MySQL 进程的startup步骤/etc/init.d/mysqld start。

当此生命周期步骤运行时，组件进入STARTING状态。如果startup脚本以成功代码退出，则组件将进入RUNNING状态。然后，可以启动依赖组件。

当您部署具有startup生命周期的组件时，核心设备可以在此生命周期脚本退出或报告其状态后将部署报告为已完成。换句话说，部署的状态是IN_PROGRESS直到所有组件的启动脚本退出或报告状态为止。

注意

您只能定义一个startup或run生命周期。

此对象或字符串包含以下信息：

Script

要运行的脚本。

RequiresPrivilege

（可选）您可以使用 root 权限运行脚本。如果将此选项设置为true，则 Amazon IoT Greengrass Core 软件将以 root 用户身份运行此生命周期脚本，而不是以您配置为运行此组件的系统用户的身份运行此生命周期脚本。默认值为 false。

Skipif

（可选）用于确定是否运行脚本的检查。您可以定义以检查路径上是否有可执行文件或文件是否存在。如果输出为真，则 Amazon IoT Greengrass Core 软件将跳过该步骤。选择以下支票之一：

  • onpath runnable— 检查系统路径上是否有可运行对象。例如，如果 Python 3 可用，则使用onpath python3跳过此生命周期步骤。

  • exists file— 检查文件是否存在。例如，如果/tmp/my-configuration.db存在此生命周期步骤，则使用exists /tmp/my-configuration.db可跳过此生命周期步骤。

Timeout

（可选）在Amazon IoT Greengrass核心软件终止进程之前，脚本可以运行的最大时间（以秒为单位）。

默认值：120 秒

Setenv

（可选）要提供给脚本的环境变量字典。这些环境变量会覆盖您在中提供的变量Lifecycle.Setenv。

shutdown

（可选）定义组件关闭时要运行的脚本的对象或字符串。使用关闭生命周期来执行要在组件处于STOPPING状态时运行的代码。关闭生命周期可用于停止startup或run脚本启动的进程。

如果您在中启动后台进程startup，请使用该shutdown步骤在组件关闭时停止该进程。例如，您可以定义一个停止 MySQL 进程的shutdown步骤/etc/init.d/mysqld stop。

该shutdown脚本在组件进入STOPPING状态后运行。如果脚本成功完成，则组件将进入FINISHED状态。

此对象或字符串包含以下信息：

Script

要运行的脚本。

RequiresPrivilege

（可选）您可以使用 root 权限运行脚本。如果将此选项设置为true，则 Amazon IoT Greengrass Core 软件将以 root 用户身份运行此生命周期脚本，而不是以您配置为运行此组件的系统用户的身份运行此生命周期脚本。默认值为 false。

Skipif

（可选）用于确定是否运行脚本的检查。您可以定义以检查路径上是否有可执行文件或文件是否存在。如果输出为真，则 Amazon IoT Greengrass Core 软件将跳过该步骤。选择以下支票之一：

  • onpath runnable— 检查系统路径上是否有可运行对象。例如，如果 Python 3 可用，则使用onpath python3跳过此生命周期步骤。

  • exists file— 检查文件是否存在。例如，如果/tmp/my-configuration.db存在此生命周期步骤，则使用exists /tmp/my-configuration.db可跳过此生命周期步骤。

Timeout

（可选）在Amazon IoT Greengrass核心软件终止进程之前，脚本可以运行的最大时间（以秒为单位）。

默认值：15 秒。

Setenv

（可选）要提供给脚本的环境变量字典。这些环境变量会覆盖您在中提供的变量Lifecycle.Setenv。

recover

（可选）一个对象或字符串，用于定义在组件遇到错误时要运行的脚本。

此步骤在组件进入ERRORED状态时运行。如果组件变为ERRORED三次但未成功恢复，则该组件将变为BROKEN状态。要修复组BROKEN件，必须重新部署它。

此对象或字符串包含以下信息：

Script

要运行的脚本。

RequiresPrivilege

（可选）您可以使用 root 权限运行脚本。如果将此选项设置为true，则 Amazon IoT Greengrass Core 软件将以 root 用户身份运行此生命周期脚本，而不是以您配置为运行此组件的系统用户的身份运行此生命周期脚本。默认值为 false。

Skipif

（可选）用于确定是否运行脚本的检查。您可以定义以检查路径上是否有可执行文件或文件是否存在。如果输出为真，则 Amazon IoT Greengrass Core 软件将跳过该步骤。选择以下支票之一：

  • onpath runnable— 检查系统路径上是否有可运行对象。例如，如果 Python 3 可用，则使用onpath python3跳过此生命周期步骤。

  • exists file— 检查文件是否存在。例如，如果/tmp/my-configuration.db存在此生命周期步骤，则使用exists /tmp/my-configuration.db可跳过此生命周期步骤。

Timeout

（可选）在Amazon IoT Greengrass核心软件终止进程之前，脚本可以运行的最大时间（以秒为单位）。

默认值：60 秒。

Setenv

（可选）要提供给脚本的环境变量字典。这些环境变量会覆盖您在中提供的变量Lifecycle.Setenv。

bootstrap

（可选）定义要求Amazon IoT Greengrass核心软件或核心设备重新启动的脚本的对象或字符串。例如，这使您可以开发一个在安装操作系统更新或运行时更新后执行重启的组件。

注意

要安装不需要重启Amazon IoT Greengrass核心软件或设备的更新或依赖项，请使用安装生命周期。

在以下情况下，当Amazon IoT Greengrass核心软件部署组件时，此生命周期步骤在安装生命周期步骤之前运行：

  • 该组件首次部署到核心设备。

  • 组件版本发生变化。

  • 由于组件配置更新，引导脚本会发生变化。

Amazon IoT Greengrass核心软件完成部署中包含引导步骤的所有组件的引导步骤后，软件将重新启动。

重要

必须将Amazon IoT Greengrass核心软件配置为系统服务才能重新启动Amazon IoT Greengrass核心软件或核心设备。如果您未将 Amazon IoT Greengrass Core 软件配置为系统服务，则该软件将无法重新启动。有关更多信息，请参阅 将 Greengrass 核心配置为系统服务。

此对象或字符串包含以下信息：

BootstrapOnRollback
注意

启用此功能后，BootstrapOnRollback只有在失败的目标部署中已完成或尝试运行引导生命周期步骤的组件才会运行。此功能适用于 Greengrass nucleus 版本 2.12.0 及更高版本。

（可选）您可以将引导生命周期步骤作为回滚部署的一部分来运行。如果将此选项设置为true，则将在回滚部署中定义的引导生命周期步骤运行。部署失败时，先前版本的组件引导程序生命周期将在回滚部署期间再次运行。

默认值为 false。

Script

要运行的脚本。此脚本的退出代码定义了重启指令。使用以下退出代码：

  • 0— 不要重启Amazon IoT Greengrass核心软件或核心设备。在所有组件启动后，Amazon IoT GreengrassCore 软件仍会重新启动。

  • 100— 请求重新启动 Amazon IoT Greengrass Core 软件。

  • 101— 请求重启核心设备。

退出代码 100 到 199 是为特殊行为保留的。其他退出代码代表脚本错误。

RequiresPrivilege

（可选）您可以使用 root 权限运行脚本。如果将此选项设置为true，则 Amazon IoT Greengrass Core 软件将以 root 用户身份运行此生命周期脚本，而不是以您配置为运行此组件的系统用户的身份运行此生命周期脚本。默认值为 false。

Timeout

（可选）在Amazon IoT Greengrass核心软件终止进程之前，脚本可以运行的最大时间（以秒为单位）。

默认值：120 秒

Setenv

（可选）要提供给脚本的环境变量字典。这些环境变量会覆盖您在中提供的变量Lifecycle.Setenv。

Selections

（可选）选择键列表，用于指定要为此清单运行的全局生命周期的各个部分。在全局生命周期中，您可以使用任何级别的选择键来定义生命周期步骤，以选择生命周期的子部分。然后，核心设备使用与该清单中的选择键相匹配的部分。有关更多信息，请参阅全球生命周期示例。

重要

仅当此清单未定义生命周期时，核心设备才会使用全局生命周期中的选项。

您可以指定all选择密钥来运行全局生命周期中没有选择键的部分。

Artifacts

（可选）对象列表，每个对象都为该清单所定义的平台上的组件定义了一个二进制构件。例如，您可以将代码或图像定义为工件。

部署组件时，Amazon IoT GreengrassCore 软件会将构件下载到核心设备上的文件夹。您也可以将构件定义为软件下载后提取的存档文件。

您可以使用配方变量来获取核心设备上安装工件的文件夹的路径。

  • 普通文件 — 使用 artifacts: path 配方变量获取包含工件的文件夹的路径。例如，在配方{artifacts:path}/my_script.py中指定以获取包含 URI 的工件的路径s3://DOC-EXAMPLE-BUCKET/path/to/my_script.py。

  • 提取的档案 — 使用 art ifacts: decompressedPath 配方变量获取包含已提取存档工件的文件夹的路径。C Amazon IoT Greengrass ore 软件将每个存档提取到与存档同名的文件夹中。例如，在配方{artifacts:decompressedPath}/my_archive/my_script.py中指定以获取包含 URI 的存档构件my_script.py中的路径s3://DOC-EXAMPLE-BUCKET/path/to/my_archive.zip。

注意

在本地核心设备上开发带有存档构件的组件时，可能没有该构件的 URI。要使用提取构件的Unarchive选项测试组件，请指定一个文件名与存档构件文件名匹配的 URI。您可以指定要将存档项目上传到的 URI，也可以指定新的占位符 URI。例如，要在本地部署期间提取my_archive.zip对象，可以指定s3://DOC-EXAMPLE-BUCKET/my_archive.zip。

每个对象都包含以下信息：

URI

S3 存储桶中工件的 URI。安装组件时，Amazon IoT GreengrassCore 软件会从此 URI 中获取工件，除非该构件已存在于设备上。每个项目在每个清单中都必须有一个唯一的文件名。

Unarchive

（可选）要解压缩的档案类型。从以下选项中进行选择：

  • NONE— 该文件不是要解压的存档。C Amazon IoT Greengrass ore 软件将构件安装到核心设备上的文件夹。你可以使用 artifacts: path 配方变量来获取此文件夹的路径。

  • ZIP— 该文件是一个 ZIP 存档。C Amazon IoT Greengrass ore 软件将存档提取到与存档同名的文件夹。你可以使用 artifacts: decompressedPath 配方变量来获取包含此文件夹的文件夹的路径。

默认值为 NONE。

Permission

（可选）一个对象，用于定义要为此构件文件设置的访问权限。您可以设置读取权限和执行权限。

注意

您无法设置写入权限，因为Amazon IoT Greengrass核心软件不允许组件编辑构件文件夹中的构件文件。要编辑组件中的构件文件，请将其复制到其他位置或发布并部署新的构件文件。

如果您将工件定义为要解压缩的存档，则 Amazon IoT Greengrass Core 软件会对其从存档中解压缩的文件设置这些访问权限。C Amazon IoT Greengrass ore 软件将文件夹的访问权限设置ALL为Read和Execute。这允许组件查看文件夹中已解压缩的文件。要为存档中的单个文件设置权限，可以在安装生命周期脚本中设置权限。

该对象包含以下信息：

Read

（可选）要为此构件文件设置的读取权限。要允许其他组件访问此构件，例如依赖于此组件的组件，请指定ALL。从以下选项中进行选择：

  • NONE— 文件不可读。

  • OWNER— 您配置为运行此组件的系统用户可以读取该文件。

  • ALL— 所有用户都可以读取该文件。

默认值为 OWNER。

Execute

（可选）要为此构件文件设置的运行权限。该Execute权限意味着Read权限。例如，如果您ALL为指定Execute，则所有用户都可以读取和运行此构件文件。

从以下选项中进行选择：

  • NONE— 该文件无法运行。

  • OWNER— 该文件可由您配置为运行该组件的系统用户运行。

  • ALL— 该文件可供所有用户运行。

默认值为 NONE。

Digest

（只读）工件的加密摘要哈希。创建组件时，Amazon IoT Greengrass使用哈希算法计算构件文件的哈希值。然后，在部署组件时，Greengrass nucleus 会计算已下载工件的哈希值，并将哈希值与该摘要进行比较，以便在安装之前验证工件。如果哈希值与摘要不匹配，则部署失败。

如果您设置了此参数，则Amazon IoT Greengrass会替换您在创建组件时设置的值。

Algorithm

（只读）Amazon IoT Greengrass用于计算工件摘要哈希值的哈希算法。

如果您设置了此参数，则Amazon 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_variable}语法。大括号表示配方变量。

Amazon IoT Greengrass支持以下配方变量：

component_dependency_name:configuration:json_pointer

此配方定义的组件或该组件所依赖的组件的配置参数值。

您可以使用此变量为在组件生命周期中运行的脚本提供参数。

注意

Amazon IoT Greengrass仅在组件生命周期定义中支持此配方变量。

此配方变量具有以下输入：

  • component_dependency_name—（可选）要查询的组件依赖项的名称。省略此区段可查询此配方定义的组件。您只能指定直接依赖关系。

  • json_pointer— 指向要评估的配置值的 JSON 指针。JSON 指针以正斜杠/开头。要标识嵌套组件配置中的值，请使用正斜杠 (/) 分隔配置中每个级别的键。您可以使用数字作为键来指定列表中的索引。有关更多信息，请参阅 JSON 指针规范。

    Amazon IoT GreengrassCore 使用 JSON 指针获取 YAML 格式的食谱。

JSON 指针可以引用以下节点类型：

  • 一个值节点。 Amazon IoT GreengrassCore 将配方变量替换为该值的字符串表示形式。空值转换为null字符串。

  • 一个对象节点。 Amazon IoT GreengrassCore 将配方变量替换为该对象的序列化 JSON 字符串表示形式。

  • 没有节点。 Amazon IoT GreengrassCore 不会替换配方变量。

例如，{configuration:/Message}配方变量检索组件配置中Message键的值。{com.example.MyComponentDependency:configuration:/server/port}配方变量在组件依赖关系的server配置对象port中检索的值。

component_dependency_name:artifacts:path

此配方定义的组件或该组件所依赖的组件的工件根路径。

安装组件时，会将该组件的构件Amazon IoT Greengrass复制到此变量公开的文件夹。例如，您可以使用此变量来标识要在组件生命周期中运行的脚本的位置。

此路径下的文件夹为只读文件夹。要修改构件文件，请将文件复制到其他位置，例如当前工作目录（$PWD或.）。然后，修改那里的文件。

要从组件依赖项中读取或运行工件，则该构件Read或Execute权限必须是ALL。有关更多信息，请参阅您在组件配方中定义的构件权限。

此配方变量具有以下输入：

  • component_dependency_name—（可选）要查询的组件依赖项的名称。省略此区段可查询此配方定义的组件。您只能指定直接依赖关系。

component_dependency_name:artifacts:decompressedPath

此配方定义的组件或该组件所依赖的组件的解压缩存档工件的根路径。

安装组件后，将该组件的存档工件Amazon IoT Greengrass解压缩到此变量公开的文件夹。例如，您可以使用此变量来标识要在组件生命周期中运行的脚本的位置。

每个工件都会解压缩到解压缩路径内的一个文件夹，该文件夹与构件同名，减去其扩展名。例如，名为的 ZIP 工件models.zip解压缩到该{artifacts:decompressedPath}/models文件夹。

此路径下的文件夹为只读文件夹。要修改构件文件，请将文件复制到其他位置，例如当前工作目录（$PWD或.）。然后，修改那里的文件。

要从组件依赖项中读取或运行工件，则该构件Read或Execute权限必须是ALL。有关更多信息，请参阅您在组件配方中定义的构件权限。

此配方变量具有以下输入：

  • component_dependency_name—（可选）要查询的组件依赖项的名称。省略此区段可查询此配方定义的组件。您只能指定直接依赖关系。

component_dependency_name:work:path

此功能适用于 2.0.4 及更高版本的 Greengrass nucleus 组件。

此配方定义的组件或该组件所依赖的组件的工作路径。从组件的上下文中运行时，此配方变量的值等同于$PWD环境变量和 pwd 命令的输出。

您可以使用此配方变量在组件和依赖项之间共享文件。

此路径下的文件夹可由此配方定义的组件以及以同一用户和组身份运行的其他组件进行读写操作。

此配方变量具有以下输入：

  • component_dependency_name—（可选）要查询的组件依赖项的名称。省略此区段可查询此配方定义的组件。您只能指定直接依赖关系。

kernel:rootPath

Amazon IoT Greengrass核心根路径。

iot:thingName

此功能适用于 2.3.0 及更高版本的 Greengrass nucleus 组件。

核心设备的名称Amazon IoT。

食谱示例

您可以参考以下配方示例，以帮助您为组件创建配方。

Amazon IoT Greengrass策划了一份名为 Greengrass 软件目录的 Greengrass 组件索引。该目录追踪了 Greengrass 社区开发的 Greengrass 组件。您可以从该目录中下载、修改和部署组件来创建 Greengrass 应用程序。有关更多信息，请参阅 社区组件。

你好 World 组件配方

以下配方描述了一个运行 Python 脚本的 Hello World 组件。该组件支持所有平台，并接受作为Message参数Amazon IoT Greengrass传递给 Python 脚本的参数。这是入门教程中 Hello World 组件的配方。

JSON
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.HelloWorld",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "My first Amazon 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 Amazon 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 Amazon 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://DOC-EXAMPLE-BUCKET/hello_world.zip",
          "Unarchive": "ZIP"
        },
        {
          "URI": "s3://DOC-EXAMPLE-BUCKET/hello_world_linux.py"
        }
      ]
    },
    {
      "Lifecycle": {
        "install": {
          "Skipif": "onpath git",
          "Script": "sudo apt-get install git",
          "RequiresPrivilege": "true"
        }
      },
      "Artifacts": [
        {
          "URI": "s3://DOC-EXAMPLE-BUCKET/hello_world.py"
        }
      ]
    }
  ]
}
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.FooService
ComponentDescription: Complete recipe for Amazon 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://DOC-EXAMPLE-BUCKET/hello_world.zip'
        Unarchive: ZIP
      - URI: 's3://DOC-EXAMPLE-BUCKET/hello_world_linux.py'
  - Lifecycle:
      install:
        Skipif: onpath git
        Script: sudo apt-get install git
        RequiresPrivilege: 'true'
    Artifacts:
      - URI: 's3://DOC-EXAMPLE-BUCKET/hello_world.py'