本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 准备 Amazon IoT 工作 Amazon IoT Device Management Software Package Catalog 通过替换参数以及与 Amazon IoT 舰队索引、动态事物组和 Amazon IoT 事物的保留名为 shadow 的集成来扩展作 Amazon IoT 业。 **注意** 要使用 Software Package Catalog 提供的所有功能，您必须创建[以下 Amazon Identity and Access Management (IAM) 角色和策略：Amazon IoT 部署软件包版本](https://docs.amazonaws.cn/iot/latest/developerguide/preparing-security.html#job-rights-deploy-versions)的[Amazon IoT 任务权限和更新保留名为 shadow 的](https://docs.amazonaws.cn/iot/latest/developerguide/preparing-security.html#job-rights-update-reserved-named-shadow)任务权限。有关更多信息，请参阅[准备安全性](https://docs.amazonaws.cn/iot/latest/developerguide/preparing-security.html)。 ## Amazon IoT 任务的替代参数 您可以在 Amazon IoT 工作文档中使用替代参数作为占位符。当任务服务遇到替代参数时，它会将任务指向指定软件版本的属性以获取参数值。您可以使用此过程创建单个任务文档，并通过通用属性将元数据传递到任务中。例如，您可以通过程序包版本属性，将 Amazon Simple Storage Service（Amazon S3）URL、软件包 Amazon 资源名称（ARN）或签名传递到任务文档中。 在任务文档中，替代参数的格式应如下所示： + **软件包名称和程序包版本** + `package::version` 之间的空字符串表示软件包名称替代参数。`version::attribute` 之间的空字符串表示程序包版本替代参数。有关在任务文档中使用软件包名称和程序包版本替代参数的信息，请参阅以下示例：`${aws:iot:package::version::attributes:{{}}}`。 + 任务文档将使用程序包版本详情中的*版本 ARN* 自动填充这些替代参数。如果您使用 API 或 CLI 命令为单个软件包部署创建任务或任务模板，则程序包版本的*版本 ARN* 在 `CreateJob` 和 `DescribeJob` 中用参数 `destinationPackageVersions` 表示。 + **程序包版本的所有属性** + 有关在任务文档中使用程序包版本替代参数所有属性的信息，请参阅以下示例：`${aws:iot:package:{{}}:version:{{}}:attributes}` **注意** 软件包名称、程序包版本以及所有属性替代参数可以一起使用。有关在任务文档中使用所有三个替代参数的信息，请参阅以下示例：`${aws:iot:package::version::attributes}` 在以下示例中，有一个名为 `samplePackage` 的软件包，它有一个名为 `2.1.5` 的程序包版本，该版本具有以下属性： + 名称：`s3URL`，值：`https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile` + 此属性标识存储在 Amazon S3 中的代码文件的位置。 + 名称：`signature`，值：`aaaaabbbbbcccccdddddeeeeefffffggggghhhhhiiiiijjjj` + 此属性提供了设备所需的作为安全措施的代码签名值。有关更多信息，请参阅[任务的代码签名](https://docs.amazonaws.cn/iot/latest/developerguide/create-manage-jobs.html#create-manage-jobs-code-signing)。**注意：**此属性是一个示例，而不是软件包目录或任务的必需属性。 对于 `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`）的更多信息，请参阅 [准备任务文档和程序包版本以进行部署](#preparing-to-deploy)。 在中 Amazon Web Services 管理控制台，在任务部署包版本期间，切*换*部署指令文件编辑器*窗口中的预览*替换按钮，以查看带有和不带替换参数的作业文档。 使用`DescribeJob`和中的 “替换之前” 参数 `GetJobDocument` APIs，您可以查看移除替换参数之前和之后的 API 响应。请参考以下带有`DescribeJob`和的示例 `GetJobDocument` APIs： + `DescribeJob` + 默认视图 ``` { "jobId": "", "description": "", "destinationPackageVersions": ["arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/1.0.2"] } ``` + 使用替代参数之前的视图 ``` { "jobId": "", "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 作业、创建作业文档和部署作业的更多信息，请参阅[作业](https://docs.amazonaws.cn/iot/latest/developerguide/iot-jobs.html)。 ## 准备任务文档和程序包版本以进行部署 创建程序包版本时，它处于 `draft` 状态，表示正准备部署。要准备好程序包版本进行部署，您必须创建任务文档，将文档保存到任务可以访问的位置（例如 Amazon S3），确认程序包版本具有您希望任务文档使用的属性值。（注意：仅当程序包版本处于 `draft` 状态时，您才可以更新其属性。） 在为单包部署创建 Job 或 Job 模板时，您可以使用以下选项自定义任务文档： Amazon IoT **部署指令文件 (`recipe`)** + 程序包版本的部署指令文件包含用于将程序包版本部署到多台设备的部署指令，其中包括内联任务文档。该文件将特定的部署指令与程序包版本相关联，以实现快速高效的任务部署。 在中 Amazon Web Services 管理控制台，您可以在 “*部署说明” 文件预览*窗口的 “创建新包” 工作流程的 “*版本部署配置*” 选项卡中创建文件。您可以使用*从 Amazon IoT 推荐文件开始使用包版本属性自动生成说明文件，或者使用*您自己的部署说明文件**使用存储在 Amazon S3 存储桶中的现有任务文档。 Amazon IoT **注意** 如果您使用自己的任务文档，则可以在*部署指令文件预览*窗口中直接对其进行更新，但它不会自动更新存储在 Amazon S3 存储桶中的原始任务文档。 使用 Amazon CLI 或 API 命令时`CreatePackageVersion`，例如`GetPackageVersion``UpdatePackageVersion`、或，`recipe`表示部署指令文件，其中包括内联作业文档。 有关什么是任务文档的更多信息，请参阅 [基本概念](key-concepts-jobs.md#basic-concepts-jobs)。 有关通过 `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 存储桶中，您必须在存储桶上启用版本控制。有关更多信息，请参阅[在存储桶上启用版本控制](https://docs.amazonaws.cn/AmazonS3/latest/userguide/manage-versioning-examples.html)。 要在使用 `CreatePackageVersion` 或 `UpdatePackageVersion` API 操作时访问 Amazon S3 存储桶中的程序包版本构件，您必须具有以下权限： **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "s3:GetObjectVersion", "Resource": "arn:aws:s3:::{{bucket-name}}/{{key-name}}" } ] } ``` 有关`CreatePackageVersion`和 `UpdatePackageVersion` API 操作`artifact`中版本属性的更多信息，请参阅[CreatePackageVersion](https://amazonaws.com.cn/iot/latest/apireference/API_CreatePackageVersion.html)和[UpdatePackageVersion](https://docs.amazonaws.cn/iot/latest/apireference/API_UpdatePackageVersion.html)。 请参阅以下示例，该示例显示了在创建新程序包版本时支持 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 管理控制台中，表示为 `VersionARN`。任务文档中的程序包版本用以下任务文档占位符表示，如下所示： ``` arn:aws:iot:{{}}:{{111122223333}}:package/{{}}/version/{{$default}} ``` 要使用默认程序包版本创建任务或任务模板，请在 `CreateJob` 或 `CreateJobTemplate` 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](https://docs.amazonaws.cn/iot/latest/apireference/API_UpdatePackageVersion.html)API 操作进行发布。然后，您可以在创建任务时通过 Amazon IoT 控制台或发出 [CreateJob](https://docs.amazonaws.cn/iot/latest/apireference/API_CreateJob.html)API 操作来引用软件包版本。 ## 部署时指定软件包和版本 要将程序包版本部署到设备，请确认任务文档中引用的软件包和程序包版本与 `CreateJob` API 操作的 `destinationPackageVersions` 参数中所述的软件包和程序包版本相匹配。如果它们不匹配，您将收到一条错误消息，提示您确保两个引用匹配。有关软件包目录错误消息的更多信息，请参阅 [一般错误消息疑难解答](software-package-catalog-troubleshooting.md#spc-general-troubleshooting)。 除了任务文档中引用的软件包和程序包版本外，您还可以在 `CreateJob` API 操作的 `destinationPackageVersions` 参数中包含任务文档中未引用的其他软件包和程序包版本。确保任务文档中包含必要的安装信息，以便设备正确安装其他程序包版本。有关 `CreateJob ` API 操作的更多信息，请参阅[CreateJob](https://amazonaws.com.cn/iot/latest/apireference/API_CreateJob.html)。 ## 通过 Amazon IoT 动态事物组定位工作 软件包目录与[实例集索引](https://docs.amazonaws.cn/iot/latest/developerguide/iot-indexing.html)、[Amazon IoT 任务](https://docs.amazonaws.cn/iot/latest/developerguide/iot-jobs.html)和 [Amazon IoT 动态事物组](https://docs.amazonaws.cn/iot/latest/developerguide/dynamic-thing-groups.html)配合使用来筛选和定位实例集中的设备，以选择要部署到设备上的程序包版本。您可以根据设备当前的包裹信息运行队列索引查询，并将这些内容定位到 Amazon IoT 任务中。您也可以发布软件更新，但只能发布到符合条件的目标设备。例如，您可以指定只想将配置部署到当前运行 `iot-device-client 1.5.09` 的设备。有关更多信息，请参阅[创建动态事物组](https://docs.amazonaws.cn/iot/latest/developerguide/dynamic-thing-groups.html#create-dynamic-thing-group)。 ## 预留命名影子和程序包版本 如果已配置，则 Amazon IoT 任务可以在任务成功完成时更新名为 shadow (`$package`) 的事物的保留内容。如果这样做，则无需手动将程序包版本与事物的预留命名影子相关联。 在以下情况下，您可以选择手动将程序包版本关联或更新到事物的预留命名影子： + 您 Amazon IoT Core 无需关联已安装的软件包版本即可向其注册事物。 + Amazon IoT 未将作业配置为更新事物的预留名为 shadow。 + 您使用内部流程将软件包版本发送到您的车队，该流程 Amazon IoT Core 在完成后不会更新。 **注意** 我们建议您使用 Amazon IoT Jobs 更新名为 shadow (`$package`) 的预留文件中的软件包版本。当 Amazon IoT Jobs 也配置为更新`$package`影子时，通过其他流程（例如手动或编程 API 调用）更新影子中的版本参数可能会导致设备上的实际版本与报告的预留命名影子的版本不一致。 您可以通过控制台或 [https://docs.amazonaws.cn/iot/latest/apireference/API_iotdata_UpdateThingShadow.html](https://docs.amazonaws.cn/iot/latest/apireference/API_iotdata_UpdateThingShadow.html) API 操作，将程序包版本添加到或更新为预留命名影子 (`$package`)。有关更多信息，请参阅[将包版本与 Amazon IoT 事物关联](https://docs.amazonaws.cn/iot/latest/developerguide/associating-package-version.html)。 **注意** 将软件包版本与 Amazon IoT 事物关联不会直接更新设备软件。必须将程序包版本部署到设备才能更新设备软件。 ## 卸载软件包及其程序包版本 `$null`是一个保留的占位符，它会提示 Amazon IoT 作业服务从设备的预留名为 shadow `$package` 的软件包中删除现有的软件包和软件包版本。有关更多信息，请参阅[预留命名影子](https://docs.amazonaws.cn/iot/latest/developerguide/preparing-to-use-software-package-catalog.html#reserved-named-shadow)。 要使用此功能，请将 [destinationPackageVersion](https://docs.amazonaws.cn/iot/latest/apireference/API_CreateJobTemplate.html#iot-CreateJobTemplate-request-destinationPackageVersions)Amazon 资源名称 (ARN) 末尾的版本名称替换为。`$null`之后，您必须指示您的服务从设备中删除该软件。 授权的 ARN 使用以下格式： ``` arn:aws:iot:{{}}:{{111122223333}}:package/{{}}/version/$null ``` 例如， ``` $ aws iot create-job \ ... \ --destinationPackageVersions ["arn:aws:iot:us-east-1:111122223333:package/samplePackage/version/$null"] ```