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

# AWS IoT Greengrass 组件配方参考
<a name="component-recipe-reference"></a>

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

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

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

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

在 AWS IoT Greengrass 核心软件选择与核心设备匹配的清单后，它会执行以下操作来确定要使用的生命周期步骤：
+ 如果所选清单定义了生命周期，则核心设备将使用该生命周期。
+ 如果所选清单未定义生命周期，则核心设备将使用全局生命周期。核心设备执行以下操作来确定要使用全局生命周期的哪些部分：
  + 如果清单定义了选择键，则核心设备将使用全局生命周期中包含清单选择键的部分。
  + 如果清单未定义选择键，则核心设备将使用全局生命周期中没有选择键的部分。此行为等同于定义 `all` 选择的清单。

**重要**  <a name="recipe-core-device-manifest-requirement"></a>
核心设备必须满足至少一个清单的平台要求才能安装该组件。如果没有清单与核心设备匹配，则 AWS IoT Greengrass 核心软件不会安装该组件，部署将失败。

您可以用 [JSON](https://en.wikipedia.org/wiki/JSON) 或 [YAML](https://en.wikipedia.org/wiki/YAML) 格式定义配方。配方示例部分包括各种格式的配方。

**Topics**
+ [配方验证](#recipe-validation)
+ [配方格式](#recipe-format)
+ [配方变量](#recipe-variables)
+ [配方示例](#recipe-examples)

## 配方验证
<a name="recipe-validation"></a>

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

如果您收到配方验证错误消息，请检查您的配方中是否缺少逗号、大括号或字段。查看[配方格式](#recipe-format)，确认您没有遗漏任何字段。

## 配方格式
<a name="recipe-format"></a>

在为组件定义配方时，需要在配方文档中指定以下信息。同样的结构适用于 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。  
<a name="semver-para"></a>AWS IoT Greengrass 使用组件的语义版本。语义版本遵循 *major*.*minor*.*patch* 编号系统。例如，版本 `1.0.0` 表示组件的第一个主要版本。有关更多信息，请参阅[语义版本规范](https://semver.org/)。

`ComponentDescription`  
（可选）组件的描述。

`ComponentPublisher`  
组件的发布者或作者。

`ComponentConfiguration`  
（可选）定义组件配置或参数的对象。您可以定义默认配置，然后在部署组件时，可以指定要提供给组件的配置对象。组件配置支持嵌套参数和结构。该对象包含以下信息：    
`DefaultConfiguration`  
定义组件默认配置的对象。您可以定义此对象的结构。  
<a name="configuration-value-type-note"></a>AWS IoT Greengrass 使用 JSON 作为配置值。JSON 指定了数字类型，但不区分整数和浮点数。因此， AWS IoT Greengrass中的配置值可能会转换为浮点数。为确保您的组件使用正确的数据类型，我们建议您将数字配置值定义为字符串。然后，让组件将其解析为整数或浮点数。这样可以确保您的配置值在配置和核心设备上具有相同的类型。

`ComponentDependencies`  <a name="recipe-reference-component-dependencies"></a>
（可选）一个对象字典，每个对象都定义了组件的组件依赖关系。每个对象的密钥标识组件依赖关系的名称。 AWS IoT Greengrass 安装组件时安装组件依赖关系。 AWS IoT Greengrass 等待依赖关系启动后再启动组件。每个对象包含以下信息：    
`VersionRequirement`  
npm 风格的语义版本约束，用于定义此依赖关系的兼容组件版本。您可以指定一个版本或一系列版本。有关更多信息，请参阅 [npm 语义版本计算器](https://semver.npmjs.com/)。  
`DependencyType`  
（可选）这种依赖关系的类型。从以下选项中进行选择。  
+ `SOFT` – 如果依赖关系更改状态，组件不会重新启动。
+ `HARD` – 如果依赖关系更改状态，组件将会重新启动。
默认值为 `HARD`。

`ComponentType`  
（可选）组件的类型。  
我们不建议您在配方中指定组件类型。 AWS IoT Greengrass 在创建组件时为您设置类型。
类型可以是以下项之一：  
+ `aws.greengrass.generic` – 组件运行命令或提供构件。
+ `aws.greengrass.lambda` – 组件使用 [Lambda 启动组件](lambda-launcher-component.md)运行 Lambda 函数。`ComponentSource` 参数指定此组件运行的 Lambda 函数的 ARN。

  我们不建议您使用此选项，因为它是在您通过 Lambda 函数创建组件 AWS IoT Greengrass 时设置的。有关更多信息，请参阅 [运行 AWS Lambda 函数](run-lambda-functions.md)。
+ `aws.greengrass.plugin` – 该组件与 Greengrass Nucleus 在同一 Java 虚拟机（JVM）中运行。如果您部署或重启插件组件，Greengrass Nucleus 将重新启动。

  插件组件使用与 Greengrass Nucleus 相同的日志文件。有关更多信息，请参阅 [监控 AWS IoT Greengrass 日志](monitor-logs.md)。

  我们不建议您在组件配方中使用此选项，因为它适用于 AWS由 Java 编写的、直接与 Greengrass 核心接口的组件。有关哪些公有组件是插件的更多信息，请参阅 [AWS提供的组件](public-components.md)。
+ `aws.greengrass.nucleus` – 核心成分。有关更多信息，请参阅 [Greengrass Nucleus](greengrass-nucleus-component.md)。

  我们建议您不要在组件配方中使用此选项。它适用于 Greengrass Nucleus 组件，该组件提供了 AWS IoT Greengrass Core 软件的最低功能。
从配方创建组件时默认为 `aws.greengrass.generic`，从 Lambda 函数创建组件时默认为 `aws.greengrass.lambda`。  
有关更多信息，请参阅 [组件类型](develop-greengrass-components.md#component-types)。

`ComponentSource`  
（可选）组件运行的 Lambda 函数的 ARN。  
我们不建议您在配方中指定组件来源。 AWS IoT Greengrass 当您通过 Lambda 函数创建组件时，为您设置此参数。有关更多信息，请参阅 [运行 AWS Lambda 函数](run-lambda-functions.md)。

  `Manifests`   
对象列表，每个对象都定义了组件的生命周期、参数和平台要求。如果核心设备符合多个清单的平台要求，则 AWS IoT Greengrass 使用与核心设备匹配的第一个清单。为确保核心设备使用正确的清单，请先定义平台要求更严格的清单。适用于所有平台的清单必须是列表中的最后一个清单。  
核心设备必须满足至少一个清单的平台要求才能安装该组件。如果没有清单与核心设备匹配，则 AWS IoT Greengrass 核心软件不会安装该组件，部署将失败。
每个对象包含以下信息：    
`Name`  
（可选）此清单定义的平台友好名称。  
如果省略此参数，则会从平台 AWS IoT Greengrass 创建名称，`os`然后。`architecture`  
  `Platform`   
（可选）定义此清单所适用平台的对象。省略此参数可定义适用于所有平台的清单。  
此对象指定有关核心设备运行平台的键值对。部署此组件时， AWS IoT Greengrass Core 软件会将这些键值对与核心设备上的平台属性进行比较。C AWS IoT Greengrass ore 软件始终定义`os`和`architecture`，它可能会定义其他属性。部署 Greengrass Nucleus 组件时，您可以为核心设备指定自定义平台属性。有关更多信息，请参阅 [Greengrass Nucleus 组件](greengrass-nucleus-component.md)的[平台覆盖参数](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-platform-overrides)。  
对于每个键/值对，可以指定以下值之一：  
+ 一个精确的值，例如 `linux` 或 `windows`。必须以字母或数字开头。
+ `*`，可匹配任何值。当值不存在时，也可匹配。
+ Java 风格的正则表达式，例如 `/windows|linux/`。正则表达式必须以斜杠字符（`/`）开头和结尾。例如，正则表达式 `/.+/` 匹配任何非空值。
该对象包含以下信息：    
`runtime`  
此清单支持的平台的 [Greengrass Nucleus 运行时](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`  
（可选）您为此清单定义的平台属性。*Key*替换为平台属性的名称。 AWS IoT Greengrass Core 软件将此平台属性与您在 Greengrass nucleus 组件配置中指定的键值对进行匹配。有关更多信息，请参阅 [Greengrass Nucleus 组件](greengrass-nucleus-component.md)的[平台覆盖参数](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-platform-overrides)。  
使用反向域名格式以避免公司内部的域名冲突。例如，如果您的公司拥有 `example.com`，而您开展的是广播项目，则可以将自定义平台属性命名为 `com.example.radio.RadioModule`。这有助于避免公司内部的平台属性名称冲突。
例如，您可以定义平台属性 `com.example.radio.RadioModule`，根据核心设备上可用的无线电模块来指定不同的清单。每个清单可以包含适用于不同硬件配置的不同构件，因此您可以将最少的软件集部署到核心设备。  
  `Lifecycle`   
定义如何在此清单定义的平台上安装和运行组件的对象或字符串。您还可以定义适用于所有平台的[全局生命周期](#global-lifecycle-definition)。只有当要使用的清单没有指定生命周期时，核心设备才会使用全局生命周期。  
您可以在清单中定义该生命周期。您在此处指定的生命周期步骤仅适用于此清单所定义的平台。您还可以定义适用于所有平台的[全局生命周期](#global-lifecycle-definition)。
该对象或字符串包含以下信息：    
  `Setenv`   
（可选）提供给所有生命周期脚本的环境变量词典。您可以在每个生命周期脚本中使用 `Setenv` 覆盖这些环境变量。  
  `install`   
（可选）定义组件安装时要运行的脚本的对象或字符串。每次软件启动时， AWS IoT Greengrass Core 软件也会运行此生命周期步骤。  
如果 `install` 脚本以成功代码退出，则组件将进入 `INSTALLED` 状态。  
该对象或字符串包含以下信息：    
`Script`  <a name="recipe-lifecycle-script"></a>
待运行脚本。  
`RequiresPrivilege`  <a name="recipe-lifecycle-requiresprivilege"></a>
（可选）如果将此选项设置为`true`，则 AWS IoT Greengrass Core 软件将以运行 Greengrass nucleus 的用户而不是为此组件配置的系统用户的身份运行此生命周期脚本。当 nucleus 以 root 身份运行时，这会向脚本授予 root 权限。默认值为 `false`。  
`Skipif`  <a name="recipe-lifecycle-skipif"></a>
（可选）用于确定是否运行脚本的检查。您可以定义检查路径上是否有可执行文件或文件是否存在。如果输出为真，则 AWS IoT Greengrass Core 软件将跳过该步骤。选择以下检查之一：  
+ `onpath runnable` – 检查系统路径上是否有可运行对象。例如，如果 Python 3 可用，则使用 **onpath python3** 跳过此生命周期步骤。
+ `exists file` – 检查文件是否存在。例如，如果存在 `/tmp/my-configuration.db`，则使用 **exists /tmp/my-configuration.db** 可跳过此生命周期步骤。  
`Timeout`  <a name="recipe-lifecycle-timeout"></a>
（可选）在 AWS IoT Greengrass Core 软件终止进程之前，脚本可以运行的最长时间（以秒为单位）。  
默认值：120 秒  
`Setenv`  <a name="recipe-lifecycle-environment"></a>
（可选）提供给脚本的环境变量词典。这些环境变量会覆盖您在 `Lifecycle.Setenv` 中提供的变量。  
  `run`   
（可选）定义组件启动时要运行的脚本的对象或字符串。  
当此生命周期步骤运行时，组件进入 `RUNNING` 状态。如果 `run` 脚本以成功代码退出，则组件将进入 `STOPPING` 状态。若指定了 `shutdown` 脚本，则会运行；否则组件进入 `FINISHED` 状态。  
依赖此组件的组件将在此生命周期步骤运行时启动。要运行后台进程，例如依赖组件使用的服务，请改用 `startup` 生命周期步骤。  
当您部署具有 `run` 生命周期的组件时，核心设备可以在此生命周期脚本运行后立即报告部署已完成。因此，即使 `run` 生命周期脚本在运行后不久就失败了，也可成功完成部署。如果您希望部署状态取决于组件启动脚本的结果，请改用 `startup` 生命周期步骤。  
您只能定义一个 `startup` 或 `run` 生命周期。
该对象或字符串包含以下信息：    
`Script`  <a name="recipe-lifecycle-script"></a>
待运行脚本。  
`RequiresPrivilege`  <a name="recipe-lifecycle-requiresprivilege"></a>
（可选）如果将此选项设置为`true`，则 AWS IoT Greengrass Core 软件将以运行 Greengrass nucleus 的用户而不是为此组件配置的系统用户的身份运行此生命周期脚本。当 nucleus 以 root 身份运行时，这会向脚本授予 root 权限。默认值为 `false`。  
`Skipif`  <a name="recipe-lifecycle-skipif"></a>
（可选）用于确定是否运行脚本的检查。您可以定义检查路径上是否有可执行文件或文件是否存在。如果输出为 true，则 AWS IoT Greengrass Core 软件将跳过该步骤。选择以下检查之一：  
+ `onpath runnable` – 检查系统路径上是否有可运行对象。例如，如果 Python 3 可用，则使用 **onpath python3** 跳过此生命周期步骤。
+ `exists file` – 检查文件是否存在。例如，如果存在 `/tmp/my-configuration.db`，则使用 **exists /tmp/my-configuration.db** 可跳过此生命周期步骤。  
`Timeout`  <a name="recipe-lifecycle-timeout"></a>
（可选）在 AWS IoT Greengrass 核心软件终止进程之前，脚本可以运行的最大时间（以秒为单位）。  
默认情况下，此生命周期步骤不会超时。如果省略此超时，`run` 脚本将一直运行直到退出。  
`Setenv`  <a name="recipe-lifecycle-environment"></a>
（可选）提供给脚本的环境变量词典。这些环境变量会覆盖您在 `Lifecycle.Setenv` 中提供的变量。  
  `startup`   
（可选）定义组件启动时要运行的后台进程的对象或字符串。  
使用 `startup` 运行命令，该命令必须成功退出或将组件状态更新为 `RUNNING`，然后才能启动依赖组件。使用 [UpdateState](ipc-component-lifecycle.md#ipc-operation-updatestate)IPC 操作将组件的状态设置为`RUNNING`或`ERRORED`当组件启动未退出的脚本时。例如，您可以定义一个 `/etc/init.d/mysqld start` 启动 MySQL 进程的 `startup` 步骤。  
当此生命周期步骤运行时，组件进入 `STARTING` 状态。如果 `startup` 脚本以成功代码退出，则组件将进入 `RUNNING` 状态。然后，可以启动依赖组件。  
当您部署具有 `startup` 生命周期的组件时，核心设备可以在此生命周期脚本退出或报告其状态后将部署报告为已完成。换句话说，部署的状态 `IN_PROGRESS` 一直持续到所有组件的启动脚本退出或报告状态为止。  
您只能定义一个 `startup` 或 `run` 生命周期。
该对象或字符串包含以下信息：    
`Script`  <a name="recipe-lifecycle-script"></a>
待运行脚本。  
`RequiresPrivilege`  <a name="recipe-lifecycle-requiresprivilege"></a>
（可选）如果将此选项设置为`true`，则 AWS IoT Greengrass Core 软件将以运行 Greengrass nucleus 的用户而不是为此组件配置的系统用户的身份运行此生命周期脚本。当 nucleus 以 root 身份运行时，这会向脚本授予 root 权限。默认值为 `false`。  
`Skipif`  <a name="recipe-lifecycle-skipif"></a>
（可选）用于确定是否运行脚本的检查。您可以定义检查路径上是否有可执行文件或文件是否存在。如果输出为 true，则 AWS IoT Greengrass Core 软件将跳过该步骤。选择以下检查之一：  
+ `onpath runnable` – 检查系统路径上是否有可运行对象。例如，如果 Python 3 可用，则使用 **onpath python3** 跳过此生命周期步骤。
+ `exists file` – 检查文件是否存在。例如，如果存在 `/tmp/my-configuration.db`，则使用 **exists /tmp/my-configuration.db** 可跳过此生命周期步骤。  
`Timeout`  <a name="recipe-lifecycle-timeout"></a>
（可选）在 AWS IoT Greengrass Core 软件终止进程之前，脚本可以运行的最长时间（以秒为单位）。  
默认值：120 秒  
`Setenv`  <a name="recipe-lifecycle-environment"></a>
（可选）提供给脚本的环境变量词典。这些环境变量会覆盖您在 `Lifecycle.Setenv` 中提供的变量。  
  `shutdown`   
（可选）定义组件关闭时要运行的脚本的对象或字符串。使用关闭生命周期来执行要在组件处于 `STOPPING` 状态时运行的代码。关闭生命周期可用于停止 `startup` 或 `run` 脚本启动的进程。  
如果您在 `startup` 中启动后台进程，请使用 `shutdown` 步骤在组件关闭时停止该进程。例如，您可以定义一个使用 `/etc/init.d/mysqld stop` 停止 MySQL 进程的 `shutdown` 步骤。  
该 `shutdown` 脚本在组件进入 `STOPPING` 状态后运行。如果此脚本成功完成，组件将进入 `FINISHED` 状态。  
该对象或字符串包含以下信息：    
`Script`  <a name="recipe-lifecycle-script"></a>
待运行脚本。  
`RequiresPrivilege`  <a name="recipe-lifecycle-requiresprivilege"></a>
（可选）如果将此选项设置为`true`，则 AWS IoT Greengrass Core 软件将以运行 Greengrass nucleus 的用户而不是为此组件配置的系统用户的身份运行此生命周期脚本。当 nucleus 以 root 身份运行时，这会向脚本授予 root 权限。默认值为 `false`。  
`Skipif`  <a name="recipe-lifecycle-skipif"></a>
（可选）用于确定是否运行脚本的检查。您可以定义检查路径上是否有可执行文件或文件是否存在。如果输出为 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 核心软件终止进程之前，脚本可以运行的最大时间（以秒为单位）。  
默认值：15 秒。  
`Setenv`  <a name="recipe-lifecycle-environment"></a>
（可选）提供给脚本的环境变量词典。这些环境变量会覆盖您在 `Lifecycle.Setenv` 中提供的变量。  
  `uninstall`   
（可选）一个对象或字符串，用于定义从设备中永久删除组件时要运行的脚本。当部署移除组件时， AWS IoT Greengrass Core 软件会运行此步骤。此步骤不会在组件版本升级期间运行。  
当此生命周期步骤运行时，组件进入 `UNINSTALLING` 状态。如果卸载脚本失败或超时，则仍会删除该组件。卸载失败不会使部署失败。  
该对象或字符串包含以下信息：    
`Script`  <a name="recipe-lifecycle-script"></a>
待运行脚本。  
`RequiresPrivilege`  <a name="recipe-lifecycle-requiresprivilege"></a>
（可选）如果将此选项设置为`true`，则 AWS IoT Greengrass Core 软件将以运行 Greengrass nucleus 的用户而不是为此组件配置的系统用户的身份运行此生命周期脚本。当 nucleus 以 root 身份运行时，这会向脚本授予 root 权限。默认值为 `false`。  
`Skipif`  <a name="recipe-lifecycle-skipif"></a>
（可选）用于确定是否运行脚本的检查。您可以定义检查路径上是否有可执行文件或文件是否存在。如果输出为 true，则 AWS IoT Greengrass Core 软件将跳过该步骤。选择以下检查之一：  
+ `onpath runnable` – 检查系统路径上是否有可运行对象。例如，如果 Python 3 可用，则使用 **onpath python3** 跳过此生命周期步骤。
+ `exists file` – 检查文件是否存在。例如，如果存在 `/tmp/my-configuration.db`，则使用 **exists /tmp/my-configuration.db** 可跳过此生命周期步骤。  
`Timeout`  <a name="recipe-lifecycle-timeout"></a>
（可选）在 AWS IoT Greengrass Core 软件终止进程之前，脚本可以运行的最长时间（以秒为单位）。  
默认值：120 秒  
`Setenv`  <a name="recipe-lifecycle-environment"></a>
（可选）提供给脚本的环境变量词典。这些环境变量会覆盖您在 `Lifecycle.Setenv` 中提供的变量。  
  `recover`   
（可选）定义组件遇到错误时要运行的脚本的对象或字符串。  
此步骤在组件进入 `ERRORED` 状态时运行。如果组件三次变为 `ERRORED` 而没有成功恢复，组件就会变为 `BROKEN` 状态。要修复 `BROKEN` 组件，必须将其重新部署。  
该对象或字符串包含以下信息：    
`Script`  <a name="recipe-lifecycle-script"></a>
待运行脚本。  
`RequiresPrivilege`  <a name="recipe-lifecycle-requiresprivilege"></a>
（可选）如果将此选项设置为`true`，则 AWS IoT Greengrass Core 软件将以运行 Greengrass nucleus 的用户而不是为此组件配置的系统用户的身份运行此生命周期脚本。当 nucleus 以 root 身份运行时，这会向脚本授予 root 权限。默认值为 `false`。  
`Skipif`  <a name="recipe-lifecycle-skipif"></a>
（可选）用于确定是否运行脚本的检查。您可以定义检查路径上是否有可执行文件或文件是否存在。如果输出为 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 核心软件终止进程之前，脚本可以运行的最大时间（以秒为单位）。  
默认值：60 秒。  
`Setenv`  <a name="recipe-lifecycle-environment"></a>
（可选）提供给脚本的环境变量词典。这些环境变量会覆盖您在 `Lifecycle.Setenv` 中提供的变量。  
  `bootstrap`   
（可选）定义要求 AWS IoT Greengrass Core 软件或核心设备重新启动的脚本的对象或字符串。这样，您就可以开发一个组件，例如在安装操作系统更新或运行时更新后执行重启。  
要安装不需要重启 AWS IoT Greengrass 核心软件或设备的更新或依赖项，请使用[安装生命周期](#install-lifecycle-definition)。
在以下情况下，当 AWS IoT Greengrass 核心软件部署组件时，此生命周期步骤在安装生命周期步骤之前运行：  
+ 组件首次部署至核心设备。
+ 组件版本变更。
+ 引导脚本会因组件配置更新而改变。
 AWS IoT Greengrass 核心软件完成部署中包含引导步骤的所有组件的引导步骤后，软件将重新启动。  
必须将 AWS IoT Greengrass 核心软件配置为系统服务，才能重新启动 AWS IoT Greengrass 核心软件或核心设备。如果您未将 AWS IoT Greengrass Core 软件配置为系统服务，则该软件将无法重新启动。有关更多信息，请参阅 [将 Greengrass Nucleus 配置为系统服务](configure-greengrass-core-v2.md#configure-system-service)。
该对象或字符串包含以下信息：    
`BootstrapOnRollback`  
启用此功能后，`BootstrapOnRollback` 仅会在那些因目标部署失败而已经完成或尝试执行引导生命周期步骤的组件上运行。此功能适用于 Greengrass Nucleus 版本 2.12.0 及更高版本。
（可选）您可以将引导生命周期步骤作为回滚部署的一部分来运行。若您将此选项设置为 `true`，则将运行在回滚部署中定义的引导生命周期步骤。部署失败时，先前版本的组件引导生命周期将在回滚部署期间再次运行。  
默认值为 `false`。  
`Script`  
待运行脚本。此脚本的退出代码定义了重启指令。使用以下退出代码：  
+ `0`— 不要重启 AWS IoT Greengrass 核心软件或核心设备。在所有组件启动后， AWS IoT Greengrass Core 软件仍会重新启动。
+ `100`— 请求重新启动 AWS IoT Greengrass Core 软件。
+ `101` – 请求重启核心设备。
退出代码 100 至 199 保留给特殊行为使用。其他退出代码代表脚本错误。  
`RequiresPrivilege`  <a name="recipe-lifecycle-requiresprivilege"></a>
（可选）如果将此选项设置为`true`，则 AWS IoT Greengrass Core 软件将以运行 Greengrass nucleus 的用户而不是为此组件配置的系统用户的身份运行此生命周期脚本。当 nucleus 以 root 身份运行时，这会向脚本授予 root 权限。默认值为 `false`。  
`Timeout`  <a name="recipe-lifecycle-timeout"></a>
（可选）在 AWS IoT Greengrass Core 软件终止进程之前，脚本可以运行的最长时间（以秒为单位）。  
默认值：120 秒  
`Setenv`  <a name="recipe-lifecycle-environment"></a>
（可选）提供给脚本的环境变量词典。这些环境变量会覆盖您在 `Lifecycle.Setenv` 中提供的变量。  
  `Selections`   
（可选）选择键列表，用于指定要为此清单运行的[全局生命周期](#global-lifecycle-definition)的各个部分。在全局生命周期中，您可以使用任何级别的选择键来定义生命周期步骤，以选择生命周期的子部分。然后，核心设备使用与该清单中的选择键相匹配的部分。有关更多信息，请参阅[全局生命周期示例](#global-lifecycle-definition)。  
只有当该清单未定义生命周期时，核心设备才会使用全局生命周期中的选择。
您可以指定 `all` 选择键来运行全局生命周期中没有选择键的部分。  
  `Artifacts`   
（可选）对象列表，每个对象都定义了该清单所定义平台上组件的二进制工件。例如，您可以将代码或图像定义为构件。  
部署组件时， AWS IoT Greengrass Core 软件会将构件下载到核心设备上的文件夹。您也可以将构件定义为软件下载后提取的存档文件。  
您可以使用[配方变量](#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)来获取包含已提取存档构件的文件夹路径。C AWS IoT Greengrass ore 软件将每个存档提取到与存档同名的文件夹中。例如，在配方中指定 `{artifacts:decompressedPath}/my_archive/my_script.py` 以获取包含 URI `s3://amzn-s3-demo-bucket/path/to/my_archive.zip` 的存档构件 `my_script.py` 路径。
在本地核心设备上开发带有存档构件的组件时，可能没有该构件的 URI。要使用提取构件的 `Unarchive` 选项测试组件，请指定一个文件名与存档构件文件名匹配的 URI。您可以指定期望上传存档构件的 URI，也可以指定一个新的占位符 URI。例如，要在本地部署期间提取 `my_archive.zip` 构件，可以指定 `s3://amzn-s3-demo-bucket/my_archive.zip`。
每个对象包含以下信息：    
`Uri`  
S3 存储桶中的构件 URI。安装组件时， AWS IoT Greengrass Core 软件会从此 URI 中获取工件，除非该构件已存在于设备上。在每个清单中，每个构件都必须有一个唯一的文件名。  
`Unarchive`  
（可选）要解压缩的档案类型。从以下选项中进行选择：  
+ `NONE` – 该文件不是要解压的存档。 AWS IoT Greengrass Core 软件将构件安装至核心设备上的文件夹。您可以使用 [artifacts:path 配方变量](#component-recipe-artifacts-path)来获取此文件夹的路径。
+ `ZIP` – 该文件是一个 ZIP 存档。C AWS IoT Greengrass ore 软件将存档提取到与存档同名的文件夹。您可以使用 [artifacts:decompressedPath 配方变量](#component-recipe-artifacts-decompressed-path)来获取包含此文件夹的文件夹路径。
默认值为 `NONE`。  
  `Permission`   
（可选）定义为此构件文件设置的访问权限的对象。您可以设置读取权限和执行权限。  
您无法设置写入权限，因为 AWS IoT Greengrass 核心软件不允许组件编辑构件文件夹中的构件文件。要编辑组件中的构件文件，请将其复制到其他位置或发布并部署新的构件文件。
如果您将工件定义为要解压的存档，则 AWS IoT Greengrass Core 软件会对其从存档中解压缩的文件设置这些访问权限。C AWS IoT Greengrass ore 软件将文件夹的访问权限设置`ALL`为`Read`和`Execute`。这样，组件就可以查看文件夹中的解压文件。要为存档中的单个文件设置权限，可以在[安装生命周期脚本](#install-lifecycle-definition)中设置权限。  
该对象包含以下信息：    
`Read`  
（可选）要为此构件文件设置的读取权限。要允许其他组件访问此构件，例如依赖于此组件的组件，请指定 `ALL`。从以下选项中进行选择：  
+ `NONE` – 文件不可读。
+ `OWNER` – 您配置为运行此组件的系统用户可以读取该文件。
+ `ALL` – 所有用户均可读取该文件。
默认值为 `OWNER`。  
`Execute`  
（可选）要为此构件文件设置的运行权限。`Execute` 权限意味着 `Read` 权限。例如，如果您将 `Execute` 指定为 `ALL`，则所有用户都可以读取和运行此构件文件。  
从以下选项中进行选择：  
+ `NONE` – 该文件无法运行。
+ `OWNER` – 该文件可由您配置为运行该组件的系统用户运行。
+ `ALL` – 所有用户均可运行该文件。
默认值为 `NONE`。  
`Digest`  
（只读）构件的加密摘要哈希值。创建组件时， AWS IoT Greengrass 使用哈希算法计算构件文件的哈希值。然后，在部署组件时，Greengrass Nucleus 会计算已下载构件的哈希值，并将哈希值与该摘要进行比较，以便在安装之前验证构件。如果哈希值与摘要不匹配，则部署失败。  
如果您设置了此参数，则 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
```

## 配方变量
<a name="recipe-variables"></a>

配方变量显示来自当前组件和核心的信息，供您在配方中使用。例如，您可以使用配方变量将组件配置参数传递给在生命周期脚本中运行的应用程序。

您可以在组件配方的以下部分中使用配方变量：
+ 生命周期定义。
+ 组件配置定义，前提是您使用 [Greengrass](greengrass-nucleus-component.md) nucleus v2.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 仅在组件生命周期定义中支持此配方变量。
此配方变量的输入如下：  
+ <a name="recipe-variable-component-dependency-name"></a>`component_dependency_name` –（可选）要查询的组件依赖关系名称。省略此段可查询此配方定义的组件。您只能指定直接依赖关系。
+ `json_pointer` – 指向要评估的配置值的 JSON 指针。JSON 指针以正斜杠 `/` 开头。要识别嵌套组件配置中的值，请使用正斜杠 (`/`) 分隔配置中每一级的键。您可以使用数字作为键来指定列表中的索引。有关更多信息，请参阅 [JSON 指针规范](https://tools.ietf.org/html/rfc6901)。

  AWS IoT Greengrass Core 使用 JSON 指针获取 YAML 格式的食谱。
JSON 指针可以引用以下节点类型：  
+ 一个值节点。 AWS IoT Greengrass Core 将配方变量替换为该值的字符串表示形式。空值转换为 `null` 字符串。
+ 一个对象节点。 AWS IoT Greengrass Core 将配方变量替换为该对象的序列化 JSON 字符串表示形式。
+ 没有节点。 AWS IoT Greengrass Core 不会替换配方变量。
例如，`{configuration:/Message}` 配方变量检索组件配置中 `Message` 键的值。`{com.example.MyComponentDependency:configuration:/server/port}` 配方变量检索组件依赖关系的 `server` 配置对象中 `port` 的值。

  `component_dependency_name:artifacts:path`   
此配方定义的组件或该组件所依赖的组件的构件根路径。  
安装组件时，会将该组件的构件 AWS IoT Greengrass 复制到此变量公开的文件夹。例如，您可以使用此变量来标识要在组件生命周期中运行的脚本的位置。  
<a name="recipe-variable-artifact-folder-permissions"></a>此路径下的文件夹为只读文件夹。要修改构件文件，请将文件复制到其他位置，例如当前工作目录（`$PWD` 或 `.`）。然后，修改那里的文件。  
<a name="recipe-variable-component-dependency-artifact-file-permissions"></a>要从组件依赖关系中读取或运行构件，则该构件 `Read` 或 `Execute` 权限必须是 `ALL`。有关更多信息，请参阅您在组件配方中定义的[构件权限](#component-artifact-permission)。  
此配方变量的输入如下：  
+ <a name="recipe-variable-component-dependency-name"></a>`component_dependency_name` –（可选）要查询的组件依赖关系名称。省略此段可查询此配方定义的组件。您只能指定直接依赖关系。

  `component_dependency_name:artifacts:decompressedPath`   
此配方定义的组件或该组件所依赖的组件的解压存档构件的根路径。  
安装组件时，将该组件的存档工件 AWS IoT Greengrass 解压缩到此变量公开的文件夹。例如，您可以使用此变量来标识要在组件生命周期中运行的脚本的位置。  
每个构件都会解压至解压路径内的一个文件夹，该文件夹与构件同名，但没有扩展名。例如，名为 `models.zip` 的 ZIP 构件解压至 `{artifacts:decompressedPath}/models` 文件夹。  
<a name="recipe-variable-artifact-folder-permissions"></a>此路径下的文件夹为只读文件夹。要修改构件文件，请将文件复制到其他位置，例如当前工作目录（`$PWD` 或 `.`）。然后，修改那里的文件。  
<a name="recipe-variable-component-dependency-artifact-file-permissions"></a>要从组件依赖关系中读取或运行构件，则该构件 `Read` 或 `Execute` 权限必须是 `ALL`。有关更多信息，请参阅您在组件配方中定义的[构件权限](#component-artifact-permission)。  
此配方变量的输入如下：  
+ <a name="recipe-variable-component-dependency-name"></a>`component_dependency_name` –（可选）要查询的组件依赖关系名称。省略此段可查询此配方定义的组件。您只能指定直接依赖关系。

  `component_dependency_name:work:path`   
此功能适用于 [Greengrass Nucleus 组件](greengrass-nucleus-component.md)的 v2.0.4 及更高版本。  
此配方定义的组件或该组件所依赖的组件的工作路径。从组件的上下文运行时，此配方变量的值等同于 `$PWD` 环境变量和 [pwd](https://en.wikipedia.org/wiki/Pwd) 命令的输出。  
您可以使用此配方变量在组件和依赖关系之间共享文件。  
此路径下的文件夹可由此配方定义的组件以及以同一用户和组身份运行的其他组件进行读写操作。  
此配方变量的输入如下：  
+ <a name="recipe-variable-component-dependency-name"></a>`component_dependency_name` –（可选）要查询的组件依赖关系名称。省略此段可查询此配方定义的组件。您只能指定直接依赖关系。

`kernel:rootPath`  
 AWS IoT Greengrass 核心根路径。

`iot:thingName`  
此功能适用于 [Greengrass Nucleus 组件](greengrass-nucleus-component.md)的 v2.3.0 及更高版本。  
核心设备的名称 AWS IoT 。

## 配方示例
<a name="recipe-examples"></a>

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

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 组件配方
<a name="recipe-example-hello-world"></a>

以下配方描述了一个运行 Python 脚本的 Hello World 组件。该组件支持所有平台，接受 AWS IoT Greengrass 作为实参传递给 Python 脚本的 `Message` 参数。这是[入门教程](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 运行时组件示例
<a name="recipe-example-python-runtime"></a>

以下配方描述了一个安装 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
```

------

### 指定多个字段的组件配方
<a name="recipe-example-all-fields"></a>

以下组件配方使用多个配方字段。

------
#### [ 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'
```

------