准备使用软件包目录 - Amazon IoT Core
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

准备使用软件包目录

以下部分概述了 Amazon IoT Device Management 软件包的版本生命周期以及使用 Software Package Catalog 的信息。

软件包版本生命周期

软件包版本可以通过以下生命周期状态演变:draftpublisheddeprecated。也可以是 deleted

包含草稿、已发布和已弃用的软件包版本生命周期。也可以是已删除。
  • 草稿

    当你创建包版本时,它处于draft状态。此状态表示软件包正在准备中或不完整。

    当软件包版本处于这种状态时,您无法对其进行部署。您可以编辑软件包版本的描述、属性和标签。

    您可以使用控制台或deleted通过发出或DeletePackageVersionAPI操作将处于publisheddraft状态的软件包版本过渡到UpdatePackageVersion或状态。

  • 已发布

    当您的软件包版本准备好部署时,请将软件包版本过渡到published状态。在此状态下,您可以选择通过在控制台中编辑软件包或通过UpdatePackageAPI操作将软件包版本标识为默认版本。在此状态下,您只能编辑描述和标签。

    您可以使用控制台或发出或DeletePackageVersionAPI操作将处于deprecatedpublished状态deleted的软件包版本过渡到UpdatePackageVersion或状态。

  • 已弃用

    如果新的软件包版本可用,则可以将较早的软件包版本转换为 deprecated。您仍然可以使用已弃用的软件包版本部署作业。您也可以将已弃用的软件包版本命名为默认版本,并仅编辑描述和标签。

    可以考虑将软件包版本过渡到版本过deprecated时的时候,但由于运行时依赖性,现场仍有设备使用旧版本,或者需要对其进行维护。

    您可以使用控制台或发出或DeletePackageVersionAPI操作将处于publisheddeprecated 状态deleted的软件包版本转换为UpdatePackageVersion或状态。

  • Deleted

    当您不再打算使用某个软件包版本时,可以使用控制台或发出DeletePackageVersionAPI操作将其删除。

    注意

    如果您在有待处理的任务引用软件包版本的情况下删除此版本,则当该任务成功完成并尝试更新预留命名影子时,您将收到错误消息。

    如果您要删除的软件包版本已指定为默认软件包版本,则必须先更新软件包以将另一个版本指定为默认版本,或者将该字段保留为未指定。您可以使用控制台或操作来执行此UpdatePackageVersionAPI操作。(要默认删除任何已命名的软件包版本,请在发出UpdatePackageAPI操作时将unsetDefaultVersion参数设置为 true)。

    如果您通过控制台删除软件包,则会删除与该软件包关联的所有软件包版本,除非其中一个版本指定为默认版本。

软件包版本命名约定

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

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

默认版本

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

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

版本属性

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

使用作业文档创建 Amazon IoT 作业时,也可以选择使用引用属性值的替代变量 ($parameter)。有关更多信息,请参阅准备 Amazon IoT 作业

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

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

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

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

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

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

软件物料清单

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

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

SPDX格式SBOM中的 a 的示例。

软件物料清单的好处

在 Software Package Catalog 中添加软件包版本的软件材料清单的主要好处之一是漏洞管理。

漏洞管理

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

软件物料清单存储

使用 Amazon S3 版本控制功能将每个软件包版本的软件材料清单 (SBOM) 存储在 Amazon S3 存储桶中。存储的 Amazon S3 存储桶SBOM必须位于创建软件包版本的同一区域。使用版本控制功能的 Amazon S3 存储桶将对象的多个变体保存在同一个存储桶中。有关在 Amazon S3 存储桶中使用版本控制的更多信息,请参阅在 Amazon S 3 存储桶中使用版本控制

注意

每个软件包版本只有一个SBOM文件存储为 zip 存档文件。

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

注意

对于包含单个SBOM文件的包版本,您可以将该文件作为 zip 存档SBOM文件存储在 Amazon S3 存储桶中。

对于包含多个SBOM文件的包版本,您必须将所有文件放在单个 zip 存档SBOM文件中,然后将该 zip 存档文件存储在 Amazon S3 存储桶中。

在这两种情况下,存储在单个 zip 存档文件中的所有SBOM文件都被格式化为 CycloneDX .json 文件。SPDX

权限政策

为了 Amazon IoT 充当指定委托人访问存储在 Ama SBOM zon S3 存储桶中的 zip 存档文件,您需要一个基于资源的权限策略。有关正确的基于资源的权限策略,请参阅以下示例:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "iot.amazonaws.com" ] }, "Action": "s3:*", "Resource": "arn:aws:s3:::bucketName/*" } ] }

有关基于资源的权限策略的更多信息,请参阅 Amazon IoT 基于资源的策略

正在更新 SBOM

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

注意

更新软件材料清单会生成新的版本 ID,但不会导致创建新的软件包版本。

有关 Amazon S3 对象密钥的更多信息,请参阅创建对象密钥名称

启用 Amazon IoT 舰队索引

要利用带有 Software Package Catalog 的 Amazon IoT 队列索引,请将名为 shadow ($package) 的预留设备设置为要编入索引并收集指标的每台设备的数据源。有关保留命名阴影的更多信息,请参阅预留命名影子

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

注意

为软件包目录启用实例集索引会产生标准服务成本。有关更多信息,请参阅 Amazon IoT Device Management定价

预留命名影子

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

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

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

它可以在您通过控制台创建 Amazon IoT 事物、 Amazon IoT 任务成功完成并更新影子以及发出UpdateThingShadowAPI操作时创建。有关更多信息,请参阅 Amazon IoT Core 开发者指南UpdateThingShadow中的。

注意

对预留命名影子编制索引不计入实例集索引可以编制索引的命名影子数量。有关更多信息,请参阅 Amazon IoT Device Management 实例集索引限制和限额。此外,如果您选择在任务成功完成时让 Amazon IoT 任务更新预留的名为 shadow,则该API调用将计入您的 Device Shadow 和注册表操作,并且可能会产生费用。有关更多信息,请参阅Amazon IoT Device Management 作业限制和配额以及IndexingFilterAPI数据类型。

$package 影子的结构

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

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

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

  • <packageName>:已安装的软件包的名称,该名称使用packageName参数进行更新。

  • version:已安装软件包版本的名称,该名称使用versionName参数进行更新。

  • attributes:由设备存储并由实例集索引编制索引的可选元数据。这允许客户根据存储的数据查询其索引。

  • version:影子的版本号。每次更新影子时,版本号都会自动递增,从 1 开始。

  • timestamp:表示上次更新影子的时间,并以 Unix 时间记录。

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

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

在删除软件包之前,请执行以下操作:

  • 确认软件包及其版本未处于活动部署状态。

  • 请先删除所有关联的版本。如果其中一个版本指定为默认版本,则必须从软件包中删除指定的默认版本。由于指定默认版本是可选的,因此删除默认版本不会发生冲突。要从软件包中删除默认版本,请通过控制台编辑软件包或使用 UpdatePackageVersionAPI操作。

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