本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 命令使用场景 **重要** 目前对某些 AWS 物联网 FleetWise 功能的访问受到限制。有关更多信息，请参阅 [AWS AWS 物联网中的区域和功能可用性 FleetWise](fleetwise-regions.md)。 使用命令功能时，可以在以下情况下创建和运行命令： + 在创建过程中，您可以省略参数并仅指定命令 ID。在这种情况下，您需要指定在目标设备上运行命令时要使用的参数。 + 您可以指定一个或多个参数，并在创建命令时为其配置默认值。提供默认值将有助于防止您发送不准确的命令。 + 您可以指定一个或多个参数，并在创建命令时为其配置值。可以提供多个参数，但只能执行其中一个，并且此参数的`Name`字段必须使用前`$actuatorPath`缀。 本节提供了`CreateCommand`和 `StartCommandExecution` API 的一些使用场景以及参数的使用。它还向您展示了在状态模板中使用命令的一些示例。 **Topics** + [创建不带参数的命令](#remote-command-use-case1) + [使用参数的默认值创建命令](#remote-command-use-case2) + [使用参数值创建命令](#remote-command-use-case3) + [使用带有状态模板的命令](#remote-command-use-cases-templates) ## 创建不带参数的命令 以下用例展示了如何使用 `CreateCommand` API 或 `create-command` CLI 创建不带参数的命令。创建命令时，您只需要提供命令 ID 和角色 ARN。 此用例在反复出现的用例中特别有用，例如当你想多次向车辆发送相同的命令时。在这种情况下，该命令与特定的执行器无关，因此您可以灵活地在任何执行器上执行命令。使用 `StartCommandExecution` API 或 `start-command-execution` CLI 执行命令时，必须改为在运行时指定参数，包括执行器和物理信号值。 ### 在没有`mandatory-parameters`输入的情况下创建命令 此用例展示了如何在不输入任何必填参数的情况下创建命令。 ``` aws iot create-command \ --command-id "UserJourney1" \ --role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \ --description "UserJourney1 - No mandatory parameters" \ --namespace "AWS-IoT-FleetWise" ``` ### 运行在没有`mandatory-parameters`输入的情况下创建的命令 在第一个示例中，上面创建的命令允许您在任何执行器上不受限制地执行命令。`actuator1`要将值设置为 10，请运行： ``` aws iot-jobs-data start-command-execution \ --command-arn arn:aws:iot:region:111122223333:command/UserJourney1 \ --target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \ --parameters '{ "$actuatorPath.Vehicle.actuator1": {"S": "10"} }' ``` 同样，您可以运行将值设置`actuator3`为的命令`true`。 ``` aws iot-jobs-data start-command-execution \ --command-arn arn:aws:iot:region:111122223333:command/UserJourney1 \ --target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \ --parameters '{ "$actuatorPath.Vehicle.actuator3": {"S": "true"} }' ``` ## 使用参数的默认值创建命令 此命令仅允许您在指定的执行器上执行命令。提供默认值将有助于防止您发送不准确的命令。例如，可以将锁定和解锁门的`LockDoor`命令配置为默认值，以避免该命令意外解锁门。 当您想要多次发送相同的命令并在同一个执行器上执行不同的操作（例如锁定和解锁车辆的车门）时，此用例特别有用。如果要将执行器设置为默认值，则无需向 `start-command-execution` CLI 传递 qny `parameters`。如果您确实在 `start-command-execution` CLI `parameters` 中为指定了不同的值，则它将覆盖默认值。 ### 使用默认值为创建命令 `mandatory-parameters` 以下命令显示如何为 actuator1 提供默认值。 ``` aws iot create-command \ --command-id "UserJourney2" \ --namespace "AWS-IoT-FleetWise" \ --role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \ --mandatory-parameters '[ { "name": "$actuatorPath.Vehicle.actuator1", "defaultValue": {"S": "0"} } ]' ``` ### 运行使用默认值创建的命令 `mandatory-parameters` 该命令`UserJourney2`允许您执行命令，而无需在运行时传递输入值。在这种情况下，运行时执行将使用创建期间指定的默认值。 ``` aws iot-data start-command-execution \ --command-arn arn:aws:iot:region:111122223333:command/UserJourney3 \ --target-arn arn:aws:iot:region:111122223333:thing/target-vehicle ``` 您还可以在运行时为同一个执行器 actuator1 传递不同的值，这将覆盖默认值。 ``` aws iot-jobs-data start-command-execution \ --command-arn arn:aws:iot:region:111122223333:command/UserJourney3 \ --target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \ --parameters '{ "$actuatorPath.Vehicle.actuator1": {"S": "139"} }' ``` ## 使用参数值创建命令 此命令仅允许您在指定的执行器上执行命令。它还会强制您在运行时为执行器设置一个值。 当您希望最终用户在车辆上运行某些执行器时，仅对某些执行器执行某些指定操作时，此用例特别有用。 **注意** 您可以为`mandatory-parameters`输入设置多个名称/值对，其中部分或全部为默认值。然后，在运行时，您可以确定在执行器上运行时要使用的参数，前提是执行器名称使用带`$actuatorPath.`前缀的完全限定名称。 ### 正在创建不带默认值的命令 `mandatory-parameters` 此命令仅允许您在指定的执行器上执行命令。它还会强制您在运行时为执行器设置一个值。 ``` aws iot create-command \ --command-id "UserJourney2" \ --namespace "AWS-IoT-FleetWise" \ --role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \ --mandatory-parameters '[ { "name": "$actuatorPath.Vehicle.actuator1" } ]' ``` ### 运行在没有默认值的情况下创建的命令 `mandatory-parameters` 在这种情况下，在运行命令时，必须为 actuator1 指定一个值。如下所示的命令执行将成功地将的值设置`actuator1`为`10`。 ``` aws iot-data start-command-execution \ --command-arn arn:aws:iot:region:111122223333:command/UserJourney2 \ --target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \ --parameters '{ "$actuatorPath.Vehicle.actuator1": {"S": "10"} }' ``` ## 使用带有状态模板的命令 您还可以使用命令 API 操作来收集和处理状态数据。例如，您可以获取一次性状态快照，或者激活或停用状态模板以开始或停止收集车辆状态数据。以下示例展示了如何将命令功能与状态模板一起使用。有关更多信息，请参阅 [用于数据收集和处理的状态模板操作](state-template-api-operations.md)。 **注意** 作为`mandatory-parameters`输入一部分指定的 “名称” 字段必须使用前`$stateTemplate`缀。 ### 示例 1：使用默认值为状态模板创建命令 此示例说明如何使用 `create-command` CLI 激活状态模板。 ``` aws iot create-command \ --command-id \ --display-name "Activate State Template" \ --namespace AWS-IoT-FleetWise \ --mandatory-parameters '[ { "name": "$stateTemplate.name" }, { "name": "$stateTemplate.operation", "defaultValue": {"S": "activate"} } ]' ``` 同样，以下命令显示了如何将 `start-command-execution` CLI 用于状态模板的示例。 ``` aws iot-data start-command-execution \ --command-arn arn:aws:iot:region:111122223333:command/ \ --target-arn arn:aws:iot:region:111122223333:thing/ \ --parameters '{ "$stateTemplate.name": {"S": "ST345"} }' ``` ### 示例 2：为没有默认值的状态模板创建命令 以下命令创建多个状态模板，其中任何参数都没有默认值。它会强制你使用这些参数及其值来运行命令。 ``` aws iot create-command \ --command-id \ --display-name "Activate State Template" \ --namespace AWS-IoT-FleetWise \ --mandatory-parameters '[ { "name": "$stateTemplate.name", "defaultValue": {"S": "ST123"} }, { "name": "$stateTemplate.operation", "defaultValue": {"S": "activate"} }, { "name": "$stateTemplate.deactivateAfterSeconds", "defaultValue": {"L": "120"} } ]' ``` 以下命令显示了如何使用上述示例的 `start-command-execution` CLI。 ``` aws iot-data start-command-execution \ --command-arn arn:aws:iot:region:111122223333:command/ \ --target-arn arn:aws:iot:region:111122223333:thing/ \ --parameters '{ "$stateTemplate.name": {"S": "ST345"}, "$stateTemplate.operation": {"S": "activate"}, "$stateTemplate.deactivateAfterSeconds" : {"L": "120"} ```