本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 准备使用软件包目录 以下部分概述了 Amazon IoT Device Management 软件包的版本生命周期以及使用 Software Package Catalog 的信息。 ## 程序包版本生命周期 程序包版本可以通过以下生命周期状态演变：`draft`、`published` 和 `deprecated`。也可以是 `deleted`。 ![\[包含草稿、已发布和已弃用的程序包版本生命周期。也可以是已删除。\]](http://docs.amazonaws.cn/iot/latest/developerguide/images/package-catalog-version-lifecycle.png) + **草稿** 创建程序包版本时，它处于 `draft` 状态。此状态表示软件包正在准备中，或者软件包不完整。 当程序包版本处于这种状态时，您将无法部署。您可以编辑程序包版本的描述、属性和标签。 您可以使用控制台`published`或`deleted`通过发出或 [DeletePackageVersion](https://docs.amazonaws.cn/iot/latest/apireference/API_DeletePackageVersion.html)API 操作将处于或`draft`处于状态的软件包版本过渡。[UpdatePackageVersion](https://docs.amazonaws.cn/iot/latest/apireference/API_UpdatePackageVersion.html) + **已发布** 当程序包版本准备就绪可供部署时，将程序包版本转换为 `published` 状态。在此状态下，您可以选择通过在控制台中编辑软件包或通过 [UpdatePackage](https://docs.amazonaws.cn/iot/latest/apireference/API_UpdatePackage.html)API 操作将软件包版本标识为默认版本。在此状态下，您只能编辑描述和标签。 您可以使用控制台或发出或 [DeletePackageVersion](https://docs.amazonaws.cn/iot/latest/apireference/API_DeletePackageVersion.html)API 操作将`deleted`处于`deprecated`或`published`处于状态的软件包版本过渡。[UpdatePackageVersion](https://docs.amazonaws.cn/iot/latest/apireference/API_UpdatePackageVersion.html) + **已弃用** 如果新的程序包版本可用，则可以将较早的程序包版本转换为 `deprecated`。您仍然可以使用已弃用的程序包版本部署任务。您也可以将已弃用的程序包版本指定为默认版本，只编辑描述和标签。 可以考虑在程序包版本过期时将其转换为 `deprecated`，但由于运行时依赖性，您现场仍有设备使用旧版本，或者需要对其进行维护。 您可以使用控制台或发出或 [DeletePackageVersion](https://docs.amazonaws.cn/iot/latest/apireference/API_DeletePackageVersion.html)API 操作将`deleted`处于`published`或`deprecated `处于状态的软件包版本过渡。[UpdatePackageVersion](https://docs.amazonaws.cn/iot/latest/apireference/API_UpdatePackageVersion.html) + **已删除** 当您不再打算使用某个软件包版本时，您可以使用控制台或发出 [DeletePackageVersion](https://docs.amazonaws.cn/iot/latest/apireference/API_DeletePackageVersion.html)API 操作将其删除。 **注意** 如果您在有待处理的任务引用程序包版本的情况下删除此版本，则当该任务成功完成并尝试更新预留命名影子时，您将收到错误消息。 如果您要删除的程序包版本已指定为默认程序包版本，则必须先更新软件包以将另一个版本指定为默认版本，或者将该字段保留为未指定。您可以使用控制台或 [UpdatePackageVersion](https://docs.amazonaws.cn/iot/latest/apireference/API_UpdatePackageVersion.html)API 操作来执行此操作。（要默认删除任何已命名的软件包版本，请在发出 [UpdatePackage](https://docs.amazonaws.cn/iot/latest/apireference/API_UpdatePackage.html)API 操作时将[unsetDefaultVersion](https://docs.amazonaws.cn/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/)。有关软件包版本名称要求的更多信息，请参阅 Amazon IoT API 参考指南中的 [versionN](https://docs.amazonaws.cn/iot/latest/apireference/API_CreatePackageVersion.html#API_CreatePackageVersion_RequestSyntax) ame。 ## 默认版本 将版本设置为默认版本是可选的。您可以添加或删除默认程序包版本。您也可以部署未指定为默认版本的程序包版本。 创建程序包版本时，它处于 `draft` 状态，在将程序包版本转换为已发布状态之前，无法将其指定为默认版本。软件包目录不会自动选择一个版本作为默认版本，也不会将更高的程序包版本更新为默认版本。您必须通过控制台或发出 [UpdatePackageVersion](https://docs.amazonaws.cn/iot/latest/apireference/API_UpdatePackageVersion.html)API 操作来故意命名您选择的软件包版本。 ## 版本属性 版本属性及其值拥有有关程序包版本的重要信息。我们建议您为软件包或程序包版本定义通用属性。例如，您可以为平台、架构、操作系统、发布日期、作者或 Amazon S3 URL 创建名称/值对。 使用作业文档创建 Amazon IoT 作业时，也可以选择使用引用属性值的替代变量 (`$parameter`)。有关更多信息，请参阅[准备 Amazon IoT 作业](https://docs.amazonaws.cn/iot/latest/developerguide/preparing-jobs-for-service-package-catalog.html)。 程序包版本中使用的版本属性不会自动添加到预留命名影子中，也无法直接通过队列索引进行索引或查询。要通过队列索引对程序包版本属性进行索引或查询，可以在预留命名影子中填充版本属性。 我们建议预留命名影子中的版本属性参数捕获报告设备的属性，例如操作系统和安装时间。也可以通过队列索引对它们进行索引和查询。 版本属性无需遵循特定的命名惯例。您可以创建名称/值对以满足您的业务需求。程序包版本上所有属性的总大小限制为 3KB。有关更多信息，请参阅[软件包目录软件包和程序包版本限制](https://docs.amazonaws.cn/general/latest/gr/iot_device_management.html#software_package_catalog_limits)。 **使用任务文档中的所有属性** 您可以将所有程序包版本属性自动添加到选定设备的任务部署中。要通过 API 或 CLI 命令中以编程方式自动使用所有程序包版本属性，请参阅以下任务文档示例： ``` "TestPackage": "${aws:iot:package:TestPackage:version:PackageVersion:attributes}" ``` ## 软件物料清单 软件物料清单（SBOM）针对您软件包的各个方面提供了一个中央存储库。除了存储软件包和软件包版本外，您还可以将与每个软件包版本关联的软件物料清单 (SBOM) 存储在 Softw Amazon 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.amazonaws.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.amazonaws.cn/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 文件。 **权限策略** 为了 Amazon IoT 充当指定委托人访问存储在 Amazon S3 存储桶中的 SBOM zip 存档文件，您需要一个基于资源的权限策略。有关正确的基于资源的权限策略，请参阅以下示例： **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "iot.amazonaws.com" ] }, "Action": "s3:*", "Resource": "arn:aws:s3:::bucketName/*" } ] } ``` 有关基于资源的权限策略的更多信息，请参阅 [Amazon IoT 基于资源的政策](security_iam_service-with-iam.md#security_iam_service-with-iam-resource-based-policies)。 **更新 SBOM** 您可以根据需要经常更新软件物料清单，以保护和增强您的设备实例集。每次更新您的 Amazon S3 存储桶中的软件物料清单时，版本 ID 都会发生变化，并且您必须将新的 Amazon S3 存储桶 URL 与相应的程序包版本相关联。您将在 Amazon Web Services 管理控制台中程序包版本页面上的 **Amazon S3 对象版本 ID** 列看到新版本 ID。此外，您可以使用 API 操作 `[GetPackageVersion](https://docs.amazonaws.cn/iot/latest/apireference/API_GetPackageVersion.html)` 或 CLI 命令 `[get-package-version](https://docs.amazonaws.cn/cli/latest/reference/iot/get-package-version.html)` 来查看新版本 ID。 **注意** 更新软件物料清单会生成新的版本 ID，但不会导致创建新的程序包版本。 有关 Amazon S3 对象键的更多信息，请参阅[创建对象键名称](https://docs.amazonaws.cn/AmazonS3/latest/userguide/object-keys.html)。 ## 启用 Amazon IoT 舰队索引 要使用 Software Package Catal Amazon IoT Device Management og，必须启用 Amazon IoT 队列索引。要利用软件包目录的 Amazon IoT 实例集索引，请将预留命名影子 (`$package`) 设置为要编制索引并收集指标的每台设备的数据来源。有关预留命名影子的更多信息，请参阅 [预留命名影子](#reserved-named-shadow)。 队列索引提供的支持使 Amazon IoT 事物能够通过按软件包版本筛选的动态事物组进行分组。例如，实例集索引可以识别已安装或尚未安装特定程序包版本、未安装任何程序包版本或匹配特定名称/值对的事物。最后，实例集索引提供了标准指标和自定义指标，您可以使用这些指标来深入了解设备实例集的状态。有关更多信息，请参阅 [准备实例集索引](preparing-fleet-indexing.md)。 **注意** 为软件包目录启用实例集索引会产生标准服务成本。有关更多信息，请参阅 [Amazon IoT Device Management定价](https://www.amazonaws.cn/iot-device-management/pricing/)。 ## 预留命名影子 预留命名影子 `$package` 反映了设备已安装的软件包和程序包版本的状态。实例集索引使用预留命名影子作为数据来源来构建标准指标和自定义指标，以便您可以查询实例集的状态。有关更多信息，请参阅[准备实例集索引](https://docs.amazonaws.cn/iot/latest/developerguide/preparing-fleet-indexing.html)。 预留命名影子与[命名影子](https://docs.amazonaws.cn/iot/latest/developerguide/iot-device-shadows.html)类似，唯一的不同是前者的名称是预定义的，您无法对其进行更改。此外，预留命名影子不会使用元数据进行更新，而只使用 `version` 和 `attributes` 关键字。 包含其它关键字（例如 `description`）的更新请求将在 `rejected` 主题下收到错误响应。有关更多信息，请参阅[设备影子错误消息](https://docs.amazonaws.cn/iot/latest/developerguide/device-shadow-error-messages.html)。 它可以在您通过控制台创建 Amazon IoT 事物、 Amazon IoT 任务成功完成并更新影子以及发出 [https://docs.amazonaws.cn/iot/latest/apireference/API_iotdata_UpdateThingShadow.html](https://docs.amazonaws.cn/iot/latest/apireference/API_iotdata_UpdateThingShadow.html)API 操作时创建。有关更多信息，请参阅 Amazon IoT Core 开发者指南[UpdateThingShadow](https://docs.amazonaws.cn/iot/latest/developerguide/device-shadow-rest-api.html#API_UpdateThingShadow)中的。 **注意** 对预留命名影子编制索引不计入实例集索引可以编制索引的命名影子数量。有关更多信息，请参阅 [Amazon IoT Device Management 实例集索引限制和限额](https://docs.amazonaws.cn/general/latest/gr/iot_device_management.html#fleet-indexing-limits)。此外，如果您选择在任务成功完成时让 Amazon IoT 任务更新预留的名为 shadow，则 API 调用将计入您的 Device Shadow 和注册表操作，并且可能会产生费用。有关更多信息，请参阅[Amazon IoT Device Management 任务限制和配额](https://docs.amazonaws.cn/general/latest/gr/iot_device_management.html#job-limits)以及 [IndexingFilter](https://docs.amazonaws.cn/iot/latest/apireference/API_IndexingFilter.html)API 数据类型。 **`$package` 影子的结构** 预留命名影子包含以下内容： ``` { "state": { "reported": { "": { "version": "", "attributes": { } } } }, "version" : 1 "timestamp" : 1672531201 } ``` 影子属性将使用以下信息进行更新： + ``：已安装软件包的名称，该名称使用 [packageName](https://docs.amazonaws.cn/iot/latest/apireference/API_CreatePackage.html#API_CreatePackage_RequestSyntax) 参数进行更新。 + `version`：已安装程序包版本的名称，该版本使用 [versionName](https://docs.amazonaws.cn/iot/latest/apireference/API_CreatePackageVersion.html#API_CreatePackageVersion_RequestSyntax) 参数进行更新。 + `attributes`：由设备存储并由实例集索引编制索引的可选元数据。这允许客户根据存储的数据查询其索引。 + `version`：影子的版本号。每次更新影子时，版本号都会自动递增，从 `1` 开始。 + `timestamp`：表示上次更新影子的时间，并以 [Unix 时间](https://en.wikipedia.org/wiki/Unix_time)记录。 有关命名影子的格式和行为的更多信息，请参阅 [Amazon IoT 设备影子服务 消息顺序](https://docs.amazonaws.cn/iot/latest/developerguide/iot-device-shadows.html#message-ordering)。 ## 删除软件包及其程序包版本 在删除软件包之前，请执行以下操作： + 确认软件包及其版本未处于活动部署状态。 + 请先删除所有关联的版本。如果其中一个版本指定为**默认版本**，则必须从软件包中删除指定的默认版本。由于指定默认版本是可选的，因此删除默认版本不会发生冲突。要从软件包中删除默认版本，请通过控制台编辑软件包或使用 [ UpdatePackageVersion](https://docs.amazonaws.cn/iot/latest/apireference/API_UpdatePackageVersion.html)API 操作。 只要没有已指定的默认程序包版本，您就可以使用控制台删除软件包，其所有程序包版本也将被删除。如果您使用 API 调用删除软件包，则必须先删除程序包版本，然后再删除软件包。