创建和管理命令 - Amazon IoT Core
创建命令资源检索关于命令的信息列出你中的命令 Amazon Web Services 账户更新命令资源弃用或恢复命令资源删除命令资源
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

创建和管理命令

使用Amazon IoT Device Management命令配置可重复使用的远程操作或向设备发送即时指令。通过Amazon IoT控制台或使用创建和管理命令Amazon CLI。

创建命令资源

创建命令时提供以下信息：

  • 一般信息

    提供唯一的命令 ID，以便在目标设备上运行命令时识别该命令。（可选）指定用于管理的显示名称、描述和标签。

  • 有效载荷

    对于静态命令，请提供定义设备操作的负载。指定 Payload 格式类型以便正确解释设备。

    有关动态命令，请参阅 Payload 模板属性。

  • 有效载荷模板

    对于动态命令，请提供包含占位符和参数的 PayloadTemplate。（可选）提供defaultValue和条件。 Amazon IoT Device Management命令会在运行时替换占位符。缺少的参数使用其默认值。所有值都必须满足定义的条件。

    支持以下区分大小写的占位符类型：

    • ${aws:iot:commandexecution::parameter:parameter1}— 名称parameter1为的参数值的占位符。

    • ${aws:iot:commandexecution::executionTimeoutSec}— 运行时提供的命令执行超时参数的占位符。

命令保留主题使用基于负载格式类型的格式。

  • 对于application/json我们的application/cbor内容类型，请使用此请求主题：

    $aws/commands/<devices>/<DeviceID>/executions/+/request/<PayloadFormat>

  • 对于其他内容类型或未指定格式，请使用此请求主题。负载格式显示在 MQTT 消息标头中。

    $aws/commands/<devices>/<DeviceID>/executions/+/request

无论负载类型如何，命令响应主题都使用json或cbor格式化。 <PayloadFormat>必须是json或cbor：

$aws/commands/<devices>/<DeviceID>/executions/<ExecutionId>/response/<PayloadFormat>

以下各节介绍了 Payload 格式注意事项和通过控制台创建命令。

静态命令有效载荷格式

有效载荷支持任何不超过 32 KB 的格式。指定 Payload 格式类型以实现安全、正确的设备解释。

使用格式指定 Payload type/subtype 格式类型（例如application/json或application/cbor）。默认值：application/octet-stream。有关支持的格式，请参阅常用 MIME 类型。

动态命令有效载荷格式

PayloadTemplate 必须是有效的 JSON，至少有一个占位符，最多 32 KB。

对于AwsJsonSubstitution预处理器，Amazon IoT Device Management命令会根据预处理器配置以 JSON 或 CBOR 格式发送通知。

如何创建命令（控制台）

要从控制台创建命令，请转到 C ommand Hub 并按照以下步骤操作：

  1. 选择创建命令。

  2. 指定唯一的命令 ID。

  3. （可选）指定显示名称、描述和标签。

  4. 上传包含设备操作的 Payload 文件。指定 Payload 格式类型以便正确解释设备。

  5. （可选）对于带有占位符的 JSON 负载模板，参数会预先填充到行内表中以供编辑。

  6. （可选）配置参数值类型（必填）、默认值和条件。

  7. 选择创建命令。

使用 CreateCommandAP create-commandI 或 CLI 命令创建命令。

命令有效载荷

提供静态负载或负载模板。静态负载采用 base64 编码。对于负载模板，最终的有效载荷在运行时使用参数值生成。设备处理负载并执行指定的操作。指定 Payload 内容类型以便正确接收设备。

注意

命令创建后无法修改有效负载。创建新命令来修改有效负载。

IAM 策略示例

在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 CreateCommand 操作。

在此示例中：

  • 将 region 替换成您的 Amazon Web Services 区域，例如 us-east-1。

  • 将 account-id 替换成您的 Amazon Web Services 账户 编号，例如 123456789012。

  • command-id使用您的Amazon IoT命令 ID 的唯一标识符，例如LockDoor。如果您想发送多个命令，可以在 IAM 策略的资源部分指定这些命令。

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:CreateCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

静态命令创建示例

以下示例说明如何创建静态命令。根据您的应用程序，进行以下替换：

  • 将 <command-id> 替换为命令的唯一标识符。例如，要锁上房屋的门，您可以指定LockDoor。我们建议您使用 UUID。您也可以使用字母数字字符、“-”和“_”。

  • （可选）<display-name> 和 <description>，这些是可选字段，您可以使用它们为命令提供友好名称和有意义的描述，例如 Lock the doors of my home。

  • namespace，您可以使用它来指定命令的命名空间。它必须是 AWS-IoT。有关使用此功能的信息Amazon IoT FleetWise，请参阅远程命令

  • payload 包含关于您要在运行命令时使用的有效载荷及其内容类型的信息。

aws iot create-command \ 
    --command-id <command-id> \
    --display-name <display-name> \
    --description <description> \ 
    --namespace AWS-IoT \ 
    --payload '{"content":"eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=","contentType":"application/json"}'

运行此命令生成一个响应，其中包含命令的 ID 和 ARN（Amazon 资源名称）。例如，如果您在创建期间指定了 LockDoor 命令，以下显示运行命令的示例输出。

{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor"
}

动态命令创建示例

以下示例说明如何创建动态命令。根据您的应用程序，进行以下替换：

  • 将 <command-id> 替换为命令的唯一标识符。例如，要设置灯光电源状态，可以指定Light_Power_Status。我们建议您使用 UUID。您也可以使用字母数字字符、“-”和“_”。

  • （可选）<display-name> 和 <description>，这些是可选字段，您可以使用它们为命令提供友好名称和有意义的描述，例如 Turn a light ON or OFF。

  • namespace，您可以使用它来指定命令的命名空间。它必须是 AWS-IoT。有关使用此功能的信息Amazon IoT FleetWise，请参阅远程命令

  • payloadTemplate包含带有占位符的 JSON 格式的 playoad 模板。

  • preprocessor包含预处理器的配置，用于确定必须如何处理 PayloadTemplate。

  • mandatoryParameter包含与 PayloadTemplate 中占位符对应的参数、其类型、默认值和条件。

aws iot create-command \
    --command-id Light_Power_Status \
    --description "Turn a light ON or OFF" \
    --namespace AWS-IoT \
    --payload-template '{"powerStatus":"${aws:iot:commandexecution::parameter:powerStatus}"}' \
    --preprocessor awsJsonSubstitution={outputFormat=JSON} \
    --mandatory-parameters "name=powerStatus, defaultValue={S=OFF}, valueConditions=[{comparisonOperator=IN_SET, operand={strings=['ON','OFF']}}]"

运行此命令生成一个响应，其中包含命令的 ID 和 ARN（Amazon 资源名称）。例如，如果您在创建期间指定了 Light_Power_Status 命令，以下显示运行命令的示例输出。

{
    "commandId": "Light_Power_Status",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status"
}

检索关于命令的信息

创建命令后，您可以从 Amazon IoT 控制台和使用 Amazon CLI 检索关于它的信息。您可以获取以下信息。

  • 命令 ID、Amazon 资源名称（ARN）、您为命令指定的任何显示名称和描述。

  • 命令状态，指示命令是否可用于在目标设备上运行，或者是否已被弃用或正在删除。

  • 您提供的有效负载或负载模板。

  • 您提供的预处理器。

  • 您提供的必填参数。

  • 创建命令和上次更新命令的时间。

要从控制台检索命令，请转到控制台的 Amazon IoT C ommand Hub，然后选择您创建的命令以查看其详细信息。

除了命令详细信息外，您还可以看到命令历史，它提供关于命令在目标设备上执行的信息。在设备上运行此命令后，您可以在此选项卡上找到关于执行的信息。

使用 GetCommandHTTP 控制平面 API 操作或get-commandAmazon CLI命令来检索有关命令资源的信息。您必须已经使用 CreateCommand API 请求或 create-command CLI 创建了命令。

IAM 策略示例

在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 GetCommand 操作。

在此示例中：

  • 将 region 替换成您的 Amazon Web Services 区域，例如 us-east-1。

  • 将 account-id 替换成您的 Amazon Web Services 账户 编号，例如 123456789023。

  • command-id使用您的Amazon IoT唯一命令标识符，例如LockDoor或Light_Power_Status。如果您想检索多个命令，可以在 IAM 策略的资源部分指定这些命令。

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:GetCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

检索命令示例 (Amazon CLI)

以下示例说明如何使用检索命令的相关信息get-commandAmazon CLI。根据您的应用程序，将 <command-id> 替换为您要检索信息的命令的标识符。您可以从 create-command CLI 的响应中获取此信息。

aws iot get-command --command-id <command-id>

运行此命令生成一个响应，其中包含关于命令、有效载荷以及它被创建和最后更新时间的信息。它还提供指示命令是否已被弃用或正在删除的信息。

例如，以下代码显示一个示例响应。

{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:<region>:<account>:command/LockDoor",
    "namespace": "AWS-IoT",
    "payload":{
        "content": "eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=",
        "contentType": "application/json"
    },
    "createdAt": "2024-03-23T00:50:10.095000-07:00",
    "lastUpdatedAt": "2024-03-23T00:50:10.095000-07:00",
    "deprecated": false,
    "pendingDeletion": false
}

列出你中的命令 Amazon Web Services 账户

创建命令后，您可以查看您在账户中创建的命令。在列表中，您可以找到关于以下信息：

  • 命令 ID，以及您为命令指定的任何显示名称。

  • 命令的 Amazon 资源名称（ARN）。

  • 命令状态，指示命令是否可用于在目标设备上运行，或者是否已被弃用。

    注意

    列表不显示正在从您的账户中删除的命令。如果命令待删除，您仍然可以使用它们的命令 ID 查看这些命令的详细信息。

  • 创建命令和上次更新命令的时间。

在Amazon IoT控制台中，您可以转到 Comm and Hub，找到您创建的命令列表及其详细信息。

要列出您创建的命令，请使用 ListCommands API 操作或 list-commands CLI。

IAM 策略示例

在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 ListCommands 操作。

在此示例中：

  • 将 region 替换成您的 Amazon Web Services 区域，例如 us-east-1。

  • 将 account-id 替换成您的 Amazon Web Services 账户 编号，例如 123456789012。

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:ListCommands",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/*"
    }
}

列出您账户中的命令示例

以下命令说明如何列出您账户中的命令。

aws iot list-commands --namespace "AWS-IoT"

运行此命令会生成一个响应，其中包含您创建的命令列表、命令的创建时间以及最后更新时间。它还提供命令状态信息，指示命令是否已被弃用或可用于在目标设备上运行。有关不同状态和状态原因的更多信息，请参阅 命令执行状态。

更新命令资源

创建命令后，您可以更新命令的显示名称和描述。

注意

命令的有效载荷无法更新。要更新此信息或使用修改后的有效载荷，您需要创建一个新命令。

要从控制台更新命令，请转到控制台的 Command Hub 并执行以下步骤。Amazon IoT

  1. 要更新现有命令资源，选择您要更新的命令，然后在操作下选择编辑。

  2. 指定您要使用的显示名称和描述，以及任何作为命令标签的名称-值对。

  3. 选择编辑以保存具有新设置的命令。

使用UpdateCommand控制平面 API 操作或更新命令资源。update-commandAmazon CLI使用此 API，您可以：

  • 编辑您创建的命令的显示名称和描述。

  • 弃用命令资源，或恢复已弃用的命令。

IAM 策略示例

在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 UpdateCommand 操作。

在此示例中：

  • 将 region 替换成您的 Amazon Web Services 区域，例如 us-east-1。

  • 将 account-id 替换成您的 Amazon Web Services 账户 编号，例如 123456789012。

  • 将 command-id 替换成您的 Amazon IoT 唯一命令标识符，例如 LockDoor。如果您想检索多个命令，可以在 IAM 策略的资源部分指定这些命令。

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:UpdateCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

更新关于命令的信息示例 (Amazon CLI)

以下示例向您展示如何使用命令更新有关命令的信息。update-command Amazon CLI有关如何使用此 API 弃用或恢复命令资源的信息，请参阅 更新命令资源（CLI）。

该示例说明您如何更新命令的显示名称和描述。根据您的应用程序，将 <command-id> 替换为您要检索信息的命令的标识符。

aws iot update-command \ 
    --command-id <command-id>    
    --displayname <display-name> \
    --description <description>

运行此命令会生成一个响应，其中包含关于命令的更新信息以及最后更新时间。以下代码显示一个示例请求和响应，用于更新关闭 AC 的命令的显示名称和描述。

aws iot update-command \ 
    --command-id <LockDoor> \ 
    --displayname <Secondary lock door> \
    --description <Locks doors to my home>

运行此命令会生成以下响应。

{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor",
    "displayName": "Secondary lock door",
    "description": "Locks doors to my home",
    "lastUpdatedAt": "2024-05-09T23:15:53.899000-07:00"
}

弃用或恢复命令资源

创建命令后，如果您不再想继续使用该命令，可以将其标记为已弃用。当您弃用一个命令时，所有待处理的命令执行将继续在目标设备上运行，直到它们达到终端状态。一旦命令被弃用，如果您想使用它（例如向目标设备发送新的命令执行），您必须恢复它。

注意

您无法编辑已弃用的命令，或为其运行任何新的执行。要在设备上运行新命令，您必须恢复它，以便命令状态更改为“可用”。

有关弃用和恢复命令的更多信息及其注意事项，请参阅 弃用命令资源。

删除命令资源

如果您不再想使用某个命令，可以将其从您的账户中永久删除。如果删除操作成功：

  • 如果命令已被弃用的持续时间超过 12 小时的最大超时时间，该命令将被立即删除。

  • 如果命令未被弃用，或已被弃用的持续时间短于最大超时时间，该命令将处于 pending deletion 状态。它将在最大超时时间 12 小时后自动从您的账户中移除。

注意

即使有任何待处理的命令执行，该命令也可能被删除。该命令将处于待删除状态，并将自动从您的账户中移除。

要从控制台删除命令，请转到控制台的 Command Hub 并执行以下步骤。Amazon IoT

  1. 选择要删除的命令，然后在操作下选择删除。

  2. 确认要删除该命令，然后选择删除。

该命令将被标记为待删除，并将在 12 小时后从您的账户中永久移除。

使用 DeleteCommand HTTP 控制平面 API 操作或delete-commandAmazon CLI命令删除命令资源。如果删除操作成功，您将看到 HTTP statusCode 状态码为 204 或 202，并且该命令将在最大超时持续时间 12 小时后自动从您的账户中删除。在状态码为 204 的情况下，表示该命令已被删除。

IAM 策略示例

在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 DeleteCommand 操作。

在此示例中：

  • 将 region 替换成您的 Amazon Web Services 区域，例如 us-east-1。

  • 将 account-id 替换成您的 Amazon Web Services 账户 编号，例如 123456789012。

  • 将 command-id 替换成您的 Amazon IoT 唯一命令标识符，例如 LockDoor。如果您想检索多个命令，可以在 IAM 策略的资源部分指定这些命令。

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:DeleteCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

删除命令示例 (Amazon CLI)

以下示例说明如何使用该命令删除delete-commandAmazon CLI命令。根据您的应用程序，将 <command-id> 替换为要删除的命令的标识符。

aws iot delete-command --command-id <command-id>

如果 API 请求成功，则该命令会生成状态码 202 或 204。您可以使用 GetCommand API 来验证该命令是否已不在您的账户中。