本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 命令使用案例
<a name="remote-command-use-cases"></a>

**重要**  
對特定 AWS IoT FleetWise 功能的存取目前受到鎖定。如需詳細資訊，請參閱[AWS AWS IoT 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)

## 建立不含參數的命令
<a name="remote-command-use-case1"></a>

下列使用案例顯示如何使用 `CreateCommand` API 或 `create-command` CLI 來建立不含參數的命令。當您建立命令時，只需要提供命令 ID 和角色 ARN。

此使用案例在經常性使用案例中特別有用，例如當您想要多次將相同的命令傳送到車輛時。在此情況下，命令不會繫結至特定傳動器，並可讓您彈性地在任何傳動器上執行命令。使用 `StartCommandExecution` API 或 `start-command-execution`CLI 執行命令時，您必須在執行時間指定參數，其中包含致動器和實體訊號值。

### 建立不含`mandatory-parameters`輸入的命令
<a name="remote-command-use-case1-create"></a>

此使用案例示範如何在沒有任何必要參數輸入的情況下建立命令。

```
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`輸入的情況下建立的命令
<a name="remote-command-use-case1-start"></a>

在此第一個範例中，上述建立的 命令可讓您在任何作動器上執行命令，而不受限制。若要`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"}
    }'
```

## 建立具有參數預設值的命令
<a name="remote-command-use-case2"></a>

此命令只允許您在指定的作動器上執行命令。提供預設值有助於防止您傳送不正確的命令。例如，可以使用預設值來設定鎖定和解鎖門的`LockDoor`命令，以避免命令意外解鎖門。

當您想要多次傳送相同的命令，並在相同的作動器上執行不同的動作時，例如鎖定和解鎖車輛的門時，此使用案例特別有用。如果您想要將致動器設定為預設值，則不需要將 qny 傳遞`parameters`給 `start-command-execution` CLI。如果您在 CLI `start-command-execution` `parameters`中為 指定不同的值，則會覆寫預設值。

### 使用 的預設值建立命令 `mandatory-parameters`
<a name="remote-command-use-case2-create"></a>

下列命令顯示如何為 致動器 1 提供預設值。

```
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`
<a name="remote-command-use-case2-start"></a>

命令`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
```

您也可以在執行時間期間，為相同的作動器 - 作動器 1 傳遞不同的值，這會覆寫預設值。

```
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"}
    }'
```

## 使用參數值建立命令
<a name="remote-command-use-case3"></a>

此命令只允許您在指定的作動器上執行命令。它也會強制您在執行時間期間設定致動器的值。

當您希望最終使用者在車輛上執行某些動作器時，此使用案例特別有用。

**注意**  
您可以有超過 個`mandatory-parameters`輸入的名稱值對，其中有部分或全部的預設值。然後，在執行時間，您可以判斷要在啟動器上執行時使用的參數，前提是啟動器名稱使用完整名稱與`$actuatorPath.`字首。

### 建立不含預設值的 命令 `mandatory-parameters`
<a name="remote-command-use-case3-create"></a>

此命令只允許您在指定的作動器上執行命令。它也會強制您在執行時間期間設定致動器的值。

```
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`
<a name="remote-command-use-case3-start"></a>

執行 命令時，在此情況下，您必須指定 致動器 1 的值。以下顯示的命令執行會成功將 的值設定為 `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"}
    }'
```

## 搭配狀態範本使用命令
<a name="remote-command-use-cases-templates"></a>

您也可以使用命令 API 操作進行狀態資料收集和處理。例如，您可以擷取一次性狀態快照，或啟用或停用狀態範本，以開始或停止收集車輛狀態資料。下列範例示範如何搭配狀態範本使用命令功能。如需詳細資訊，請參閱[用於收集和處理資料的狀態範本操作](state-template-api-operations.md)

**注意**  
指定為`mandatory-parameters`輸入一部分的名稱欄位必須使用 `$stateTemplate`字首。

### 範例 1：使用預設值為狀態範本建立命令
<a name="remote-command-use-cases-template-ex1"></a>

此範例說明如何使用 `create-command` CLI 來啟用狀態範本。

```
aws iot create-command \
    --command-id <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/<COMMAND_ID> \
    --target-arn arn:aws:iot:region:111122223333:thing/<VEHICLE_NAME> \
    --parameters '{
       "$stateTemplate.name": {"S": "ST345"}
    }'
```

### 範例 2：為沒有預設值的狀態範本建立命令
<a name="remote-command-use-cases-template-ex2"></a>

下列命令會建立多個狀態範本，而沒有任何參數的預設值。它會強制您使用這些參數及其值來執行命令。

```
aws iot create-command \
    --command-id <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/<COMMAND_ID> \
    --target-arn arn:aws:iot:region:111122223333:thing/<VEHICLE_NAME> \
    --parameters '{
        "$stateTemplate.name": {"S": "ST345"},
        "$stateTemplate.operation": {"S": "activate"},
        "$stateTemplate.deactivateAfterSeconds" : {"L": "120"}
```