本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # AWS IoT Device Management 软件包 Package 目录 使用 AWS IoT Device Management Software Package Catalog，您可以维护软件包及其版本的清单。您可以将包版本与单个事物和 AWS IoT 动态事物组相关联，并通过内部流程或[AWS IoT 作业](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)进行部署。 软件包中包含一个或多个程序包版本，这些版本是可以作为单个单元部署的文件集合。程序包版本可以包含固件、操作系统更新、设备应用程序、配置和安全补丁。随着软件发展，您可以创建新的程序包版本并将其部署到您的实例集中。 AWS IoT 软件包中心位于其中 AWS IoT Core。您可以使用该中心来集中注册和维护您的软件包清单和元数据，从而创建软件包及其版本的目录。您可以选择根据设备上部署的软件包和程序包版本对设备进行分组。此特征提供了此类机会：将设备端软件包清单保留为命名影子，根据版本关联设备和对设备分组，以及使用实例集指标可视化程序包版本在实例集中的分布。 如果您已建立内部软件部署系统，则可以继续使用该过程来部署程序包版本。如果您尚未建立部署过程，或者如果您愿意，我们建议您通过 [AWS IoT 任务](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)来使用软件包目录中的特征。有关更多信息，请参阅[准备 AWS IoT 作业](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-jobs-for-service-package-catalog.html)。 **Topics** + [准备使用软件包目录](preparing-to-use-software-package-catalog.md) + [准备安全性](preparing-security.md) + [准备实例集索引](preparing-fleet-indexing.md) + [准备 AWS IoT 工作](preparing-jobs-for-service-package-catalog.md) + [软件包目录入门](getting-started-with-software-package-catalog.md) # 准备使用软件包目录 以下部分概述了 AWS IoT Device Management 软件包的版本生命周期以及使用 Software Package Catalog 的信息。 ## 程序包版本生命周期 程序包版本可以通过以下生命周期状态演变：`draft`、`published` 和 `deprecated`。也可以是 `deleted`。 ![\[包含草稿、已发布和已弃用的程序包版本生命周期。也可以是已删除。\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/images/package-catalog-version-lifecycle.png) + **草稿** 创建程序包版本时，它处于 `draft` 状态。此状态表示软件包正在准备中，或者软件包不完整。 当程序包版本处于这种状态时，您将无法部署。您可以编辑程序包版本的描述、属性和标签。 您可以使用控制台`published`或`deleted`通过发出或 [DeletePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_DeletePackageVersion.html)API 操作将处于或`draft`处于状态的软件包版本过渡。[UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html) + **已发布** 当程序包版本准备就绪可供部署时，将程序包版本转换为 `published` 状态。在此状态下，您可以选择通过在控制台中编辑软件包或通过 [UpdatePackage](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackage.html)API 操作将软件包版本标识为默认版本。在此状态下，您只能编辑描述和标签。 您可以使用控制台或发出或 [DeletePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_DeletePackageVersion.html)API 操作将`deleted`处于`deprecated`或`published`处于状态的软件包版本过渡。[UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html) + **已弃用** 如果新的程序包版本可用，则可以将较早的程序包版本转换为 `deprecated`。您仍然可以使用已弃用的程序包版本部署任务。您也可以将已弃用的程序包版本指定为默认版本，只编辑描述和标签。 可以考虑在程序包版本过期时将其转换为 `deprecated`，但由于运行时依赖性，您现场仍有设备使用旧版本，或者需要对其进行维护。 您可以使用控制台或发出或 [DeletePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_DeletePackageVersion.html)API 操作将`deleted`处于`published`或`deprecated `处于状态的软件包版本过渡。[UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html) + **已删除** 当您不再打算使用某个软件包版本时，您可以使用控制台或发出 [DeletePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_DeletePackageVersion.html)API 操作将其删除。 **注意** 如果您在有待处理的任务引用程序包版本的情况下删除此版本，则当该任务成功完成并尝试更新预留命名影子时，您将收到错误消息。 如果您要删除的程序包版本已指定为默认程序包版本，则必须先更新软件包以将另一个版本指定为默认版本，或者将该字段保留为未指定。您可以使用控制台或 [UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html)API 操作来执行此操作。（要默认删除任何已命名的软件包版本，请在发出 [UpdatePackage](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackage.html)API 操作时将[unsetDefaultVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackage.html#iot-UpdatePackage-request-unsetDefaultVersion)参数设置为 true）。 如果您通过控制台删除软件包，则会删除与该软件包关联的所有程序包版本，除非其中一个版本指定为默认版本。 ## 程序包版本命名约定 在命名程序包版本时，重要的是要规划和应用合乎逻辑的命名策略，这样您和他人就可以轻松地识别最新的程序包版本和版本进展。创建程序包版本时必须提供版本名称，但策略和格式在很大程度上取决于您的业务案例。 作为最佳实践，我们建议使用语义版本控制格式。[SemVer](https://semver.org/)例如 `1.2.3`，其中 `1` 是功能发生不兼容更改的主要版本，`2` 是功能发生兼容更改的主要版本，而 `3` 是补丁版本（适用于错误修复）。有关更多信息，请参阅[语义版本控制 2.0.0](https://semver.org/)。有关软件包版本名称要求的更多信息，请参阅 AWS IoT API 参考指南中的 [versionN](https://docs.aws.amazon.com/iot/latest/apireference/API_CreatePackageVersion.html#API_CreatePackageVersion_RequestSyntax) ame。 ## 默认版本 将版本设置为默认版本是可选的。您可以添加或删除默认程序包版本。您也可以部署未指定为默认版本的程序包版本。 创建程序包版本时，它处于 `draft` 状态，在将程序包版本转换为已发布状态之前，无法将其指定为默认版本。软件包目录不会自动选择一个版本作为默认版本，也不会将更高的程序包版本更新为默认版本。您必须通过控制台或发出 [UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html)API 操作来故意命名您选择的软件包版本。 ## 版本属性 版本属性及其值拥有有关程序包版本的重要信息。我们建议您为软件包或程序包版本定义通用属性。例如，您可以为平台、架构、操作系统、发布日期、作者或 Amazon S3 URL 创建名称/值对。 使用作业文档创建 AWS IoT 作业时，也可以选择使用引用属性值的替代变量 (`$parameter`)。有关更多信息，请参阅[准备 AWS IoT 作业](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-jobs-for-service-package-catalog.html)。 程序包版本中使用的版本属性不会自动添加到预留命名影子中，也无法直接通过队列索引进行索引或查询。要通过队列索引对程序包版本属性进行索引或查询，可以在预留命名影子中填充版本属性。 我们建议预留命名影子中的版本属性参数捕获报告设备的属性，例如操作系统和安装时间。也可以通过队列索引对它们进行索引和查询。 版本属性无需遵循特定的命名惯例。您可以创建名称/值对以满足您的业务需求。程序包版本上所有属性的总大小限制为 3KB。有关更多信息，请参阅[软件包目录软件包和程序包版本限制](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#software_package_catalog_limits)。 **使用任务文档中的所有属性** 您可以将所有程序包版本属性自动添加到选定设备的任务部署中。要通过 API 或 CLI 命令中以编程方式自动使用所有程序包版本属性，请参阅以下任务文档示例： ``` "TestPackage": "${aws:iot:package:TestPackage:version:PackageVersion:attributes}" ``` ## 软件物料清单 软件物料清单（SBOM）针对您软件包的各个方面提供了一个中央存储库。除了存储软件包和软件包版本外，您还可以将与每个软件包版本关联的软件物料清单 (SBOM) 存储在 Softw AWS IoT Device Management are Package Catalog 中。软件包中包含一个或多个程序包版本，并且每个程序包版本由一个或多个组件组成。支持特定程序包版本构成的每个组件都可以使用软件物料清单进行描述和编目。支持的软件物料清单的行业标准是 SPDX 和 CycloneDX。首次创建 SBOM 时，它会根据 SPDX 和 CycloneDX 行业标准格式进行验证。有关 SPDX 的更多信息，请参阅 [System Package Data Exchange](https://spdx.dev/)。有关 CycloneDX 的更多信息，请参阅 [CycloneDX](https://cyclonedx.org/)。 软件物料清单介绍了特定程序包版本组件的各个方面，例如软件包信息、文件信息和其他相关元数据。参见以下 SPDX 格式的软件物料清单文档结构示例： ![\[SPDX 格式的 SBOM 示例。\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/images/spdx-2.3-document.png) ### 软件物料清单的好处 在软件包目录中添加程序包版本的软件物料清单的主要好处之一是漏洞管理。 **漏洞管理** 评估和缓解软件组件中明显安全风险的漏洞，对于保护设备实例集的完整性仍然至关重要。通过为每个程序包版本添加存储在软件包目录中的软件物料清单，您可以使用自己的内部漏洞管理解决方案，根据程序包版本和 SBOM 了解哪些设备面临风险，从而主动揭露安全漏洞。您可以为这些受影响的设备部署修复程序并保护您的设备实例集。 ### 软件物料清单存储 每个程序包版本的软件物料清单（SBOM）都存储在使用 Amazon S3 版本控制特征的 Amazon S3 存储桶中。存储 SBOM 的 Amazon S3 存储桶必须位于创建程序包版本的区域中。使用版本控制特征的 Amazon S3 存储桶在同一存储桶中会保留一个对象的多个变体。有关在 Amazon S3 存储桶中使用版本控制的更多信息，请参阅[在 Amazon S3 存储桶中使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。 **注意** 每个程序包版本可以附加多个 SBOM 文件，但 SBOM 文件必须存储在单个 zip 归档文件中。 存储桶的特定 Amazon S3 密钥和版本 ID 用于唯一标识程序包版本的每个软件物料清单版本。 **注意** 对于包含单个 SBOM 文件的程序包版本，您可以将该 SBOM 文件作为 zip 存档文件存储在 Amazon S3 存储桶中。 对于包含多个 SBOM 文件的程序包版本，您必须将所有 SBOM 文件放在单个 zip 存档文件中，然后将该 zip 存档文件存储在 Amazon S3 存储桶中。 在这两种情况下，存储在单个 zip 存档文件中的所有 SBOM 文件都会被格式化为 SPDX 或 CycloneDX .json 文件。 **权限策略** 为了 AWS IoT 充当指定委托人访问存储在 Amazon S3 存储桶中的 SBOM zip 存档文件，您需要一个基于资源的权限策略。有关正确的基于资源的权限策略，请参阅以下示例： **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "iot.amazonaws.com" ] }, "Action": "s3:*", "Resource": "arn:aws:s3:::bucketName/*" } ] } ``` 有关基于资源的权限策略的更多信息，请参阅 [AWS IoT 基于资源的政策](security_iam_service-with-iam.md#security_iam_service-with-iam-resource-based-policies)。 **更新 SBOM** 您可以根据需要经常更新软件物料清单，以保护和增强您的设备实例集。每次更新您的 Amazon S3 存储桶中的软件物料清单时，版本 ID 都会发生变化，并且您必须将新的 Amazon S3 存储桶 URL 与相应的程序包版本相关联。您将在 AWS 管理控制台中程序包版本页面上的 **Amazon S3 对象版本 ID** 列看到新版本 ID。此外，您可以使用 API 操作 `[GetPackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_GetPackageVersion.html)` 或 CLI 命令 `[get-package-version](https://docs.aws.amazon.com/cli/latest/reference/iot/get-package-version.html)` 来查看新版本 ID。 **注意** 更新软件物料清单会生成新的版本 ID，但不会导致创建新的程序包版本。 有关 Amazon S3 对象键的更多信息，请参阅[创建对象键名称](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html)。 ## 启用 AWS IoT 舰队索引 要使用 Software Package Catal AWS IoT Device Management og，必须启用 AWS IoT 队列索引。要利用软件包目录的 AWS IoT 实例集索引，请将预留命名影子 (`$package`) 设置为要编制索引并收集指标的每台设备的数据来源。有关预留命名影子的更多信息，请参阅 [预留命名影子](#reserved-named-shadow)。 队列索引提供的支持使 AWS IoT 事物能够通过按软件包版本筛选的动态事物组进行分组。例如，实例集索引可以识别已安装或尚未安装特定程序包版本、未安装任何程序包版本或匹配特定名称/值对的事物。最后，实例集索引提供了标准指标和自定义指标，您可以使用这些指标来深入了解设备实例集的状态。有关更多信息，请参阅 [准备实例集索引](preparing-fleet-indexing.md)。 **注意** 为软件包目录启用实例集索引会产生标准服务成本。有关更多信息，请参阅 [AWS IoT Device Management定价](https://aws.amazon.com/iot-device-management/pricing/)。 ## 预留命名影子 预留命名影子 `$package` 反映了设备已安装的软件包和程序包版本的状态。实例集索引使用预留命名影子作为数据来源来构建标准指标和自定义指标，以便您可以查询实例集的状态。有关更多信息，请参阅[准备实例集索引](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-fleet-indexing.html)。 预留命名影子与[命名影子](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html)类似，唯一的不同是前者的名称是预定义的，您无法对其进行更改。此外，预留命名影子不会使用元数据进行更新，而只使用 `version` 和 `attributes` 关键字。 包含其它关键字（例如 `description`）的更新请求将在 `rejected` 主题下收到错误响应。有关更多信息，请参阅[设备影子错误消息](https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-error-messages.html)。 它可以在您通过控制台创建 AWS IoT 事物、 AWS IoT 任务成功完成并更新影子以及发出 [https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_UpdateThingShadow.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_UpdateThingShadow.html)API 操作时创建。有关更多信息，请参阅 AWS IoT Core 开发者指南[UpdateThingShadow](https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-rest-api.html#API_UpdateThingShadow)中的。 **注意** 对预留命名影子编制索引不计入实例集索引可以编制索引的命名影子数量。有关更多信息，请参阅 [AWS IoT Device Management 实例集索引限制和限额](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#fleet-indexing-limits)。此外，如果您选择在任务成功完成时让 AWS IoT 任务更新预留的名为 shadow，则 API 调用将计入您的 Device Shadow 和注册表操作，并且可能会产生费用。有关更多信息，请参阅[AWS IoT Device Management 任务限制和配额](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#job-limits)以及 [IndexingFilter](https://docs.aws.amazon.com/iot/latest/apireference/API_IndexingFilter.html)API 数据类型。 **`$package` 影子的结构** 预留命名影子包含以下内容： ``` { "state": { "reported": { "": { "version": "", "attributes": { } } } }, "version" : 1 "timestamp" : 1672531201 } ``` 影子属性将使用以下信息进行更新： + ``：已安装软件包的名称，该名称使用 [packageName](https://docs.aws.amazon.com/iot/latest/apireference/API_CreatePackage.html#API_CreatePackage_RequestSyntax) 参数进行更新。 + `version`：已安装程序包版本的名称，该版本使用 [versionName](https://docs.aws.amazon.com/iot/latest/apireference/API_CreatePackageVersion.html#API_CreatePackageVersion_RequestSyntax) 参数进行更新。 + `attributes`：由设备存储并由实例集索引编制索引的可选元数据。这允许客户根据存储的数据查询其索引。 + `version`：影子的版本号。每次更新影子时，版本号都会自动递增，从 `1` 开始。 + `timestamp`：表示上次更新影子的时间，并以 [Unix 时间](https://en.wikipedia.org/wiki/Unix_time)记录。 有关命名影子的格式和行为的更多信息，请参阅 [AWS IoT 设备影子服务 消息顺序](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html#message-ordering)。 ## 删除软件包及其程序包版本 在删除软件包之前，请执行以下操作： + 确认软件包及其版本未处于活动部署状态。 + 请先删除所有关联的版本。如果其中一个版本指定为**默认版本**，则必须从软件包中删除指定的默认版本。由于指定默认版本是可选的，因此删除默认版本不会发生冲突。要从软件包中删除默认版本，请通过控制台编辑软件包或使用 [ UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html)API 操作。 只要没有已指定的默认程序包版本，您就可以使用控制台删除软件包，其所有程序包版本也将被删除。如果您使用 API 调用删除软件包，则必须先删除程序包版本，然后再删除软件包。 # 准备安全性 本节讨论 Software Package Catal AWS IoT Device Management og 的主要安全要求。 ## 基于资源的身份验证 在更新实例集中的软件时，软件包目录使用基于资源的授权来提高安全性。这意味着您必须创建一个 AWS Identity and Access Management (IAM) 策略，该策略授予对软件包和软件包版本执行`create``read``update``delete`、、和`list`操作的权限，并在该`Resources`部分中引用要部署的特定软件包和软件包版本。您也需要这些权限，以便更新[预留命名影子](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-to-use-software-package-catalog.html#reserved-named-shadow)。您可以通过为每个实体包括 Amazon 资源名称（ARN）来引用软件包和程序包版本。 **注意** 如果您打算让策略授予软件包版本 API 调用的权限（例如[CreatePackageVersion[UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html)](https://docs.aws.amazon.com/iot/latest/apireference/API_CreatePackageVersion.html)、、[DeletePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_DeletePackageVersion.html)），则需要在策略 ARNs 中*同时*包含软件包和软件包版本。如果您打算通过策略授予软件包 API 调用（例如[CreatePackage[UpdatePackage](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackage.html)](https://docs.aws.amazon.com/iot/latest/apireference/API_CreatePackage.html)、和 [DeletePackage](https://docs.aws.amazon.com/iot/latest/apireference/API_DeletePackage.html)）的权限，则必须在策略中仅包含软件包 ARN。 按 ARNs 如下方式构造软件包和软件包版本： + 软件包：`arn:aws:iot:::package//package` + 程序包版本：`arn:aws:iot:::package//version/` **注意** 您还可以此策略中包含其它相关权限。例如，您可以为 `job`、`thinggroup` 和 `jobtemplate` 加入一个 ARN。有关更多信息以及策略选项的完整列表，请参阅使用[AWS IoT 任务保护用户和设备](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs-security.html)。 例如，如果您的软件包和程序包版本命名如下： + AWS IoT 东西：`myThing` + 软件包名称：`samplePackage` + 版本 `1.0.0` 该策略可能类似于以下示例： **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:createPackage", "iot:createPackageVersion", "iot:updatePackage", "iot:updatePackageVersion" ], "Resource": [ "arn:aws:iot:us-east-1:111122223333:package/samplePackage", "arn:aws:iot:us-east-1:111122223333:package/samplePackage/version/1.0.0" ] }, { "Effect": "Allow", "Action": [ "iot:GetThingShadow", "iot:UpdateThingShadow" ], "Resource": "arn:aws:iot:us-east-1:111122223333:thing/myThing/$package" } ] } ``` ## AWS IoT 部署包版本的 Job 权限 出于安全考虑，您务必授予部署软件包和程序包版本的权限，并指定允许部署的特定软件包和程序包版本。为此，您需要创建 IAM 角色和策略，以授予使用程序包版本部署任务的权限。该策略必须将目标程序包版本指定为资源。 **IAM 策略** IAM 策略授予创建任务的权限，此任务包括在 `Resource` 部分中指定的软件包和版本。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:CreateJob", "iot:CreateJobTemplate" ], "Resource":[ "arn:aws:iot:*:111122223333:job/", "arn:aws:iot:*:111122223333:thing//$package", "arn:aws:iot:*:111122223333:thinggroup/", "arn:aws:iot:*:111122223333:jobtemplate/", "arn:aws:iot:*:111122223333:package//version/" ] } ] } ``` **注意** 如果要部署卸载软件包和程序包版本的任务，则必须授权其中程序包版本为 `$null` 的 ARN，如下所示： ``` arn:aws:iot::111122223333:package//version/$null ``` ## AWS IoT 更新保留的名为 shadow 的 Job 权限 要允许任务在任务成功完成时更新事物的预留名称影子，您必须创建 IAM 角色和策略。有两种方法可以在 AWS IoT 控制台中执行此操作。第一种是在控制台中创建软件包时。如果您看到**为软件包管理启用依赖项**对话框，则可以选择使用现有角色或创建新角色。或者，在 AWS IoT 控制台中，选择**设置**，选择**管理索引**，然后选择**管理设备软件包和版本的索引**。 **注意** 如果您选择在 AWS IoT 任务成功完成时让 Job 服务更新预留的名为 shadow，则 API 调用将计入您的 Dev **ice Shadow 和注册表操作**，并且可能会产生费用。有关更多信息，请参阅[AWS IoT Core 定价](https://aws.amazon.com/iot-core/pricing/)。 使用**创建角色**选项时，所生成角色的名称以 `aws-iot-role-update-shadows` 开头并包含以下策略： **设置角色** **Permissions** 权限策略授予查询和更新事物影子的权限。资源 ARN 中的 `$package` 参数以预留命名影子为目标。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:DescribeEndpoint", "Resource": "*" }, { "Effect": "Allow", "Action": [ "iot:GetThingShadow", "iot:UpdateThingShadow" ], "Resource": [ "arn:aws:iot:us-east-1:111122223333:thing//$package" ] } ] } ``` **信任关系** 除了权限策略外，该角色还需要与 AWS IoT Core 建立信任关系，以便实体可以代入该角色并更新预留命名影子。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "iot.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` **设置用户策略** **iam：PassRole 权限** 最后，在调用 [ UpdatePackageConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageConfiguration.html)API 操作 AWS IoT Core 时，您必须拥有将角色传递给的权限。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iam:PassRole", "iot:UpdatePackageConfiguration" ], "Resource": "arn:aws:iam::111122223333:role/" } ] } ``` ## AWS IoT 从 Amazon S3 下载的任务权限 任务文件保存在 Amazon S3 中。当你通过 AWS IoT Jobs 调度时，你会参考这个文件。您必须向 AWS IoT Jobs 提供下载文件的权限 (`s3:GetObject`)。您还必须在 Amazon S3 和 AWS IoT 任务之间建立信任关系。有关创建这些策略的说明，请参阅[管理作业 URLs](https://docs.aws.amazon.com/iot/latest/developerguide/create-manage-jobs.html)中的[预签名](https://docs.aws.amazon.com/iot/latest/developerguide/create-manage-jobs.html#create-manage-jobs-presigned-URLs)。 ## 更新程序包版本的软件物料清单的权限 要更新处于`Draft`、`Published`或`Deprecated`生命周期状态的软件包版本的软件物料清单，您需要一个 AWS Identity and Access Management 角色和策略来在 Amazon S3 中查找新的软件物料清单并在中更新软件包版本 AWS IoT Core。 首先，您需要将更新的软件物料清单放置在受版本控制的 Amazon S3 存储桶中，并在包含 `sboms` 参数的情况下调用 `[UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html)` API 操作。接下来，您的授权委托人将担任您创建的 IAM 角色，在 Amazon S3 中找到更新的软件物料清单，然后在 Software Package Catalog 中 AWS IoT Core 更新软件包版本。 执行此更新需要以下策略： **策略** + **信任策略**：该策略与代入 IAM 角色的授权主体建立信任关系，以便其可以从 Amazon S3 中受版本控制的存储桶找到更新的软件物料清单，并在 AWS IoT Core中更新程序包版本。 + **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "s3.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` + **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "iot.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` + **权限策略**：通过该策略可以访问其中存储了程序包版本软件物料清单的 Amazon S3 受版本控制的存储桶，并在 AWS IoT Core中更新程序包版本。 + **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::awsexamplebucket1" ] } ] } ``` + **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:UpdatePackageVersion" ], "Resource": [ "arn:aws:iot:*:111122223333:package//version/" ] } ] } ``` + **传递角色权限**：策略授予在您调用 `[UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html)` API 操作 AWS IoT Core 时向 Amazon S3 传递 IAM 角色的权限。 + **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iam:PassRole", "s3:GetObject" ], "Resource": [ "arn:aws:s3:::awsexamplebucket1" ] } ] } ``` + **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iam:PassRole", "iot:UpdatePackageVersion" ], "Resource": "arn:aws:iam::111122223333:role/" } ] } ``` **注意** 对于已转换为 `Deleted` 生命周期状态的程序包版本，您无法更新软件物料清单。 有关为 AWS 服务创建 IAM 角色的更多信息，请参阅[创建向 AWS 服务委派权限的角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)。 有关创建 Amazon S3 存储桶并向其上传对象的更多信息，请参阅[创建存储桶](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html)和[上传对象](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html)。 # 准备实例集索引 使用 AWS IoT 队列索引，您可以使用名为 shadow (`$package`) 的预留名称来搜索和聚合数据。您还可以通过查询[预留命名影子](preparing-to-use-software-package-catalog.md#reserved-named-shadow)和[动态 AWS IoT 事物组对事物进行分组](https://docs.aws.amazon.com/iot/latest/developerguide/dynamic-thing-groups.html)。例如，您可以找到有关哪些 AWS IoT 内容使用特定的软件包版本、未安装特定的软件包版本或未安装任何软件包版本的信息。您可以通过组合属性来获得进一步的见解。例如，识别具有特定版本且属于特定事物类型的事物（例如版本 1.0.0 和事物类型 pump\$1sensor）。有关更多信息，请参阅[实例集索引](https://docs.aws.amazon.com/iot/latest/developerguide/iot-indexing.html)。 ## 将 `$package` 影子设置为数据来源 要在软件包目录中使用实例集索引，必须启用实例集索引，将命名影子设置为数据来源，并将 `$package` 定义为命名影子筛选条件。如果您尚未启用实例集索引，则可以在此过程中将其启用。从控制台中的 [AWS IoT Core](https://console.aws.amazon.com/iot/home)，打开**设置**，选择**管理索引**，然后依次选择**添加命名影子**、**添加设备软件包和版本**和**更新**。有关更多信息，请参阅[管理事物索引](https://docs.aws.amazon.com/iot/latest/developerguide/managing-fleet-index.html#thing-index)。 或者，您可以在创建第一个软件包时启用实例集索引。出现**为软件包管理启用依赖项**对话框时，选择将设备软件包和版本作为数据来源添加到实例集索引的选项。通过选择此选项，还可以启用实例集索引。 **注意** 为软件包目录启用实例集索引会产生标准服务成本。有关更多信息，请参阅 [AWS IoT Device Management定价](https://aws.amazon.com/iot-device-management/pricing/)。 ## 控制台中显示的指标 ![\[标准指标图\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/images/package-catalog-discovery-metrics.png) 在 AWS IoT 控制台软件包详细信息页面上，**Discovery** 面板显示通过`$package`阴影获取的标准指标。 + **当前版本分布**图显示了与该软件包关联的所有设备中与某 AWS IoT 件事物关联的 10 个最新软件包版本的设备数量和百分比。**注意：**如果软件包的程序包版本多于图表中标注的版本，则可以发现它们分组在**其它**中。 + **历史图表**显示指定时间段内与所选程序包版本关联的设备数量。该图表最初为空，直至您选择多达 5 个程序包版本并定义日期范围和时间间隔。要选择图表的参数，请选择**设置**。**历史图表**中显示的数据可能与**当前版本分发**图不同，这是因为它们显示的程序包版本数量不同，也因为您可以在**历史图表**中选择要分析的程序包版本。**注意：**当您选择要可视化的程序包版本时，它将计入实例集指标的最大数量限制。有关更多信息，请参阅[实例集索引限制和限额](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#fleet-indexing-limits)。 有关深入了解收集程序包版本分发的另一种方法，请参阅[通过 `getBucketsAggregation` 收集程序包版本分发](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-fleet-indexing.html#package-version-distribution)。 ## 查询模式 使用软件包目录的实例集索引支持大多数标准功能（例如术语、短语和搜索字段）。但是，比较运算符（例如小于 `<` 和大于 `>`）和 `range` 查询不适用于保留的命名影子 (`$package`) `version` 键。这些查询可用于 `attributes` 键。有关更多信息，请参阅[查询语法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。 ### 示例数据 **注意：**有关预留命名影子及其结构的信息，请参阅[预留命名影子](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-to-use-software-package-catalog.html#reserved-named-shadow)。 在此示例中，第一台设备命名为 `AnyThing` 并安装了以下软件包： + 软件包：`SamplePackage` 程序包版本：`1.0.0` 软件包 ID：`1111` 影子如下所示： ``` { "state": { "reported": { "SamplePackage": { "version": "1.0.0", "attributes": { "s3UrlForSamplePackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile1", "packageID": "1111" } } } } } ``` 第二台设备命名为 `AnotherThing` 并安装了以下软件包： + 软件包：`SamplePackage` 程序包版本：`1.0.0` 软件包 ID：`1111` + 软件包：`OtherPackage` 程序包版本：`1.2.5` 软件包 ID：`2222` 影子如下所示： ``` { "state": { "reported": { "SamplePackage": { "version": "1.0.0", "attributes": { "s3UrlForSamplePackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile1", "packageID": "1111" } }, "OtherPackage": { "version": "1.2.5", "attributes": { "s3UrlForOtherPackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile2", "packageID": "2222" } }, } } } ``` ### 查询示例 下表根据 `AnyThing` 和 `AnotherThing` 的示例设备影子列出了查询示例。有关更多信息，请参阅[示例事物查询](https://docs.aws.amazon.com/iot/latest/developerguide/example-queries.html)。 **AWS IoT Device Tester 适用于 FreeRTOS 的最新版本** | **所请求的信息** | **查询** | **结果** | | --- | --- | --- | | 安装了特定程序包版本的事物 | `shadow.name.$package.reported.SamplePackage.version:1.0.0` | `AnyThing`, `OtherThing` | | 未安装特定程序包版本的事物 | `NOT shadow.name.$package.reported.OtherPackage.version:1.2.5` | `AnyThing` | | 使用软件包 ID 大于 1500 的程序包版本的任何设备 | `shadow.name.$package.reported.*.attributes.packageID>1500"` | `OtherThing` | | 安装了特定软件包和安装了多个软件包的事物 | `shadow.name.$package.reported.SamplePackage.version:1.0.0 AND shadow.name.$package.reported.totalCount:2` | `OtherThing` | ## 通过 `getBucketsAggregation` 收集程序包版本分发 除了 AWS IoT 控制台中的**发现**面板外，您还可以使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_GetBucketsAggregation.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetBucketsAggregation.html)API 操作获取软件包版本分发信息。要获取程序包版本分发信息，必须执行以下操作： + 在实例集索引中为每个软件包定义一个自定义字段。**注意：**创建自定义字段会计入 [AWS IoT 实例集索引服务限额](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#fleet-indexing-limits)。 + 按如下方式格式化自定义字段： `shadow.name.$package.reported..version` 有关更多信息，请参阅 AWS IoT 舰队索引中的 “[自定义字段](https://docs.aws.amazon.com/iot/latest/developerguide/managing-fleet-index.html#custom-field)” 部分。 # 准备 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 部署软件包版本](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-security.html#job-rights-deploy-versions)的[AWS IoT 任务权限和更新保留名为 shadow 的](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-security.html#job-rights-update-reserved-named-shadow)任务权限。有关更多信息，请参阅[准备安全性](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-security.html)。 ## AWS IoT 任务的替代参数 您可以在 AWS 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.aws.amazon.com/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)。 在中 AWS 管理控制台，在任务部署包版本期间，切*换*部署指令文件编辑器*窗口中的预览*替换按钮，以查看带有和不带替换参数的作业文档。 使用`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}", } ``` 有关 AWS IoT 作业、创建作业文档和部署作业的更多信息，请参阅[作业](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)。 ## 准备任务文档和程序包版本以进行部署 创建程序包版本时，它处于 `draft` 状态，表示正准备部署。要准备好程序包版本进行部署，您必须创建任务文档，将文档保存到任务可以访问的位置（例如 Amazon S3），确认程序包版本具有您希望任务文档使用的属性值。（注意：仅当程序包版本处于 `draft` 状态时，您才可以更新其属性。） 在为单包部署创建 Job 或 Job 模板时，您可以使用以下选项自定义任务文档： AWS IoT **部署指令文件 (`recipe`)** + 程序包版本的部署指令文件包含用于将程序包版本部署到多台设备的部署指令，其中包括内联任务文档。该文件将特定的部署指令与程序包版本相关联，以实现快速高效的任务部署。 在中 AWS 管理控制台，您可以在 “*部署说明” 文件预览*窗口的 “创建新包” 工作流程的 “*版本部署配置*” 选项卡中创建文件。您可以使用*从 AWS IoT 推荐文件开始使用包版本属性自动生成说明文件，或者使用*您自己的部署说明文件**使用存储在 Amazon S3 存储桶中的现有任务文档。 AWS IoT **注意** 如果您使用自己的任务文档，则可以在*部署指令文件预览*窗口中直接对其进行更新，但它不会自动更新存储在 Amazon S3 存储桶中的原始任务文档。 使用 AWS 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 位置。当使用 AWS IoT Jobs 触发程序包版本的任务部署时，任务文档中的预签名 URL 占位符 ` ${aws:iot:package::version::artifact-location:s3-presigned-url}` 将使用 Amazon S3 存储桶、存储桶密钥和存储在 Amazon S3 存储桶中的文件版本进行更新。存储程序包版本构件的 Amazon S3 存储桶必须位于创建程序包版本的区域中。 **注意** 要将同一文件的多个对象版本存储在您的 Amazon S3 存储桶中，您必须在存储桶上启用版本控制。有关更多信息，请参阅[在存储桶上启用版本控制](https://docs.aws.amazon.com/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/iot/latest/apireference/API_CreatePackageVersion.html)和[UpdatePackageVersion](https://docs.aws.amazon.com/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` 状态下执行这些更新。 **程序包版本** + 默认程序包版本可以通过软件包的可用版本表示，提供安全稳定的程序包版本。使用 AWS IoT Jobs 将默认软件包版本部署到设备队列时，这是软件包的基准版本。在创建任务以部署软件包的 `$default` 程序包版本时，任务文档和新任务部署中的程序包版本必须与 `$default` 相匹配。对于 API 和 CLI 命令，任务部署中的程序包版本表示为 `destinationPackageVersions`，而在 AWS 管理控制台中，表示为 `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` 程序包版本属性是一个可选属性，只有在通过 AWS IoT Jobs 引用任务部署的默认程序包版本时才需要该属性。 如果您对软件包版本感到满意，请通过 AWS IoT 控制台中的软件包详细信息页面或发出 [UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html)API 操作进行发布。然后，您可以在创建任务时通过 AWS IoT 控制台或发出 [CreateJob](https://docs.aws.amazon.com/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/iot/latest/apireference/API_CreateJob.html)。 ## 通过 AWS IoT 动态事物组定位工作 软件包目录与[实例集索引](https://docs.aws.amazon.com/iot/latest/developerguide/iot-indexing.html)、[AWS IoT 任务](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)和 [AWS IoT 动态事物组](https://docs.aws.amazon.com/iot/latest/developerguide/dynamic-thing-groups.html)配合使用来筛选和定位实例集中的设备，以选择要部署到设备上的程序包版本。您可以根据设备当前的包裹信息运行队列索引查询，并将这些内容定位到 AWS IoT 任务中。您也可以发布软件更新，但只能发布到符合条件的目标设备。例如，您可以指定只想将配置部署到当前运行 `iot-device-client 1.5.09` 的设备。有关更多信息，请参阅[创建动态事物组](https://docs.aws.amazon.com/iot/latest/developerguide/dynamic-thing-groups.html#create-dynamic-thing-group)。 ## 预留命名影子和程序包版本 如果已配置，则 AWS IoT 任务可以在任务成功完成时更新名为 shadow (`$package`) 的事物的保留内容。如果这样做，则无需手动将程序包版本与事物的预留命名影子相关联。 在以下情况下，您可以选择手动将程序包版本关联或更新到事物的预留命名影子： + 您 AWS IoT Core 无需关联已安装的软件包版本即可向其注册事物。 + AWS IoT 未将作业配置为更新事物的预留名为 shadow。 + 您使用内部流程将软件包版本发送到您的车队，该流程 AWS IoT Core 在完成后不会更新。 **注意** 我们建议您使用 AWS IoT Jobs 更新名为 shadow (`$package`) 的预留文件中的软件包版本。当 AWS IoT Jobs 也配置为更新`$package`影子时，通过其他流程（例如手动或编程 API 调用）更新影子中的版本参数可能会导致设备上的实际版本与报告的预留命名影子的版本不一致。 您可以通过控制台或 [https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_UpdateThingShadow.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_UpdateThingShadow.html) API 操作，将程序包版本添加到或更新为预留命名影子 (`$package`)。有关更多信息，请参阅[将包版本与 AWS IoT 事物关联](https://docs.aws.amazon.com/iot/latest/developerguide/associating-package-version.html)。 **注意** 将软件包版本与 AWS IoT 事物关联不会直接更新设备软件。必须将程序包版本部署到设备才能更新设备软件。 ## 卸载软件包及其程序包版本 `$null`是一个保留的占位符，它会提示 AWS IoT 作业服务从设备的预留名为 shadow `$package` 的软件包中删除现有的软件包和软件包版本。有关更多信息，请参阅[预留命名影子](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-to-use-software-package-catalog.html#reserved-named-shadow)。 要使用此功能，请将 [destinationPackageVersion](https://docs.aws.amazon.com/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"] ``` # 软件包目录入门 您可以通过、 AWS IoT Core API 操作和 AWS Command Line Interface (AWS CLI) 来构建和维护 Soft AWS IoT Device Management ware Package 目录。 AWS 管理控制台 **注意** 要使用 Software Package Catalog，必须启用 AWS IoT 队列索引。如果不启用 AWS IoT 队列索引，则在中创建软件包版本 AWS 管理控制台 和使用 `CreatePackage` API 命令等基本操作将失败。 有关在 Software Package Catalog 中使用 AWS IoT 队列索引的更多信息，请参阅[准备实例集索引](preparing-fleet-indexing.md)。 **使用控制台** 要使用 AWS 管理控制台，请登录您的 AWS 帐户并导航至[AWS IoT Core](https://console.aws.amazon.com/iot/home)。在导航窗格中，选择**软件包**。然后，您可以通过此部分创建和管理软件包及其版本。 **使用 API 或 CLI 操作** 您可以使用 AWS IoT Core API 操作来创建和管理 Software Package Catalog 功能。有关更多信息，请参阅 [AWS IoT API 参考AWS](https://docs.aws.amazon.com/iot/latest/apireference/)[SDKs 和工具包](https://aws.amazon.com/developer/tools/)。这些 AWS CLI 命令还可以管理您的目录。有关更多信息，请参阅 [AWS IoT CLI 命令参考](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/index.html)。 **Topics** + [创建软件包和程序包版本](creating-package-and-version.md) + [通过 AWS IoT 作业部署软件包版本](deploying-package-version.md) + [将软件包版本与事物关联 AWS IoT](associating-package-version.md) # 创建软件包和程序包版本 您可以使用以下步骤通过 AWS 管理控制台创建软件包和初始版本事物。 **创建软件包** 1. 登录您的 AWS 帐户并导航到[AWS IoT 控制台](https://console.aws.amazon.com/iot/home)。 1. 在导航窗格上，选择**软件包**。 1. 在 **AWS IoT 软件包**页面上，选择**创建软件包**。将出现**为软件包管理启用依赖项**对话框。 1. 在**实例集索引**下，选择**添加设备软件包和版本**。这是软件包目录所必需的，它提供了有关实例集的实例集索引和指标。 1. [可选] 如果您希望 AWS IoT 任务在任务成功完成时更新预留的命名影子，请选择 “**自动更新任务中的阴影**”。如果您不希望 AWS IoT 作业进行此更新，请取消选中此复选框。 1. [可选] 要授予 AWS IoT 作业更新预留名为 shadow 的权限，**请在 “选择角色”** 下选择 “**创建角色**”。如果您不希望 AWS IoT 作业进行此更新，则不需要此角色。 1. 创建或选择一个角色。 1. 如果您**没有用于此用途的角色**：当**创建角色**对话框出现时，输入**角色名称**，然后选择**创建**。 1. **如果您有用于此用途的角色**：对于**选择角色**，请选择您的角色，然后确保选中**将策略附加到 IAM 角色**复选框。 1. 选择**确认**。此时将出现**创建新软件包**页面。 1. 在**软件包详细信息**下，输入**软件包名称**。 1. 在**软件包描述**下，输入可帮助您识别和管理此软件包的信息。 1. [可选] 您可以使用标签来帮助您对该软件包进行分类和管理。要添加标签，请展开**标签**，选择**添加标签**，然后输入键/值对。您最多可以输入 50 个标签。有关更多信息，请参阅为[AWS IoT 资源添加标签](https://docs.aws.amazon.com/iot/latest/developerguide/tagging-iot.html)。 **在创建新的软件包时添加程序包版本** 1. 在**初始版本**下，输入**版本名称**。 我们建议使用[SemVer 格式](https://semver.org/)（例如`1.0.0.0`）来唯一标识您的软件包版本。还可以使用更适合您的使用案例的不同格式策略。有关更多信息，请参阅 [程序包版本生命周期](preparing-to-use-software-package-catalog.md#package-version-lifecycle)。 1. 在**版本描述**下，输入有助于您识别和管理此程序包版本的信息。 **注意** **默认版本**复选框已停用，因为程序包版本是在 `draft` 状态下创建的。您可以在创建程序包版本之后以及将状态更改为 `published` 时指定默认版本。有关更多信息，请参阅 [程序包版本生命周期](preparing-to-use-software-package-catalog.md#package-version-lifecycle)。 1. [可选] 为了帮助您管理此版本或将信息传达给您的设备，请为**版本属性**输入一个或多个名称/值对。为您输入的每个名称/值对选择**添加属性**。有关更多信息，请参阅 [版本属性](preparing-to-use-software-package-catalog.md#version-attributes)。 1. [可选] 您可以使用标签来帮助您对该软件包进行分类和管理。要添加标签，请展开**标签**，选择**添加标签**，然后输入键/值对。您最多可以输入 50 个标签。有关更多信息，请参阅为[AWS IoT 资源添加标签](https://docs.aws.amazon.com/iot/latest/developerguide/tagging-iot.html)。 1. 选择**下一步**。 **将软件物料清单与程序包版本关联（可选）** 1. 在 **SBOM 配置**窗口的 “**步骤 3：版本 SBOMs （可选）**” 中，选择默认 SBOM 文件格式和验证模式，用于在软件物料清单与软件包版本关联之前对其进行验证。 1. 在**添加 SBOM 文件**窗口中，输入表示受版本控制的 Amazon S3 存储桶的 Amazon 资源名称（ARN），如果默认类型无效，则输入首选的 SBOM 文件格式。 **注意** SBOMs 如果您的软件包版本有多个软件物料清单，则可以添加一个 SBOM 文件或包含多个文件的 zip 文件。 1. 在**已添加的 SBOM 文件**窗口中，您可以查看为程序包版本添加的 SBOM 文件。 1. 选择**创建软件包和版本**。程序包版本页面随即出现，您可以在**已添加的 SBOM 文件**窗口中看到 SBOM 文件的验证状态。SBOM 文件进行验证时的初始状态将为 `In progress`。 **注意** SBOM 文件验证状态包括 `Invalid file`、`Not started`、`In progress`、`Validated (SPDX)`、`Validated (CycloneDX)`，以及验证失败的原因。 # 通过 AWS IoT 作业部署软件包版本 您可以使用以下步骤通过 AWS 管理控制台部署程序包版本。 **先决条件：** 开始之前，请执行以下操作： + 向注册 AWS IoT 事物 AWS IoT Core. 有关向其中添加设备的说明 AWS IoT Core，请参阅[创建事物对象](https://docs.aws.amazon.com/iot/latest/developerguide/create-iot-resources.html#create-aws-thing)。 + [可选] 创建 AWS IoT 事物组或动态事物组，将要部署软件包版本的设备作为目标。有关创建事物组的说明，请参阅[创建静态事物组](https://docs.aws.amazon.com/iot/latest/developerguide/thing-groups.html#create-thing-group)。有关创建动态事物组的说明，请参阅[创建动态事物组](https://docs.aws.amazon.com/iot/latest/developerguide/dynamic-thing-groups.html#create-dynamic-thing-group)。 + 创建软件包和程序包版本。有关更多信息，请参阅 [创建软件包和程序包版本](creating-package-and-version.md)。 + 创建任务文档。有关更多信息，请参阅[准备任务文档和程序包版本以进行部署](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-jobs-for-service-package-catalog.html#preparing-to-deploy)。 **部署作 AWS IoT 业** 1. 在 [AWS IoT 控制台](https://console.aws.amazon.com/iot/home)上，选择**软件包**。 1. 选择要部署的软件包。此时将显示**软件包详细信息**页面。 1. 在**版本**下选择要部署的程序包版本，然后选择**部署任务版本**。 1. 如果这是您第一次通过此门户部署任务，则会出现一个描述要求的对话框。检查信息并选择**确认**。 1. 输入部署的名称或在**名称**字段中保留自动生成的名称。 1. [可选] 在**描述**字段中，输入描述以标识部署的目的或内容，或者保留自动生成的信息。 **注意：**我们建议您不要在任务名称和描述字段中使用个人身份信息。 1. [可选] 添加要与此任务关联的所有标签。 1. 选择**下一步**。 1. 在**任务目标**下，选择应接收任务的事物或事物组。 1. 在**任务文件**字段中，指定任务文档 JSON 文件。 1. 打开**与软件包目录服务的任务集成**。 1. 选择在任务文档中指定的软件包和版本。 **注意** 您需要选择在任务文档中指定的相同软件包和程序包版本。您可以包含更多内容，但该任务将仅针对任务文档中包含的软件包和版本发出说明。有关更多信息，请参阅[部署时命名软件包和版本](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-jobs-for-service-package-catalog.html#naming-package-versions)。 1. 选择**下一步**。 1. 在“任务配置”页面上，在“任务配置”对话框中选择以下任务类型之一： + **快照任务**：快照任务在目标设备和组上完成运行后即完成。 + **连续任务**：连续任务适用于事物组，并会在以后添加到指定目标组的任何设备上运行。 1. 在 **其它配置 - 可选**对话框中，查看以下可选任务配置并相应进行选择。有关更多信息，请参阅[任务推出、计划和中止配置](https://docs.aws.amazon.com/iot/latest/developerguide/jobs-configurations-details.html#job-rollout-abort-scheduling)以及[任务执行超时和重试配置](https://docs.aws.amazon.com/iot/latest/developerguide/jobs-configurations-details.html#job-timeout-retry)。 + 推出配置 + 计划配置 + 任务执行超时配置 + 任务执行重试配置 + 中止配置 1. 查看任务选择，然后选择**提交**。 在您创建任务后，控制台会生成一个 JSON 签名并将其放在您的任务文档中。您可以使用 AWS IoT 控制台查看任务的状态，也可以取消或删除作业。要管理任务，请转到[控制台的 Job 中心](https://console.aws.amazon.com/iot/home#/jobhub)。 # 将软件包版本与事物关联 AWS IoT 在设备上安装软件后，您可以将软件包版本与名为 shadow AWS IoT 的预留内容关联起来。如果已将 AWS IoT 作业配置为在任务部署并成功完成后更新事物的预留名为 shadow，则无需完成此过程。有关更多信息，请参阅 [预留命名影子](preparing-to-use-software-package-catalog.md#reserved-named-shadow)。 **先决条件：** 开始之前，请执行以下操作： + 创造一个或 AWS IoT 多个事物，并通过 AWS IoT Core它建立遥测。有关更多信息，请参阅[入门 AWS IoT Core](https://docs.aws.amazon.com/iot/latest/developerguide/iot-gs.html)。 + 创建软件包和程序包版本。有关更多信息，请参阅 [创建软件包和程序包版本](creating-package-and-version.md)。 + 在设备上安装程序包版本软件。 **注意** 将软件包版本与 AWS IoT 事物关联不会在物理设备上更新或安装软件。程序包版本必须部署到设备上。 **将包版本与 AWS IoT 事物关联** 1. 在 [AWS IoT 控制台](https://console.aws.amazon.com/iot/home)导航窗格上，展开**所有设备**菜单并选择**事物**。 1. 从列表中确定要更新的 AWS IoT 事物，然后选择事物名称以显示其详细信息页面。 1. 在**详细信息**部分中，选择**软件包和版本**。 1. 选择**添加到软件包和版本**。 1. 对于**选择设备软件包**，选择所需的软件包。 1. 对于**选择版本**，选择所需的软件版本。 1. 选择**添加设备软件包**。 软件包和版本显示在**选定的软件包和版本**列表中。 1. 对要与此事物关联的每个软件包和版本重复这些步骤。 1. 完成后，选择**添加软件包和版本详细信息**。**事物详细信息**页面打开，您可以在列表中看到新的软件包和版本。