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

准备使用软件包目录

下一节概述了软件包版本生命周期以及使用 AWS IoT Device Management 软件包目录的信息。

软件包版本生命周期

软件包版本可以通过以下生命周期状态演变：draft、published 和 deprecated。也可以是 deleted。

软件包版本命名约定

在命名软件包版本时，重要的是要规划和应用合乎逻辑的命名策略，这样您和他人就可以轻松地识别最新的软件包版本和版本进展。创建软件包版本时必须提供版本名称，但策略和格式在很大程度上取决于您的业务案例。

作为最佳实践，我们建议使用语义版本控制 SemVer 格式。例如 1.2.3，其中 1 是功能发生不兼容更改的主要版本，2 是功能发生兼容更改的主要版本，而 3 是补丁版本（适用于错误修复）。有关更多信息，请参阅语义版本控制 2.0.0。有关软件包版本名称要求的更多信息，请参阅《AWS IoT API 参考指南》中的 versionName。

默认版本

将版本设置为默认版本是可选的。您可以添加或删除默认软件包版本。您也可以部署未指定为默认版本的软件包版本。

创建软件包版本时，它处于 draft 状态，在将软件包版本转换为已发布状态之前，无法将其指定为默认版本。软件包目录不会自动选择一个版本作为默认版本，也不会将更高的软件包版本更新为默认版本。您必须特意通过控制台或通过发出 UpdatePackageVersion API 操作来指定您选择的软件包版本。

版本属性

版本属性及其值拥有有关软件包版本的重要信息。我们建议您为软件包或软件包版本定义通用属性。例如，您可以为平台、架构、操作系统、发布日期、作者或 Amazon S3 URL 创建名称/值对。

使用任务文档创建 AWS IoT 任务时，还可以选择使用引用属性值的替代变量（$parameter）。有关更多信息，请参阅准备 AWS IoT Jobs。

软件包版本中使用的版本属性不会自动添加到预留命名影子中，也无法直接通过队列索引进行索引或查询。要通过队列索引对软件包版本属性进行索引或查询，可以在预留命名影子中填充版本属性。

我们建议预留命名影子中的版本属性参数捕获报告设备的属性，例如操作系统和安装时间。也可以通过队列索引对它们进行索引和查询。

版本属性无需遵循特定的命名惯例。您可以创建名称/值对以满足您的业务需求。软件包版本上所有属性的总大小限制为 3KB。有关更多信息，请参阅软件包目录软件包和软件包版本限制。

使用作业文档中的所有属性

您可以将所有软件包版本属性自动添加到选定设备的作业部署中。要通过 API 或 CLI 命令中以编程方式自动使用所有软件包版本属性，请参阅以下作业文档示例：

"TestPackage": "${aws:iot:package:TestPackage:version:PackageVersion:attributes}"

软件物料清单

软件物料清单（SBOM）针对您软件包的各个方面提供了一个中央存储库。除了存储软件包和软件包版本外，您还可以将与每个软件包版本关联的软件物料清单（SBOM）存储在 AWS IoT Device Management 软件包目录中。软件包中包含一个或多个软件包版本，并且每个软件包版本由一个或多个组件组成。支持特定软件包版本构成的每个组件都可以使用软件物料清单进行描述和编目。支持的软件物料清单的行业标准是 SPDX 和 CycloneDX。首次创建 SBOM 时，它会根据 SPDX 和 CycloneDX 行业标准格式进行验证。有关 SPDX 的更多信息，请参阅 System Package Data Exchange。有关 CycloneDX 的更多信息，请参阅 CycloneDX。

软件物料清单介绍了特定软件包版本组件的各个方面，例如软件包信息、文件信息和其他相关元数据。参见以下 SPDX 格式的软件物料清单文档结构示例：

软件物料清单的好处

在软件包目录中添加软件包版本的软件物料清单的主要好处之一是漏洞管理。

漏洞管理

评估和缓解软件组件中明显安全风险的漏洞，对于保护设备实例集的完整性仍然至关重要。通过为每个软件包版本添加存储在软件包目录中的软件物料清单，您可以使用自己的内部漏洞管理解决方案，根据软件包版本和 SBOM 了解哪些设备面临风险，从而主动揭露安全漏洞。您可以为这些受影响的设备部署修复程序并保护您的设备实例集。

软件物料清单存储

每个软件包版本的软件物料清单（SBOM）都存储在使用 Amazon S3 版本控制特征的 Amazon S3 存储桶中。存储 SBOM 的 Amazon S3 存储桶必须位于创建软件包版本的区域中。使用版本控制特征的 Amazon S3 存储桶在同一存储桶中会保留一个对象的多个变体。有关在 Amazon S3 存储桶中使用版本控制的更多信息，请参阅在 Amazon S3 存储桶中使用版本控制。

存储桶的特定 Amazon S3 密钥和版本 ID 用于唯一标识软件包版本的每个软件物料清单版本。

权限策略

为了让 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 基于资源的策略。

更新 SBOM

您可以根据需要经常更新软件物料清单，以保护和增强您的设备实例集。每次更新您的 Amazon S3 存储桶中的软件物料清单时，版本 ID 都会发生变化，软件包目录会收到更新通知，并且您必须将新的 Amazon S3 存储桶 URL 与相应的软件包版本相关联。您将在 AWS Management Console中软件包版本页面上的 Amazon S3 对象版本 ID 列看到新版本 ID。此外，您可以使用 API 操作 GetPackageVersion 或 CLI 命令 get-package-version 来查看新版本 ID。

有关 Amazon S3 对象键的更多信息，请参阅创建对象键名称。

启用 AWS IoT 实例集索引

要利用软件包目录的 AWS IoT 实例集索引，请将预留命名影子（$package）设置为要编制索引并收集指标的每台设备的数据来源。有关预留命名影子的更多信息，请参阅预留命名影子。

实例集索引提供的支持使 AWS IoT 事物能够通过按软件包版本筛选的动态事物组进行分组。例如，实例集索引可以识别已安装或尚未安装特定软件包版本、未安装任何软件包版本或匹配特定名称/值对的事物。最后，实例集索引提供了标准指标和自定义指标，您可以使用这些指标来深入了解设备实例集的状态。有关更多信息，请参阅 准备实例集索引。

预留命名影子

预留命名影子 $package 反映了设备已安装的软件包和软件包版本的状态。实例集索引使用预留命名影子作为数据来源来构建标准指标和自定义指标，以便您可以查询实例集的状态。有关更多信息，请参阅准备实例集索引。

预留命名影子与命名影子类似，唯一的不同是前者的名称是预定义的，您无法对其进行更改。此外，预留命名影子不会使用元数据进行更新，而只使用 version 和 attributes 关键字。

包含其它关键字（例如 description）的更新请求将在 rejected 主题下收到错误响应。有关更多信息，请参阅设备影子错误消息。

当您通过控制台创建 AWS IoT 事物时，当 AWS IoT 任务成功完成并更新影子时，以及如果您发出 UpdateThingShadow 操作时，都可以创建它。有关更多信息，请参阅《AWS IoT Core 开发人员指南》中的 UpdateThingShadow。

$package 影子的结构

预留命名影子包含以下内容：

{
    "state": {
        "reported": {
            "<packageName>": {
                "version": "",
                "attributes": {
                }
            }
        }
    },
    "version" : 1
    "timestamp" : 1672531201
}

影子属性将使用以下信息进行更新：

有关命名影子的格式和行为的更多信息，请参阅 AWS IoT 设备影子服务 消息顺序。

删除软件包及其软件包版本

在删除软件包之前，请执行以下操作：

只要没有已指定的默认软件包版本，您就可以使用控制台删除软件包，其所有软件包版本也将被删除。如果您使用 API 调用删除软件包，则必须先删除软件包版本，然后再删除软件包。