创建和管理命令 - AWS IoT FleetWise
创建命令资源检索有关命令的信息在你的账户中列出命令更新或弃用命令资源删除命令资源

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

创建和管理命令

重要

目前对某些 AWS 物联网 FleetWise 功能的访问受到限制。有关更多信息，请参阅 AWSAWS 物联网中的区域和功能可用性 FleetWise。

您可以配置可重复使用的远程操作或向您的设备发送一次性即时指令。使用此功能时，您可以指定您的设备可以近乎实时地执行的指令。命令允许您为目标车辆配置可重复使用的远程操作。创建命令后，您可以开始执行针对特定车辆的命令。

本主题介绍如何使用 AWS IoT Core API 或创建和管理命令资源 AWS CLI。它向您展示了如何对命令资源执行以下操作。

创建命令资源

您可以使用CreateCommand AWS IoT Core 控制平面 API 操作或 AWS 物联网 FleetWise 控制台来创建命令。

您可以使用 AWS IoT FleetWise 控制台创建命令。

创建命令

  1. 打开AWS 物联网 FleetWise 控制台。

  2. 在导航窗格上，选择命令。

  3. 选择创建命令。

  4. 指定唯一的命令 ID 以帮助您识别要在车辆上运行的命令。

  5. （可选）指定可选的显示名称和描述。

  6. （可选）选择执行器和默认参数值。参数指定目标车辆在收到命令后可以执行的操作。如果不添加参数，则需要在运行命令时提供这些参数。

  7. 选择一个 IAM 角色来授予为命令生成有效负载的权限。请参阅控制访问权限。

  8. 选择创建命令。

以下示例说明如何使用参数创建命令。

创建命令时的注意事项

当你在以下位置创建命令时 AWS IoT FleetWise：

  • 您必须指定授roleArn予在车辆上创建和运行命令的权限。有关更多信息以及示例策略（包括何时启用 KMS 密钥），请参阅授 AWS IoT Device Management 予使用以下命令生成有效负载的权限 AWS IoT FleetWise。

  • 必须指定AWS-IoT-FleetWise为命名空间。

  • 您可以跳过该mandatory-parameters字段，改为在运行时指定它们。或者，您可以创建带有参数的命令，也可以选择为它们指定默认值。如果您指定了默认值，则在运行时，您可以使用这些值或通过指定自己的值来覆盖它们。有关这些其他示例，请参见命令使用场景。

  • 您最多可以为该字段指定三个名称/值对。mandatory-parameters但是，在车辆上执行命令时，只接受一个名称/值对，并且该name字段必须使用带有前缀的完全限定名称。$actuatorPath.

  • command-id替换为命令的唯一标识符。您可以使用 UUID、字母数字字符、“-” 和 “_”。

  • role-arn替换为授予您创建和运行命令权限的 IAM 角色，例如"arn:aws:iam:accountId:role/FwCommandExecutionRole"。

  • （可选）display-name替换为用户友好的命令description名称以及对命令的有意义的描述。

  • 将mandatory-parameters对象namevalue的 and 替换为正在创建的命令所需的信息。该name字段是信号目录中定义的完全限定名称，前缀$actuatorPath.为前缀。例如，name可以是也可以是$actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode表示转向模式状态的布尔值，例如{"B": false}。value

aws iot create-command --command-id command-id \ 
    --role-arn role-arn \
    --description description \
    --display-name display-name \     
    --namespace "AWS-IoT-FleetWise" \
    --mandatory-parameters '[
        {
            "name": name, 
            "value": value
        }
   ]'

CreateCommandAPI 操作返回的响应包含命令的 ID 和 ARN（亚马逊资源名称）。

{
    "commandId": "HandsOffSteeringMode",
    "commandArn": "arn:aws:iot:ap-south-1:123456789012:command/HandsOffSteeringMode"
}

检索有关命令的信息

您可以使用GetCommand AWS IoT Core 控制平面 API 操作来检索有关命令资源的信息。

要获取有关命令资源的信息，请运行以下命令。command-id替换为创建命令时使用的标识符。

aws iot get-command --command-id command-id

GetCommandAPI 操作会返回包含以下信息的响应。

  • 命令的 ID 和 ARN（亚马逊资源名称）。

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

  • 指示是否可以在车辆上运行的命令状态。

  • 您在创建命令时指定的任何参数。

{
    "commandId": "HandsOffSteeringMode",
    "commandArn": "arn:aws:iot:ap-south-1:123456789012:command/HandsOffSteeringMode"",
    "namespace": "AWS-IoT-FleetWise",
    "mandatoryParameters":[
        {
            "name": "$actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode",
            "value": {"B": false }
        }
    ],
    "createdAt": "2024-03-23T11:24:14.919000-07:00",
    "lastUpdatedAt": "2024-03-23T11:24:14.919000-07:00",
    "deprecated": false,
    "pendingDeletion": false
}

在你的账户中列出命令

您可以使用ListCommands AWS IoT Core 控制平面 API 操作列出您在账户中创建的所有命令。

要列出您账户中的命令，请运行以下命令。默认情况下，API 会返回为两个命名空间创建的命令。要筛选列表以仅显示为其创建的命令 AWS IoT FleetWise，请运行以下命令。

注意

您也可以按升序或降序对列表进行排序，或者筛选列表以仅显示具有特定命令参数名称的命令。

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

ListCommandsAPI 操作会返回包含以下信息的响应。

  • 命令的 ID 和 ARN（亚马逊资源名称）。

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

  • 指示命令是否可在车辆上运行的命令状态。

更新或弃用命令资源

您可以使用UpdateCommand AWS IoT Core 控制平面 API 操作或 I AWS oT FleetWise 控制台来更新命令资源。您可以更新命令的显示名称和描述。如果当前未使用某个命令，也可以将其弃用。

注意

在执行命令时，您无法修改命名空间信息或要使用的参数。

更新命令

要从控制台更新命令，请转到 AWS 物联网 FleetWise 控制台的命令页面并执行以下步骤。

  1. 选择要更新的命令，然后选择 “编辑”。

  2. 编辑命令详细信息，然后选择 “保存更改”。

弃用命令

要弃用控制台中的命令，请转到 AWS 物联网 FleetWise 控制台的命令页面并执行以下步骤。

  1. 选择要弃用的命令，然后选择 Deprecate。

  2. 确认弃用，然后选择 “弃用”。

更新命令

要更新命令资源，请运行以下命令。command-id替换为要更新的命令的标识符，并提供更新的display-name和description。

aws iot update-command \ 
    --command-id command-id \ 
    --display-name display-name \ 
    --description description

UpdateCommandAPI 操作返回以下响应。

{
    "commandId": "HandsOffSteeringMode",
    "deprecated": false,
    "lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00"
}
弃用命令

如果您打算不再在设备上继续使用某个命令，或者该命令已过时，则可以弃用该命令。以下示例说明如何弃用命令。

aws iot update-command \ 
    --command-id command-id \ 
    --deprecated

UpdateCommandAPI 操作返回的响应包含命令的 ID 和 ARN（亚马逊资源名称）。

{
    "commandId": "HandsOffSteeringMode",
    "deprecated": true,
    "lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00"
}

命令被弃用后，现有的命令执行将继续在车辆上运行，直到它们变为终端。要运行任何新的命令执行，必须使用 UpdateCommand API 恢复命令以使其可用。有关弃用和恢复命令的更多信息及其注意事项，请参阅《开发人员指南》AWS IoT Core 中的弃用命令资源。

删除命令资源

您可以使用DeleteCommand AWS IoT Core 控制平面 API 操作或 AWS 物联网 FleetWise 控制台来删除命令资源。

注意

删除是永久性操作，无法撤消。该命令将从您的账户中永久删除。

要从控制台删除命令，请转到 AWS 物联网 FleetWise 控制台的命令页面并执行以下步骤。

  1. 选择要删除的命令，然后选择 “删除”。

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

要删除命令资源，请运行以下命令。command-id替换为要删除的命令的标识符。以下示例说明如何删除命令资源。

aws iot delete-command --command-id command-id

如果删除请求成功：

  • 如果该命令的弃用时间超过了最大超时时间 24 小时，则该命令将被立即删除，并且您将看到 HTTP statusCode 为 204。

  • 如果该命令未被弃用，或者已被弃用的时间短于最大超时时间，则该命令将处于pending deletion状态，您将看到 HTTP 为 202 statusCode。该命令将在最长 24 小时超时后自动从您的账户中删除。