本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
您可以使用 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类型
如何创建命令（控制台）
要从控制台创建命令，请转到控制台的 Command Hub
-
要创建新的命令资源，请选择创建命令。
-
指定唯一的命令 ID 以帮助您识别要在目标设备上运行的命令。
-
（可选）指定可选的显示名称、描述和任何名称/值对作为命令的标签。
-
从本地存储空间上传包含设备需要执行的操作的有效载荷文件。虽然是可选的，但我们建议您指定有效负载格式类型，以便设备正确解释文件并处理指令。
-
选择创建命令。
本节介绍HTTP控制平面API操作和相应的 AWS CLI 命令 create-command，您可以运行这些操作来创建命令资源。CreateCommand
命令有效载荷
创建命令时，必须提供有效负载。您提供的有效载荷采用 base64 编码。当您的设备收到命令时，设备端逻辑可以处理有效负载并执行指定的操作。为确保您的设备正确接收命令和有效负载，我们建议您指定负载内容类型。
注意
创建命令后，您无法修改有效负载。要修改有效负载，你必须创建一个新命令。
IAM政策示例
在使用此API操作之前，请确保您的IAM策略授权您在设备上执行此操作。以下示例显示了一个允许用户执行CreateCommand操作的IAM策略。
在此示例中：
-
regionap-south-1 -
account-id123456789012 -
command-idLockDoor
{
"Version": "2012-10-17",
"Statement":
{
"Action": "iot:CreateCommand",
"Effect": "Allow",
"Resource": "arn:aws:iot:<region>:<account_id>:command/command-id"
}
}创建命令示例
以下示例显示了如何创建命令。根据您的应用，替换：
-
<command-id>LockDoor -
（可选）
<display-name><description>Lock the doors of my home -
namespace，你可以用它来指定命令的命名空间。一定是AWS-IoT。 -
payload包含有关运行命令时要使用的有效负载及其内容类型的信息。
aws iot create-command \ --command-id<command-id>\ --display-name\ --description<display-name><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 C ommand Hub
除了命令详细信息外，您还可以查看命令历史记录，其中提供了有关在目标设备上执行命令的信息。在设备上运行此命令后，可以在此选项卡上找到有关执行的信息。
使用GetCommandHTTP控制平面API操作或get-command AWS CLI 命令来检索有关命令资源的信息。您必须已经使用CreateCommandAPI请求或创建了命令create-commandCLI。
IAM政策示例
在使用此API操作之前，请确保您的IAM策略授权您在设备上执行此操作。以下示例显示了一个允许用户执行GetCommand操作的IAM策略。
在此示例中：
-
regionap-south-1。 -
account-id123456789023 -
command-idLockDoor
{
"Version": "2012-10-17",
"Statement":
{
"Action": "iot:GetCommand",
"Effect": "Allow",
"Resource": "arn:aws:iot:<region>:<account_id>:command/command-id"
}
}检索命令示例 (AWS CLI)
以下示例说明如何使用检索命令的相关信息get-command AWS CLI。根据您的应用程序，<command-id>create-commandCLI。
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 控制台中，您可以转到 Comm and Hub，找到您创建的命令
要列出您创建的命令，请使用ListCommandsAPI操作或list-commandsCLI。
IAM政策示例
在使用此API操作之前，请确保您的IAM策略授权您在设备上执行此操作。以下示例显示了一个允许用户执行ListCommands操作的IAM策略。
在此示例中：
-
regionap-south-1。 -
account-id123456789012
{
"Version": "2012-10-17",
"Statement":
{
"Action": "iot:ListCommands",
"Effect": "Allow",
"Resource": "arn:aws:iot:<region>:<account_id>:command/*"
}
}在您的账户示例中列出命令
以下命令显示了如何在您的账户中列出命令。
aws iot list-commands --namespace "AWS-IoT"
运行此命令会生成一个响应，其中包含您创建的命令列表、命令的创建时间和上次更新的时间。它还提供命令状态信息，表明命令是否已被弃用或可以在目标设备上运行。有关不同状态和状态原因的更多信息，请参阅命令执行状态。
更新命令资源
创建命令后，可以更新命令的显示名称和描述。
注意
无法更新命令的有效负载。要更新此信息或使用修改后的有效负载，您需要创建一个新命令。
要从控制台更新命令，请转到控制台的 Command Hub
-
要更新现有命令资源，请选择要更新的命令，然后在 “操作” 下选择 “编辑”。
-
指定要使用的显示名称和描述，以及任何名称/值对作为命令的标签。
-
选择 “编辑”，使用新设置保存命令。
使用UpdateCommand控制平面API操作或更新命令资源。update-command AWS CLI 使用这个API，你可以：
-
编辑您创建的命令的显示名称和描述。
-
弃用命令资源，或恢复已经过时的命令。
IAM政策示例
在使用此API操作之前，请确保您的IAM策略授权您在设备上执行此操作。以下示例显示了一个允许用户执行UpdateCommand操作的IAM策略。
在此示例中：
-
regionap-south-1。 -
account-id123456789012 -
command-idLockDoor
{
"Version": "2012-10-17",
"Statement":
{
"Action": "iot:UpdateCommand",
"Effect": "Allow",
"Resource": "arn:aws:iot:<region>:<account_id>: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>
运行此命令会生成一个响应，其中包含有关该命令的更新信息以及上次更新时间。以下代码显示了更新关闭空调的命令的显示名称和描述的示例请求和响应。
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 小时后，它将自动从您的账户中删除。
注意
即使有待执行的命令，该命令也可能被删除。该命令将处于待删除状态，并将自动从您的账户中删除。
要从控制台删除命令，请转到控制台的 Command Hub
-
选择要删除的命令，然后在 “操作” 下选择 “删除”。
-
确认要删除该命令，然后选择删除。
该命令将被标记为删除，并将在12小时后从您的帐户中永久删除。
使用DeleteCommandHTTP控制平面API操作或delete-command AWS CLI 命令删除命令资源。如果删除操作成功，您将看到 204 或 202，并且该命令将在最长超时时间 12 小时后自动从您的帐户中删除。HTTP statusCode如果状态为 204，则表示该命令已被删除。
IAM政策示例
在使用此API操作之前，请确保您的IAM策略授权您在设备上执行此操作。以下示例显示了一个允许用户执行DeleteCommand操作的IAM策略。
在此示例中：
-
regionap-south-1。 -
account-id123456789012 -
command-idLockDoor
{
"Version": "2012-10-17",
"Statement":
{
"Action": "iot:DeleteCommand",
"Effect": "Allow",
"Resource": "arn:aws:iot:<region>:<account_id>:command/command-id"
}
}删除命令示例 (AWS CLI)
以下示例说明如何使用该命令删除delete-command AWS CLI 命令。根据您的应用程序，<command-id>
aws iot delete-command --command-id<command-id>
如果API请求成功，则该命令将生成 202 或 204 的状态码。您可以使用GetCommandAPI来验证您的账户中是否不再存在该命令。
