创建和管理命令 - AWS IoT Core
创建命令资源检索关于命令的信息列出您的 AWS 账户 中的命令更新命令资源弃用或恢复命令资源删除命令资源

创建和管理命令

您可以使用 AWS IoT Device Management 命令功能来配置可重用的远程操作或向您的设备发送一次性即时指令。以下各节介绍您如何从 AWS IoT 控制台和使用 AWS CLI 创建和管理命令。

创建命令资源

当您创建命令时，必须提供以下信息。

  • 一般信息

    创建命令时，您必须提供命令 ID，这是一个唯一标识符，帮助您在要在目标设备上运行命令时识别它。或者，您还可以指定显示名称、描述和标签，以进一步帮助您管理命令。

  • 有效载荷

    您还必须提供定义设备必须执行的操作的有效载荷。虽然可选，但我们建议您指定有效载荷格式类型，以便设备正确解释有效载荷。

命令保留主题使用依赖于有效载荷格式类型的格式。

  • 如果您指定有效载荷内容类型为 application/json 或 application/cbor，则请求主题将是以下内容。

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

  • 如果您指定有效载荷内容类型不是 application/json 或 application/cbor，或者如果您未指定有效载荷格式类型，则请求主题将是以下内容。在这种情况下，有效载荷格式将包含在 MQTT 消息头中。

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

命令响应主题将返回使用 json 或 cbor 的格式，独立于有效载荷格式类型。响应主题将使用以下格式，其中 <PayloadFormat> 必须是 json 或 cbor。

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

以下各节介绍命令有效载荷格式考虑事项以及如何从控制台创建命令。

命令有效载荷格式

有效载荷可以使用您选择的任何格式。有效载荷的最大大小不得超过 32 KB。为确保设备能够安全且正确地解释有效载荷，我们建议您指定有效载荷格式类型。

您使用 type/subtype 格式指定有效载荷格式类型，例如 application/json 或 application/cbor。默认情况下，它将被设置为 application/octet-stream。有关您可以指定的有效载荷格式的信息，请参阅常用 MIME 类型。

如何创建命令（控制台）

要从控制台创建命令，请转到 AWS IoT 控制台的命令中心并执行以下步骤。

  1. 要创建新命令资源，请选择创建命令。

  2. 指定一个唯一命令 ID，以帮助您识别要在目标设备上运行的命令。

  3. （可选）指定一个可选的显示名称、描述和任何名称-值对作为命令的标签。

  4. 从本地存储空间上传包含设备需要执行的操作的有效载荷文件。虽然可选，但我们建议您指定有效载荷格式类型，以便设备正确解释文件并处理指令。

  5. 选择创建命令。

本节介绍了 HTTP 控制面板 API 操作 CreateCommand 和相应的 AWS CLI 命令 create-command，您可以运行它们来创建命令资源。

命令有效载荷

创建命令时，您必须提供有效载荷。您提供的有效载荷是 base64 编码的。当您的设备接收命令时，设备端逻辑可以处理有效载荷并执行指定的操作。为确保您的设备正确接收命令和有效载荷，我们建议您指定有效载荷内容类型。

注意

创建命令后，您无法修改有效载荷。要修改有效载荷，您必须创建一个新命令。

IAM 策略示例

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

在此示例中：

  • 将 region 替换成您的 AWS 区域，例如 ap-south-1。

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

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

JSON
{
    "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。

  • 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:ap-south-1:123456789012:command/LockDoor"
}

检索关于命令的信息

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

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

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

  • 您提供的有效载荷及其格式类型。

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

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

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

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

IAM 策略示例

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

在此示例中：

  • 将 region 替换成您的 AWS 区域，例如 ap-south-1。

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

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

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

检索命令示例 (AWS CLI)

以下示例显示您如何使用 get-commandAWS 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
}

列出您的 AWS 账户 中的命令

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

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

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

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

    注意

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

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

在 AWS IoT 控制台中，您可以通过转到命令中心找到您创建的命令列表及其详细信息。

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

IAM 策略示例

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

在此示例中：

  • 将 region 替换成您的 AWS 区域，例如 ap-south-1。

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

JSON
{
    "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"

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

更新命令资源

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

注意

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

要从控制台更新命令，请转到 AWS IoT 控制台的命令中心并执行以下步骤。

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

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

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

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

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

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

IAM 策略示例

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

在此示例中：

  • 将 region 替换成您的 AWS 区域，例如 ap-south-1。

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

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

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

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

以下示例显示您如何使用 update-command AWS 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:ap-south-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 小时后自动从您的账户中移除。

注意

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

要从控制台删除命令，请转到 AWS IoT 控制台的命令中心并执行以下步骤。

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

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

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

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

IAM 策略示例

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

在此示例中：

  • 将 region 替换成您的 AWS 区域，例如 ap-south-1。

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

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

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

删除命令示例 (AWS CLI)

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

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

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