本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 创建和管理命令 使用 AWS IoT Device Management 命令配置可重复使用的远程操作或向设备发送即时指令。通过 AWS IoT 控制台或使用创建和管理命令 AWS CLI。 **Topics** + [创建命令资源](#iot-remote-command-create) + [检索关于命令的信息](#iot-remote-command-get) + [列出你中的命令 AWS 账户](#iot-remote-command-list) + [更新命令资源](#iot-remote-command-update) + [弃用或恢复命令资源](#iot-remote-command-deprecatecmd) + [删除命令资源](#iot-remote-command-delete) ## 创建命令资源 创建命令时提供以下信息： + **一般信息** 提供唯一的命令 ID，以便在目标设备上运行命令时识别该命令。（可选）指定用于管理的显示名称、描述和标签。 + **有效载荷** 对于静态命令，请提供定义设备操作的负载。指定 Payload 格式类型以便正确解释设备。 有关动态命令，请参阅 Payload 模板属性。 + **有效载荷模板** 对于动态命令，请提供包含占位符和参数的 PayloadTemplate。（可选）提供`defaultValue`和条件。 AWS IoT Device Management 命令会在运行时替换占位符。缺少的参数使用其默认值。所有值都必须满足定义的条件。 支持以下区分大小写的占位符类型： + `${aws:iot:commandexecution::parameter:parameter1}`— 名称`parameter1`为的参数值的占位符。 + `${aws:iot:commandexecution::executionTimeoutSec}`— 运行时提供的命令执行超时参数的占位符。 ### 有效载荷和命令主题 命令保留主题使用基于负载格式类型的格式。 + 对于`application/json`我们的`application/cbor`内容类型，请使用此请求主题： ``` $aws/commands///executions/+/request/ ``` + 对于其他内容类型或未指定格式，请使用此请求主题。有效负载格式显示在 MQTT 消息标头中。 ``` $aws/commands///executions/+/request ``` 无论负载类型如何，命令响应主题都使用`json`或`cbor`格式化。 **必须是`json`或`cbor`： ``` $aws/commands///executions//response/ ``` ### 创建命令资源（控制台） 以下各节介绍了 Payload 格式注意事项和通过控制台创建命令。 **Topics** + [静态命令有效载荷格式](#iot-commands-payload-format) + [动态命令有效载荷格式](#iot-commands-dynamic-payload-format) + [如何创建命令（控制台）](#iot-commands-console-how) #### 静态命令有效载荷格式 有效载荷支持任何不超过 32 KB 的格式。指定 Payload 格式类型以实现安全、正确的设备解释。 使用`type/subtype`格式（例如`application/json`或`application/cbor`）指定负载格式类型。默认值：`application/octet-stream`。有关支持的格式，请参阅[常用 MIME 类型](https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types/Common_types)。 #### 动态命令有效载荷格式 PayloadTemplate 必须是有效的 JSON，至少有一个占位符，最多 32 KB。 对于`AwsJsonSubstitution`预处理器， AWS IoT Device Management 命令会根据预处理器配置以 JSON 或 CBOR 格式发送通知。 #### 如何创建命令（控制台） 要从控制台创建命令，请转到 C [ommand Hub](https://console.aws.amazon.com/iot/home#/commandHub) 并按照以下步骤操作： 1. 选择**创建命令**。 1. 指定唯一的命令 ID。 1. （可选）指定显示名称、描述和标签。 1. 上传包含设备操作的 Payload 文件。指定 Payload 格式类型以便正确解释设备。 1. （可选）对于带有占位符的 JSON 负载模板，参数会预先填充到行内表中以供编辑。 1. （可选）配置参数值类型（必填）、默认值和条件。 1. 选择**创建命令**。 ### 创建命令资源（CLI） 使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html)AP [https://docs.aws.amazon.com/cli/latest/reference/iot/create-command.html](https://docs.aws.amazon.com/cli/latest/reference/iot/create-command.html)I 或 CLI 命令创建命令。 **Topics** + [命令有效载荷](#iot-commands-payload) + [IAM 策略示例](#iot-remote-command-create-iam) + [静态命令创建示例](#iot-remote-command-create-example) + [动态命令创建示例](#iot-remote-dynamic-command-create-example) #### 命令有效载荷 提供静态负载或负载模板。静态负载采用 base64 编码。对于负载模板，最终的有效载荷在运行时使用参数值生成。设备处理负载并执行指定的操作。指定 Payload 内容类型以便正确接收设备。 **注意** 命令创建后无法修改有效负载。创建新命令来修改有效负载。 #### IAM 策略示例 在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 `CreateCommand` 操作。 在此示例中： + 将 `region` 替换成您的 AWS 区域，例如 `us-east-1`。 + 将 `account-id` 替换成您的 AWS 账户 编号，例如 `123456789012`。 + `command-id`使用您的 AWS 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" } } ``` #### 静态命令创建示例 以下示例显示了如何创建静态命令。根据您的应用程序，进行以下替换： + 将 *``* 替换为命令的唯一标识符。例如，要锁上房屋的门，您可以指定*`LockDoor`*。我们建议您使用 UUID。您也可以使用字母数字字符、“-”和“\$1”。 + （可选）*``* 和 *``*，这些是可选字段，您可以使用它们为命令提供友好名称和有意义的描述，例如 *`Lock the doors of my home`*。 + `namespace`，您可以使用它来指定命令的命名空间。它必须是 `AWS-IoT`。有关使用此功能的信息 AWS IoT FleetWise，请参阅[远程命令](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html) + `payload` 包含关于您要在运行命令时使用的有效载荷及其内容类型的信息。 ``` aws iot create-command \ --command-id \ --display-name \ --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" } ``` #### 动态命令创建示例 以下示例显示了如何创建动态命令。根据您的应用程序，进行以下替换： + 将 *``* 替换为命令的唯一标识符。例如，要设置灯光电源状态，可以指定*`Light_Power_Status`*。我们建议您使用 UUID。您也可以使用字母数字字符、“-”和“\$1”。 + （可选）*``* 和 *``*，这些是可选字段，您可以使用它们为命令提供友好名称和有意义的描述，例如 *`Turn a light ON or OFF`*。 + `namespace`，您可以使用它来指定命令的命名空间。它必须是 `AWS-IoT`。有关使用此功能的信息 AWS IoT FleetWise，请参阅[远程命令](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-commands.html) + `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" } ``` ## 检索关于命令的信息 创建命令后，您可以从 AWS IoT 控制台和使用 AWS CLI检索关于它的信息。您可以获取以下信息。 + 命令 ID、Amazon 资源名称（ARN）、您为命令指定的任何显示名称和描述。 + 命令状态，指示命令是否可用于在目标设备上运行，或者是否已被弃用或正在删除。 + 您提供的有效负载或负载模板。 + 您提供的预处理器。 + 您提供的必填参数。 + 创建命令和上次更新命令的时间。 ### 检索命令资源（控制台） 要从控制台检索命令，请转到控制台的 AWS IoT C [ommand Hub](https://console.aws.amazon.com/iot/home#/commandHub)，然后选择您创建的命令以查看其详细信息。 除了命令详细信息外，您还可以看到命令历史，它提供关于命令在目标设备上执行的信息。在设备上运行此命令后，您可以在此选项卡上找到关于执行的信息。 ### 检索命令资源（CLI） 使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html)HTTP 控制平面 API 操作或[https://docs.aws.amazon.com/cli/latest/reference/get-command.html](https://docs.aws.amazon.com/cli/latest/reference/get-command.html) AWS CLI 命令来检索有关命令资源的信息。您必须已经使用 `CreateCommand` API 请求或 `create-command` CLI 创建了命令。 #### IAM 策略示例 在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 `GetCommand` 操作。 在此示例中： + 将 `region` 替换成您的 AWS 区域，例如 `us-east-1`。 + 将 `account-id` 替换成您的 AWS 账户 编号，例如 `123456789023`。 + `command-id`使用您的 AWS 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" } } ``` #### 检索命令示例 (AWS CLI) 以下示例说明如何使用检索命令的相关信息`get-command` AWS CLI。根据您的应用程序，将 *``* 替换为您要检索信息的命令的标识符。您可以从 `create-command` CLI 的响应中获取此信息。 ``` aws iot get-command --command-id ``` 运行此命令生成一个响应，其中包含关于命令、有效载荷以及它被创建和最后更新时间的信息。它还提供指示命令是否已被弃用或正在删除的信息。 例如，以下代码显示一个示例响应。 ``` { "commandId": "LockDoor", "commandArn": "arn:aws:iot:::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，找到您创建的命令](https://console.aws.amazon.com/iot/home#/commandHub)列表及其详细信息。 ### 列出您账户中的命令（CLI） 要列出您创建的命令，请使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html) API 操作或 [https://docs.aws.amazon.com/cli/latest/reference/iot/list-commands.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-commands.html) CLI。 #### IAM 策略示例 在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 `ListCommands` 操作。 在此示例中： + 将 `region` 替换成您的 AWS 区域，例如 `us-east-1`。 + 将 `account-id` 替换成您的 AWS 账户 编号，例如 `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" ``` 运行此命令会生成一个响应，其中包含您创建的命令列表、命令的创建时间以及最后更新时间。它还提供命令状态信息，指示命令是否已被弃用或可用于在目标设备上运行。有关不同状态和状态原因的更多信息，请参阅 [命令执行状态](iot-remote-command-concepts.md#iot-command-execution-status)。 ## 更新命令资源 创建命令后，您可以更新命令的显示名称和描述。 **注意** 命令的有效载荷无法更新。要更新此信息或使用修改后的有效载荷，您需要创建一个新命令。 ### 更新命令资源（控制台） 要从控制台更新命令，请转到控制台的 [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) 并执行以下步骤。 AWS IoT 1. 要更新现有命令资源，选择您要更新的命令，然后在**操作**下选择**编辑**。 1. 指定您要使用的显示名称和描述，以及任何作为命令标签的名称-值对。 1. 选择**编辑**以保存具有新设置的命令。 ### 更新命令资源（CLI） 使用[https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCommand.html)控制平面 API 操作或更新命令资源。[https://docs.aws.amazon.com/cli/latest/reference/iot/update-command.html](https://docs.aws.amazon.com/cli/latest/reference/iot/update-command.html) AWS CLI 使用此 API，您可以： + 编辑您创建的命令的显示名称和描述。 + 弃用命令资源，或恢复已弃用的命令。 #### IAM 策略示例 在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 `UpdateCommand` 操作。 在此示例中： + 将 `region` 替换成您的 AWS 区域，例如 `us-east-1`。 + 将 `account-id` 替换成您的 AWS 账户 编号，例如 `123456789012`。 + 将 `command-id` 替换成您的 AWS IoT 唯一命令标识符，例如 `LockDoor`。如果您想检索多个命令，可以在 IAM 策略的*资源*部分指定这些命令。 **** ``` { "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）](iot-remote-command-deprecate.md#iot-remote-command-deprecate-cli)。 该示例说明您如何更新命令的显示名称和描述。根据您的应用程序，将 *``* 替换为您要检索信息的命令的标识符。 ``` aws iot update-command \ --command-id --displayname \ --description ``` 运行此命令会生成一个响应，其中包含关于命令的更新信息以及最后更新时间。以下代码显示一个示例请求和响应，用于更新关闭 AC 的命令的显示名称和描述。 ``` aws iot update-command \ --command-id \ --displayname \ --description ``` 运行此命令会生成以下响应。 ``` { "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" } ``` ## 弃用或恢复命令资源 创建命令后，如果您不再想继续使用该命令，可以将其标记为已弃用。当您弃用一个命令时，所有待处理的命令执行将继续在目标设备上运行，直到它们达到终端状态。一旦命令被弃用，如果您想使用它（例如向目标设备发送新的命令执行），您必须恢复它。 **注意** 您无法编辑已弃用的命令，或为其运行任何新的执行。要在设备上运行新命令，您必须恢复它，以便命令状态更改为“*可用*”。 有关弃用和恢复命令的更多信息及其注意事项，请参阅 [弃用命令资源](iot-remote-command-deprecate.md)。 ## 删除命令资源 如果您不再想使用某个命令，可以将其从您的账户中永久删除。如果删除操作成功： + 如果命令已被弃用的持续时间超过 12 小时的最大超时时间，该命令将被立即删除。 + 如果命令未被弃用，或已被弃用的持续时间短于最大超时时间，该命令将处于 `pending deletion` 状态。它将在最大超时时间 12 小时后自动从您的账户中移除。 **注意** 即使有任何待处理的命令执行，该命令也可能被删除。该命令将处于待删除状态，并将自动从您的账户中移除。 ### 删除命令资源（控制台） 要从控制台删除命令，请转到控制台的 [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) 并执行以下步骤。 AWS IoT 1. 选择要删除的命令，然后在**操作**下选择**删除**。 1. 确认要删除该命令，然后选择**删除**。 该命令将被标记为待删除，并将在 12 小时后从您的账户中永久移除。 ### 删除命令资源（CLI） 使用 `DeleteCommand` HTTP 控制平面 API 操作或`delete-command` AWS CLI 命令删除命令资源。如果删除操作成功，您将看到 HTTP `statusCode` 状态码为 204 或 202，并且该命令将在最大超时持续时间 12 小时后自动从您的账户中删除。在状态码为 204 的情况下，表示该命令已被删除。 #### IAM 策略示例 在使用此 API 操作之前，请确保您的 IAM 策略授权您对设备执行此操作。以下示例显示一个 IAM 策略，允许用户执行 `DeleteCommand` 操作。 在此示例中： + 将 `region` 替换成您的 AWS 区域，例如 `us-east-1`。 + 将 `account-id` 替换成您的 AWS 账户 编号，例如 `123456789012`。 + 将 `command-id` 替换成您的 AWS IoT 唯一命令标识符，例如 `LockDoor`。如果您想检索多个命令，可以在 IAM 策略的*资源*部分指定这些命令。 **** ``` { "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 命令。根据您的应用程序，将 *``* 替换为要删除的命令的标识符。 ``` aws iot delete-command --command-id ``` 如果 API 请求成功，则该命令会生成状态码 202 或 204。您可以使用 `GetCommand` API 来验证该命令是否已不在您的账户中。