准备使用软件包目录

以下部分概述了软件包的版本生命周期和使用信息 AWS IoT Device Management 软件包 Package 目录。

软件包版本生命周期

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

• 草稿

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

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

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

• 已发布

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

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

• 已弃用

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

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

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

• Deleted

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

  注意

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

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

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

软件包版本命名约定

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

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

默认版本

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

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

版本属性

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

当你创建 AWS IoT job 对于作业文档，您也可以选择使用引用属性值的替代变量 ($parameter)。有关更多信息，请参阅准备 AWS IoT 职位。

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

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

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

正在启用 AWS IoT 机群索引

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

注意

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

预留命名影子

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

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

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

它可以在你创建时创建 AWS IoT 通过控制台进行操作，当 AWS IoT 作业成功完成并更新影子，以及您是否发出UpdateThingShadowAPI操作。有关更多信息，请参阅UpdateThingShadow中的 AWS IoT Core 开发者指南。

注意

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

$package 影子的结构

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

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

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

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

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

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

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

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

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

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

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

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

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

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