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 格式定义食谱。食谱示例部分包含每种格式的食谱。

食谱格式

为组件定义配方时，需要在配方文档中指定以下信息。同样的结构适用于 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

组件版本。

注意

Amazon IoT Greengrass对组件使用语义版本。语义版本遵循主要版本。 未成年人。 补丁号系统。例如，版本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 Core 软件的最低功能。

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

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

ComponentSource

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

我们建议您不要在食谱中不要指定组件来源。 Amazon IoT Greengrass在您从 Lambda 函数创建组件时为您设置此参数。有关更多信息，请参阅运行Amazon Lambda函数：

Manifests

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

重要

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

每个对象包含以下信息：

Name

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

如果省略此参数，则会从平台os和中Amazon IoT Greengrass创建一个名称architecture。

Platform

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

此对象指定了有关运行核心设备的平台的键值对。部署此组件时，CorAmazon IoT Greengrass e 软件会将这些键值对与核心设备上的平台属性进行比较。Amazon IoT GreengrassCore 软件始终定义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

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

提示

使用反向域名格式以避免公司内部的域名冲突。例如，如果您的公司拥有一个广播项目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 Core 软件终止进程之前，脚本可以运行的最长时间（以秒为单位）。

默认值：120 秒

Setenv

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

Run

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

组件在此生命周期步骤运行时进入RUNNING状态。如果Run脚本以成功代码退出，则组件将进入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 Core 软件终止进程之前，脚本可以运行的最长时间（以秒为单位）。

默认情况下，此生命周期步骤不会超时。如果您省略此超时，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 Core 软件终止进程之前，脚本可以运行的最长时间（以秒为单位）。

默认值：120 秒

Setenv

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

Shutdown

（可选）一个对象或字符串，用于定义组件关闭时要运行的脚本。

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

组件在此生命周期步骤运行时进入STOPPING状态。

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

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 Core 软件终止进程之前，脚本可以运行的最长时间（以秒为单位）。

默认值：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 Core 软件终止进程之前，脚本可以运行的最长时间（以秒为单位）。

默认值：60 秒。

Setenv

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

Bootstrap

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

注意

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

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

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

  • 组件版本发生变化。

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

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

重要

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

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

Script

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

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

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

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

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

RequiresPrivilege

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

Timeout

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

默认值：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。

  • 提取的存档 — 使用 Artifacts: decompressedPath 配方变量获取包含提取的存档构件的文件夹的路径。Amazon IoT GreengrassCore 软件将每个存档解压到与存档同名的文件夹。例如，在配方{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— 该文件不是要解压缩的存档。Amazon IoT GreengrassCore 软件将工件安装到核心设备上的文件夹。你可以使用 artifacts: path 配方变量来获取这个文件夹的路径。

  • ZIP— 该文件是 ZIP 存档。Amazon IoT GreengrassCore 软件将存档解压到与存档同名的文件夹。你可以使用 Artifacts: decompressedPath 配方变量来获取包含此文件夹的文件夹的路径。

默认值为 NONE。

Permission

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

注意

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

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

此对象包含以下信息：

Read

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

  • NONE— 该文件不可读。

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

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

默认值为 OWNER。

Execute

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

从以下选项中进行选择：

  • 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: onpath executable | 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: onpath executable | 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 指针以正斜杠开头/。要识别嵌套组件配置中的值，请使用正斜杠 (/) 分隔配置中每个级别的密钥。您可以使用数字作为键来指定列表中的索引。有关更多信息，请参阅 JSOON 指针规范。

    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或.）。然后，修改那里的文件。

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

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

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

component_dependency_name:artifacts:decompressedPath

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

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

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

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

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

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

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

component_dependency_name:work:path

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

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

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

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

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

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

kernel:rootPath

Amazon IoT Greengrass核心根路径。

iot:thingName

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

核心设备的名称Amazon IoT。

食谱示例

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

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

你好 World 组件配方

下面的食谱描述运行 Python 脚本的 Hello 脚本。该组件支持所有平台并接受作为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"
        }
      },
      "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
    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