准备 Amazon IoT Jobs - Amazon IoT Core
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

准备 Amazon IoT Jobs

Amazon IoT Device Management 软件包目录通过替换参数以及与 Amazon IoT 实例集索引集成、动态事物组和 Amazon IoT 事物的预留命名影子来扩展 Amazon IoT Jobs。

注意

要使用软件包目录提供的所有功能,您必须创建以下 Amazon Identity and Access Management(IAM)角色和策略:用于部署软件包版本的 Amazon IoT Jobs 权限用于更新预留命名影子的 Amazon IoT Jobs 权限。有关更多信息,请参阅准备安全性

Amazon IoT 任务的替代参数

您可以在 Amazon IoT 任务文档中使用替代参数作为占位符。当任务服务遇到替代参数时,它会将任务指向指定软件版本的属性以获取参数值。您可以使用此过程创建单个任务文档,并通过通用属性将元数据传递到任务中。例如,您可以通过软件包版本属性,将 Amazon Simple Storage Service (Amazon S3) URL、软件包 Amazon 资源名称(ARN)或签名传递到任务文档中。

在作业文档中,替代参数的格式应如下所示:

  • 软件包名称和软件包版本

    • package::version 之间的空字符串表示软件包名称替代参数。version::attribute 之间的空字符串表示软件包版本替代参数。有关在作业文档中使用软件包名称和软件包版本替代参数的信息,请参阅以下示例:${aws:iot:package::version::attributes:<attributekey>}

    • 作业文档将使用软件包版本详情中的版本 ARN 自动填充这些替代参数。如果您使用 API 或 CLI 命令为单个软件包部署创建作业或作业模板,则软件包版本的版本 ARNCreateJobDescribeJob 中用参数 destinationPackageVersions 表示。

  • 软件包版本的所有属性

    • 有关在作业文档中使用软件包版本替代参数所有属性的信息,请参阅以下示例:${aws:iot:package:<packageName>:version:<versionName>:attributes}

注意

软件包名称、软件包版本以及所有属性替代参数可以一起使用。有关在作业文档中使用所有三个替代参数的信息,请参阅以下示例:${aws:iot:package::version::attributes}

在以下示例中,有一个名为 samplePackage 的软件包,它有一个名为 2.1.5 的软件包版本,该版本具有以下属性:

  • 名称:s3URL,值:https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile

    • 此属性标识存储在 Amazon S3 中的代码文件的位置。

  • 名称:signature,值:aaaaabbbbbcccccdddddeeeeefffffggggghhhhhiiiiijjjj

    • 此属性提供了设备所需的作为安全措施的代码签名值。有关更多信息,请参阅任务的代码签名注意:此属性是一个示例,而不是软件包目录或任务的必需属性。

对于 s3URL,任务文档参数编写如下:

{ "samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:s3URL}" }

对于 signature,任务文档参数编写如下:

{ "samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:signature}" }

完整的任务文档编写如下:

{ ... "Steps": { "uninstall": ["samplePackage"], "download": [ { "samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:s3URL}" }, ], "signature": [ "samplePackage" : "${aws:iot:package:samplePackage1:version:2.1.5:attributes:signature}" ] } }

完成替换后,将以下任务文档部署到设备上:

{ ... "Steps": { "uninstall": ["samplePackage"], "download": [ { "samplePackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile" }, ], "signature": [ "samplePackage" : "aaaaabbbbbcccccdddddeeeeefffffggggghhhhhiiiiijjjj" ] } }

替代参数(之前和之后的视图)

替代参数使用各种标志(例如,对默认软件包版本使用 $default)简化作业文档的创建。这样就无需为每个作业部署手动输入特定的软件包版本元数据,因为这些标志会自动填充特定软件包版本中引用的元数据。有关软件包版本属性(例如代表默认软件包版本的 $default)的更多信息,请参阅准备任务文档和软件包版本以进行部署

在 Amazon Web Services Management Console中,在软件包版本的作业部署期间,切换部署指令文件编辑器窗口中的预览替代按钮,可查看有替代参数和没有替代参数的作业文档。

使用 DescribeJobGetJobDocument API 中的“before-substitution”参数可以查看移除替代参数之前和之后的 API 响应。请参阅 DescribeJobGetJobDocument API 的以下示例:

  • DescribeJob

    • 默认视图

      { "jobId": "<jobId>", "description": "<description>", "destinationPackageVersions": ["arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/1.0.2"] }
    • 使用替代参数之前的视图

      { "jobId": "<jobId>", "description": "<description>", "destinationPackageVersions": ["arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/$default"] }
  • GetJobDocument

    • 默认视图

      { "attributes": { "location": "prod-artifacts.s3.us-east-1.amazonaws.com/mqtt-core", "signature": "IQoJb3JpZ2luX2VjEIrwEaCXVzLWVhc3QtMSJHMEUCIAofPNPpZ9cI", "streamName": "mqtt-core", "fileId": "0" }, }
    • 使用替代参数之前的视图

      { "attributes": "${aws:iot:package:TestPackage:version:$default:attributes}", }

有关 Amazon IoT Jobs、创建任务文档和部署任务的更多信息,请参阅任务

准备任务文档和软件包版本以进行部署

创建软件包版本时,它处于 draft 状态,表示正准备部署。要准备好软件包版本进行部署,您必须创建作业文档,将文档保存到作业可以访问的位置(例如 Amazon S3),确认软件包版本具有您希望作业文档使用的属性值。(注意:仅当软件包版本处于 draft 状态时,您才可以更新其属性。)

为单个软件包部署创建 Amazon IoT 作业或作业模板时,您可以使用以下选项自定义作业文档:

部署指令文件(recipe

  • 软件包版本的部署指令文件包含用于将软件包版本部署到多台设备的部署指令,其中包括内联作业文档。该文件将特定的部署指令与软件包版本相关联,以实现快速高效的作业部署。

    在 Amazon Web Services Management Console中,您可以在创建新软件包工作流的部署指令文件预览窗口中,通过版本部署配置选项卡来创建文件。您可以利用 Amazon IoT 自动生成指令文件,具体方法是利用从 Amazon IoT 推荐的文件开始通过软件包版本属性,或者利用使用您自己的部署指令文件,使用存储在 Amazon S3 存储桶中的现有作业文档。

    注意

    如果您使用自己的作业文档,则可以在部署指令文件预览窗口中直接对其进行更新,但它不会自动更新存储在 Amazon S3 存储桶中的原始作业文档。

    使用 Amazon CLI 或 CreatePackageVersionGetPackageVersionUpdatePackageVersion 等 API 命令时,recipe 表示部署指令文件,其中包括内联作业文档。

    有关什么是作业文档的更多信息,请参阅基本概念

    有关通过 recipe 表示的部署指令文件,请参阅以下示例:

    { "packageName": "sample-package-name", "versionName": "sample-package-version", ... "recipe": "{...}" }
    注意

    当软件包版本处于 published 状态时,通过 recipe 表示的部署指令文件可以进行更新,因为该文件与软件包版本元数据是分开的。其在作业部署期间将变为不可变。

Artifact 版本属性

  • 在软件包版本中使用 artifact 版本属性,您可以为软件包版本构件添加 Amazon S3 位置。当使用 Amazon IoT Jobs 触发软件包版本的作业部署时,作业文档中的预签名 URL 占位符 ${aws:iot:package:<packageName>:version:<versionName>:artifact-location:s3-presigned-url} 将使用 Amazon S3 存储桶、存储桶密钥和存储在 Amazon S3 存储桶中的文件版本进行更新。存储软件包版本构件的 Amazon S3 存储桶必须位于创建软件包版本的区域中。

    注意

    要将同一文件的多个对象版本存储在您的 Amazon S3 存储桶中,您必须在存储桶上启用版本控制。有关更多信息,请参阅在存储桶上启用版本控制

    要在使用 CreatePackageVersionUpdatePackageVersion API 操作时访问 Amazon S3 存储桶中的软件包版本构件,您必须具有以下权限:

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "s3:GetObjectVersion", "Resource": "arn:<partition>:s3:::<bucket>/<key>" } ] }

    有关 CreatePackageVersionUpdatePackageVersion API 操作中的版本属性 artifact 的更多信息,请参阅 CreatePackageVersionUpdatePackageVersion

    请参阅以下示例,该示例显示了在创建新软件包版本时支持 Amazon S3 中构件位置的版本属性 artifact

    { "packageName": "sample package name", "versionName": "1.0", "artifact": { "s3Location": { "bucket": "firmware", "key": "image.bin", "version": "12345" } } }
    注意

    当软件包版本从状态 draft 更新为 published 状态时,软件包版本属性和构件位置将变为不可变。要更新此信息,您需要创建一个新的软件包版本,并在 draft 状态下执行这些更新。

软件包版本

  • 默认软件包版本可以通过软件包的可用版本表示,提供安全稳定的软件包版本。使用 Amazon IoT Jobs 将默认软件包版本部署到您的设备实例集时,这将作为软件包的基准版本。在创建作业以部署软件包的 $default 软件包版本时,作业文档和新作业部署中的软件包版本必须与 $default 相匹配。对于 API 和 CLI 命令,作业部署中的软件包版本表示为 destinationPackageVersions,而在 Amazon Web Services Management Console 中,表示为 VersionARN。作业文档中的软件包版本用以下作业文档占位符表示,如下所示:

    arn:aws:iot:<regionCode>:111122223333:package/<packageName>/version/$default

    要使用默认软件包版本创建作业或作业模板,请在 CreateJobCreateJobTemplate API 命令中使用 $default 标志,如下所示:

    "$ aws iot create-job \ --destination-package-versions "arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/$default" --document file://jobdoc.json
    注意

    引用默认版本的 $default 软件包版本属性是一个可选属性,只有在通过 Amazon IoT Jobs 引用作业部署的默认软件包版本时才需要该属性。

对软件包版本感到满意后,通过 Amazon IoT 控制台中的软件包详细信息页面,或通过执行 UpdatePackageVersion API 操作来发布该软件包版本。然后,您可以在通过 Amazon IoT 控制台或执行 CreateJob API 操作创建作业时引用软件包版本。

部署时指定软件包和版本

要将软件包版本部署到设备,请确认作业文档中引用的软件包和软件包版本与 CreateJob API 操作的 destinationPackageVersions 参数中所述的软件包和软件包版本相匹配。如果它们不匹配,您将收到一条错误消息,提示您确保两个引用匹配。有关软件包目录错误消息的更多信息,请参阅一般错误消息疑难解答

除了作业文档中引用的软件包和软件包版本外,您还可以在 CreateJob API 操作的 destinationPackageVersions 参数中包含作业文档中未引用的其他软件包和软件包版本。确保作业文档中包含必要的安装信息,以便设备正确安装其他软件包版本。有关 CreateJob API 操作的更多信息,请参阅 CreateJob

通过 Amazon IoT 动态事物组定位任务

软件包目录与实例集索引Amazon IoT 任务Amazon IoT 动态事物组配合使用来筛选和定位实例集中的设备,以选择要部署到设备上的软件包版本。您可以根据设备当前的软件包信息运行实例集索引查询,并将这些事物作为 Amazon IoT 任务的目标。您也可以发布软件更新,但只能发布到符合条件的目标设备。例如,您可以指定只想将配置部署到当前运行 iot-device-client 1.5.09 的设备。有关更多信息,请参阅创建动态事物组

预留命名影子和软件包版本

如果已配置,Amazon IoT Jobs 可以在任务成功完成时更新事物的预留命名影子($package)。如果这样做,则无需手动将软件包版本与事物的预留命名影子相关联。

在以下情况下,您可以选择手动将软件包版本关联或更新到事物的预留命名影子:

  • 您无需关联已安装的软件包版本,即可向 Amazon IoT Core 注册事物。

  • Amazon IoT Jobs 未配置为更新事物的预留命名影子。

  • 您使用内部流程将软件包版本分派到您的实例集,该流程在完成后不会更新 Amazon IoT Core。

注意

我们建议您使用 Amazon IoT Jobs 更新预留命名影子($package)中的软件包版本。当 Amazon IoT Jobs 也配置为更新影子时,通过其它流程(例如手动或编程 API 调用)更新 $package 影子中的版本参数可能会导致设备上的实际版本与报告给预留命名影子的版本不一致。

您可以通过控制台或 UpdateThingShadow API 操作,将软件包版本添加到或更新为预留命名影子($package)。有关更多信息,请参阅将软件包版本与 Amazon IoT 事物关联

注意

将软件包版本与 Amazon IoT 事物关联不会直接更新设备软件。必须将软件包版本部署到设备才能更新设备软件。

卸载软件包及其软件包版本

$null 是一个预留占位符,它会提示 Amazon IoT Jobs 服务从设备的预留命名影子 $package 中删除现有软件包和软件包版本。有关更多信息,请参阅预留命名影子

要使用此功能,请将 destinationPackageVersion Amazon 资源名称(ARN)末尾的版本名称替换为 $null。之后,您必须指示您的服务从设备中删除该软件。

授权的 ARN 使用以下格式:

arn:aws:iot:<regionCode>:111122223333:package/<packageName>/version/$null

例如,

$ aws iot create-job \ ... \ --destinationPackageVersions ["arn:aws:iot:us-east-1:111122223333:package/samplePackage/version/$null"]