AWS IoT 任务的替代参数准备任务文档和软件包版本以进行部署部署时指定软件包和版本通过 AWS IoT 动态事物组定位工作预留命名影子和软件包版本卸载软件包

准备 AWS IoT 作业

AWS IoT Device Management Software Package Catalog 通过替换参数以及与 AWS IoT 舰队索引、动态事物组和 AWS IoT 事物的保留名为 shadow 的集成来扩展 AWS IoT 任务。

注意

要使用 Software Package Catalog 提供的所有功能，必须创建以下 AWS Identity and Access Management (IAM) 角色和策略：AWS IoT 部署软件包版本的AWS IoT 作业权限和更新保留的命名影子的作业权限。有关更多信息，请参阅准备安全性。

AWS IoT 任务的替代参数

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

替换参数在作业文档中的格式应如下所示：

软件包名称和软件包版本
- 之间的空字符串package::version表示软件包名称替换参数。之间的空字符串version::attribute表示软件包版本替换参数。有关在作业文档中使用软件包名称和软件包版本替换参数的信息，请参阅以下示例:. ${aws:iot:package::version::attributes:<attributekey>}
- 作业文档将使用软件包版本详细信息ARN中的版本自动填充这些替代参数。如果您使用或CLI命令为单包部署创建任务API或作业模板，则包版本ARN的版本由CreateJob和DescribeJob中的destinationPackageVersions参数表示。
Software Package 版本的所有属性
- 有关在作业文档中使用软件包版本替换参数的所有属性的信息，请参阅以下示例：${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更多信息，请参阅准备任务文档和软件包版本以进行部署。

在中 AWS Management Console，在任务部署包版本期间，切换部署指令文件编辑器窗口中的预览替换按钮，以查看带有和不带替换参数的作业文档。

使用DescribeJob和中的 “替换之前” 参数 GetJobDocumentAPIs，您可以查看移除替换参数之前和之后的API响应。请参考以下带有DescribeJob和的示例 GetJobDocumentAPIs：

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}",
}

有关 AWS IoT 作业、创建作业文档和部署作业的更多信息，请参阅作业。

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

创建软件包版本时，其draft状态表示正在准备部署。要为部署准备包版本，您必须创建任务文档，将文档保存到任务可以访问的位置（例如 Amazon S3），并确认包版本具有您希望任务文档使用的属性值。（注意：您只能在软件包版本draft处于状态时更新其属性。）

为单包部署创建 Job 或 Job 模板时，您可以使用以下选项自定义任务文档： AWS IoT

部署指令文件 (recipe)

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

在中 AWS Management Console，您可以在 “部署说明” 文件预览窗口的 “创建新包” 工作流程的 “版本部署配置” 选项卡中创建文件。您可以使用从 AWS IoT 推荐文件开始使用包版本属性自动生成说明文件，或者使用您自己的部署说明文件使用存储在 Amazon S3 存储桶中的现有任务文档。 AWS IoT

注意
如果您使用自己的任务文档，则可以在部署说明文件预览窗口中直接对其进行更新，但它不会自动更新存储在 Amazon S3 存储桶中的原始任务文档。

使用 AWS CLI 或API命令时CreatePackageVersion，例如GetPackageVersionUpdatePackageVersion、或，recipe表示部署指令文件，其中包括内联作业文档。

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

有关部署指令文件，请参阅以下示例，如下所示recipe：
```
{
    "packageName": "sample-package-name",
    "versionName": "sample-package-version",
    ...
    "recipe": "{...}"
}
```
注意
当包版本处于published状态状态时，recipe可以更新所表示的部署指令文件，因为该文件与包版本元数据是分开的。它在任务部署期间变得不可变。

Artifact版本属性

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

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

要在使用CreatePackageVersion或UpdatePackageVersionAPI操作时访问 Amazon S3 存储桶中的软件包版本项目，您必须具有以下权限：
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:GetObjectVersion",
            "Resource": "arn:<partition>:s3:::<bucket>/<key>"
        }
    ]
}
```
有关CreatePackageVersion和UpdatePackageVersionAPI操作artifact中版本属性的更多信息，请参阅CreatePackageVersion和UpdatePackageVersion。

请参阅以下示例，该示例显示了在创建新包版本时artifact支持 Amazon S3 中构件位置的版本属性：
```
{
    "packageName": "sample package name",
    "versionName": "1.0",
    "artifact": {
        "s3Location": {
            "bucket": "firmware",
            "key": "image.bin",
            "version": "12345"
        }
    }
}
```
注意
当软件包版本从状态状态更新到draft状态状态时，软件包版本属性和artificats的位置将变为不可变。published要更新此信息，您需要创建一个新的软件包版本并在draft状态下执行这些更新。

Package 版本

默认软件包版本可以在软件包的可用版本中表示，提供安全稳定的软件包版本。使用 AWS IoT Jobs 将默认软件包版本部署到设备队列时，这是软件包的基准版本。在创建任务以部署软件$default包的软件包版本时，任务文档和新任务部署中的软件包版本必须与 as 相匹配$default。任务部署中的软件包版本由 destinationPackageVersions for API 和 co CLI mmands 表示，VersionARN在 AWS Management Console。作业文档中的包版本由以下作业文档占位符表示，如下所示：
```
arn:aws:iot:<regionCode>:111122223333:package/<packageName>/version/$default
```
要使用默认包版本创建任务或作业模板，CreateJobTemplateAPI请在CreateJob或命令中使用$default标志，如下所示：
```
"$ aws iot create-job \
    --destination-package-versions "arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/$default"
    --document file://jobdoc.json
```
注意
引用默认版本的$default软件包版本属性是一个可选属性，只有在通过 AWS IoT 作业为任务部署引用默认包版本时才需要该属性。

如果您对软件包版本感到满意，请通过 AWS IoT 控制台中的软件包详细信息页面或通过发布UpdatePackageVersionAPI操作进行发布。然后，您可以在创建任务时通过 AWS IoT 控制台或通过发出CreateJobAPI操作来引用软件包版本。

部署时指定软件包和版本

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

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

通过 AWS IoT 动态事物组定位工作

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

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

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

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

您 AWS IoT Core 无需关联已安装的软件包版本即可向其注册事物。
AWS IoT 未将作业配置为更新事物的预留名为 shadow。
您使用内部流程将软件包版本发送到您的车队，该流程 AWS IoT Core 在完成后不会更新。

注意

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

您可以通过控制台或UpdateThingShadowAPI操作将包版本添加到名为 shadow ($package) 的已保留内容中，或将其更新。有关更多信息，请参阅将包版本与 AWS IoT 事物关联。

注意

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

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

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

要使用此功能，请将 destinationPackageVersionAmazon 资源名称 (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"]

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

准备实例集索引

开始使用