本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 启动和监控命令执行
**重要**
目前对某些 AWS 物联网 FleetWise 功能的访问受到限制。有关更多信息，请参阅 [AWS AWS 物联网中的区域和功能可用性 FleetWise](fleetwise-regions.md)。
创建命令资源后，您可以开始在目标车辆上执行命令。一旦车辆开始执行命令，它就可以开始更新命令执行的结果，并将状态更新和结果信息发布到 MQTT 保留主题中。然后，您可以检索命令执行的状态并监控您账户中执行的状态。
本主题介绍如何使用 AWS CLI 或 AWS 物联网 FleetWise 控制台向车辆发送命令。它还向您展示了如何监视和更新命令执行的状态。
**Topics**
+ [更新命令执行结果](#update-remote-command-execution-cli)
+ [获取命令执行](#get-remote-command-execution-cli)
+ [列出您账户中的命令执行情况](#list-remote-command-execution-cli)
+ [删除命令执行](#delete-remote-command-execution-cli)
## 发送命令（控制台）
要从控制台发送命令，请转到 AWS 物联网 FleetWise 控制台的[车辆](https://console.aws.amazon.com/iotfleetwise/home#/vehicles)页面并执行以下步骤。
1. 选择要向其发送命令的车辆。
1. 选择 **Run command（运行命令）**。
1. 选择命令 ID。
1. 指定命令执行超时，然后选择**运行命令**。
## 发送命令 (AWS CLI)
您可以使用[https://docs.aws.amazon.com/iot/latest/apireference/API_iot_data_StartCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot_data_StartCommandExecution.html) AWS IoT 数据平面 API 操作向车辆发送命令。然后，车辆将命令转发给汽车中间件服务（例如 SOME/IP （基于 IP 的可扩展面向服务的中间件），或者将其发布到车辆网络（例如控制器局域网 (CAN) 设备接口）上。下面的示例使用了 AWS CLI。
**Topics**
+ [发送命令时的注意事项](#send-remote-command-considerations)
+ [获取账户特定的数据面板端点](#send-remote-command-endpoint)
+ [发送命令示例](#send-remote-command-example)
### 发送命令时的注意事项
当你在以下位置开始执行命令时 AWS IoT FleetWise：
+ 你必须为车辆准备 AWS IoT 一件东西。有关更多信息，请参阅 [配置 AWS 物联网 FleetWise 车辆](provision-vehicles.md)。
+ 您必须已经创建了以命名空间`AWS-IoT-FleetWise`为命名空间的命令`role-Arn`，并提供了授予您在 AWS IoT 中创建和运行命令的权限 FleetWise。有关更多信息，请参阅 [创建命令资源](create-manage-remote-command-cli.md#create-remote-command-cli)。
+ 如果您选择使用在创建命令时为参数指定的任何默认值，则可以跳过该`parameters`字段。如果在创建时`mandatory-parameters`未指定，或者您想通过为参数指定自己的值来覆盖任何默认值，则必须指定该`parameters`字段。有关这些其他示例，请参见[命令使用场景](remote-command-use-cases.md)。
+ 您最多可以为该字段指定三个名称/值对。`mandatory-parameters`但是，在车辆上执行命令时，只接受一个名称/值对，并且该`name`字段必须使用带有前缀的完全限定名称。`$actuatorPath.`
### 获取账户特定的数据面板端点
在运行 API 命令之前，您必须获取该终端节点的账户特定终端节点 URL。`iot:Jobs`例如，如果您运行此命令：
```
aws iot describe-endpoint --endpoint-type iot:Jobs
```
它将返回账户特定的端点 URL，如下面的示例响应所示。
```
{
"endpointAddress": ".jobs.iot..amazonaws.com"
}
```
### 发送命令示例
要向车辆发送命令，请运行以下命令。
+ 将要执行的命令替换*command-arn*为 ARN。您可以从 `create-command` CLI 命令的响应中获取此信息。
+ *target-arn*替换为要为其执行命令的目标设备或 AWS IoT 事物的 ARN。
**注意**
您可以指定 AWS IoT 事物（物AWS 联网 FleetWise 车辆）的目标 ARN。目前不支持事物组和队列。
+ *endpoint-url*替换为您在中获得的账户专用端点[获取账户特定的数据面板端点](#send-remote-command-endpoint)，例如，前缀为`https://`。`https://123456789012abcd.jobs.iot.ap-south-1.amazonaws.com`
+ 将*name*和*value*替换为使用 `create-command` CLI 创建命令时指定的`mandatory-parameters`字段。
该`name`字段是信号目录中定义的完全限定名称，前缀`$actuatorPath.`为前缀。例如，`name`可以是也可以是*\$1actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode*表示转向模式状态的布尔值，例如*\$1"B": false\$1*。`value`
+ （可选）您也可以指定其他参数`executionTimeoutSeconds`。此可选字段指定设备必须响应执行结果的时间（以秒为单位）。您可以将超时的最大值配置为 24 小时。
创建命令执行后，计时器启动。在计时器到期之前，如果命令执行状态未更改为使其终止的状态，例如`SUCCEEDED`或`FAILED`，则状态会自动更改为`TIMED_OUT`。
**注意**
设备还可以报告`TIMED_OUT`状态，或者将此状态改写为诸如`SUCCEEDED`、或`FAILED`、之类的状态`REJECTED`，命令执行将变为终止。有关更多信息，请参阅 [命令执行超时状态](remote-command-concepts-states.md#remote-command-execution-status-timeout)。
```
aws iot-jobs-data start-command-execution \
--command-arn command-arn \
--target-arn target-arn \
--execution-timeout-seconds 30 \
--endpoint-url endpoint-url \
--parameters '[
{
"name": name,
"value": value
}
]'
```
`StartCommandExecution`API 操作返回命令执行 ID。您可以使用此 ID 查询命令执行状态、详细信息和命令执行历史记录。
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}
```
运行该命令后，您的设备将收到包含以下信息的通知。该`issued_timestamp_ms`字段对应于调用 `StartCommandExecution` API 的时间。对`timeout_ms`应于在调用 `StartCommandExecution` API 时使用`executionTimeoutSeconds`参数配置的超时值。
```
timeout_ms: 9000000
issued_timestamp_ms: 1723847831317
```
## 更新命令执行结果
要更新命令执行状态，您的设备必须已建立 MQTT 连接并订阅了以下命令请求主题。
在此示例中，*``*替换为目标设备的唯一标识符（可以是`VehicleId`或事物的名称），并*``*替换为命令执行的标识符。
**注意**
有效载荷必须使用 protobuf 格式。
您的设备可以选择订阅`/accepted`和`/rejected`回复主题。即使您的设备没有明确订阅这些回复消息，它们也会收到这些回复消息。
```
// Request topic
$aws/devices//command_executions/+/request/protobuf
// Response topics (Optional)
$aws/devices//command_executions//response/accepted/protobuf
$aws/devices//command_executions//response/rejected/protobuf
```
您的设备可以向命令响应主题发布消息。处理完命令后，它会向该主题发送一个 protobuf 编码的响应。该**字段必须与请求主题中的相应字段匹配。
```
$aws/devices//command_executions//response/
```
在您的设备发布对此主题的响应后，您可以使用 `GetCommandExecution` API 检索更新的状态信息。命令执行的状态可以是此处列出的任何状态。
+ `IN_PROGRESS`
+ `SUCCEEDED`
+ `FAILED`
+ `REJECTED`
+ `TIMED_OUT`
请注意，任何状态`SUCCEEDED``FAILED`、和的命令执行`REJECTED`都是终止的，并且状态由设备报告。当命令执行处于终止状态时，这意味着不会对其状态或相关字段进行进一步的更新。设备或云端可能会报告`TIMED_OUT`状态。如果云端报告了状态，则设备稍后可能会更新状态原因字段。
例如，下面显示了设备发布的 MQTT 消息示例。
**注意**
对于命令执行状态，如果您的设备使用`statusReason`对象发布状态信息，则必须确保：
`reasonCode`使用该模式`[A-Z0-9_-]+`，其长度不超过 64 个字符。
的长度`reasonDescription`不超过 1,024 个字符。它可以使用除控制字符（如换行符）之外的任何字符。
```
{
"deviceId": "",
"executionId": "",
"status": "CREATED",
"statusReason": {
"reasonCode": "",
"reasonDescription": ""
}
}
```
有关展示如何使用 AWS IoT Core MQTT 测试客户端订阅主题和查看命令执行消息的示例，请参阅*AWS IoT Core 开发者*指南中的[使用 MQTT 测试客户端查看命令更新](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-execution-start-monitor.html#iot-remote-command-execution-update-mqtt)。
## 获取命令执行
您可以使用[https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html) AWS IoT 控制平面 API 操作来检索有关命令执行的信息。您必须已经使用 `StartCommandExecution` API 操作执行了此命令。
要检索已执行命令的元数据，请运行以下命令。
+ *execution-id*替换为命令的 ID。您可以从 `start-command-execution` CLI 命令的响应中获取此信息。
+ *target-arn*替换为要执行命令的目标车辆或 AWS IoT 事物的 ARN。
```
aws iot get-command-execution --execution-id execution-id \
--target-arn target-arn
```
`GetCommandExecution`API 操作返回一个响应，其中包含有关命令执行的 ARN、执行状态以及命令开始执行的时间和完成时间的信息。以下代码显示 API 请求的示例响应。
为了提供有关每个命令执行状态的更多上下文，命令功能提供了一个`statusReason`对象。该对象包含两个字段，`reasonCode`和`reasonDescription`。使用这些字段，您的设备可以提供有关命令执行状态的更多信息。此信息将覆盖云端报告的所有默认`reasonCode`信息。`reasonDescription`
要报告此信息，您的设备可以将更新的状态信息发布到云端。然后，当您使用 `GetCommandExecution` API 检索命令执行状态时，您将看到最新的状态代码。
**注意**
执行响应中的 `completedAt` 字段对应于设备向云端报告终端状态的时间。对于`TIMED_OUT`状态，只有当设备报告超时时，才会设置此字段。当 `TIMED_OUT` 状态由云端设置时，`TIMED_OUT` 状态不会更新。有关超时行为的更多信息，请参阅 [命令执行超时状态](remote-command-concepts-states.md#remote-command-execution-status-timeout)。
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/LockDoor",
"targetArn": "arn:aws:iot:ap-south-1:123456789012:thing/myFrontDoor",
"status": "SUCCEEDED",
"statusReason": {
"reasonCode": "65536",
"reasonDescription": "SUCCESS"
},
"createdAt": "2024-03-23T00:50:10.095000-07:00",
"completedAt": "2024-03-23T00:50:10.095000-07:00",
"Parameters": '{
"$actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode":
{ "B": true }
}'
}
```
## 列出您账户中的命令执行情况
使用[https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommandExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommandExecutions.html) AWS IoT Core 控制平面 HTTP API 操作列出您账户中的所有命令执行情况。该示例使用 AWS CLI。
**Topics**
+ [列出命令执行时的注意事项](#list-remote-command-considerations)
+ [列出命令执行示例](#list-remote-command-example)
### 列出命令执行时的注意事项
以下是使用 `ListCommandExecutions` API 时的一些注意事项。
+ 您必须至少指定`targetArn`或，`commandArn`具体取决于您是要列出特定命令还是目标车辆的执行情况。API 请求不能为空，也不能在同一个请求中包含两个字段。
+ 您只能提供`startedTimeFilter`或`completedTimeFilter`信息。API 请求不能为空，也不能在同一个请求中包含两个字段。您可以使用对象的`before`和`after`字段列出在特定时间范围内创建或完成的命令执行。
+ `before`和`after`字段都不能大于当前时间。默认情况下，如果您未指定任何值，则该`before`字段为当前时间，`after`字段为当前时间-6 个月。也就是说，根据您使用的筛选条件，API 将列出过去六个月内创建或完成的所有执行。
+ 您可以使用`sort-order`参数来指定是否要按升序列出执行次数。默认情况下，如果您未指定此字段，则执行将按降序列出。
+ 在列出命令 ARN 的命令执行时，您无法根据命令执行的状态筛选命令执行。
### 列出命令执行示例
以下示例显示如何列出您 AWS 账户中的命令执行。
运行命令时，您必须指定是否筛选列表，以仅显示使用 `targetArn` 为特定设备创建的命令执行，或使用 `commandArn` 为特定命令指定的执行。
在此示例中：
+ *``* 与您要执行命令的目标设备的 Amazon 资源编号（ARN），例如 `arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f`。
+ *``* 与您要执行命令的目标设备的 Amazon 资源编号（ARN），例如 `arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f`。
+ *``* 与您希望列出在此时间之后创建的执行的时间，例如 `2024-11-01T03:00`。
```
aws iot list-command-executions \
--target-arn \
--started-time-filter '{after=}' \
--sort-order "ASCENDING"
```
运行此命令会生成一个响应，其中包含您创建的命令执行列表，以及执行开始和完成的时间。它还提供状态信息，以及包含有关状态附加信息的 `statusReason` 对象。
```
{
"commandExecutions": [
{
"commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002",
"executionId": "b2b654ca-1a71-427f-9669-e74ae9d92d24",
"targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f",
"status": "TIMED_OUT",
"createdAt": "2024-11-24T14:39:25.791000-08:00",
"startedAt": "2024-11-24T14:39:25.791000-08:00"
},
{
"commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002",
"executionId": "34bf015f-ef0f-4453-acd0-9cca2d42a48f",
"targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f",
"status": "IN_PROGRESS",
"createdAt": "2024-11-24T14:05:36.021000-08:00",
"startedAt": "2024-11-24T14:05:36.021000-08:00"
}
]
}
```
## 删除命令执行
如果您不再想使用某个命令执行，可以将其从您的账户中永久删除。
**注意**
只有当命令执行进入终端状态（例如 `SUCCEEDED`、`FAILED` 或 `REJECTED`）时，才能将其删除。
以下示例说明如何使用该命令删除`delete-command-execution` AWS CLI 命令执行。*``*替换为要删除的命令执行的标识符。
```
aws iot delete-command-execution --execution-id
```
如果 API 请求成功，则该命令执行会生成状态码 200。您可以使用 `GetCommandExecution` API 来验证该命令执行是否已不在您的账户中。