使用狀態範本啟用和停用狀態資料收集 - AWS IoT FleetWise
使用 CreateCommand API範例：啟用狀態範本範例：停用狀態範本

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

使用狀態範本啟用和停用狀態資料收集

重要

存取特定 AWS IoT FleetWise 功能目前已封鎖。如需詳細資訊，請參閱AWSAWS IoT FleetWise 中的區域和功能可用性。

下列各節說明如何使用 啟用和停用狀態範本的資料擷取 AWS CLI。

重要

開始之前，請確定您已建立狀態範本，並將其及其更新策略與車輛建立關聯。

您必須啟用狀態範本， Edge Agent 才能將訊號更新傳送至雲端。

若要使用狀態範本執行這些操作，請先建立命令資源，然後在車輛上啟動命令執行。下一節說明如何使用此 API，以及如何啟用和停用資料擷取。

使用 CreateCommand API

在「AWS-IoTFleetwise」命名空間中建立命令資源，並在為狀態範本建立或傳送命令資源時使用下列參數：

  • $stateTemplate.name – 要在其中執行操作的狀態範本名稱。狀態範本必須套用至車輛，您才能執行 操作。如需詳細資訊，請參閱將 an AWS IoT FleetWise 狀態範本與 車輛建立關聯。

  • $stateTemplate.operation – 要在狀態範本上執行的操作。針對此參數使用下列其中一個值：

    • activate – 當您將狀態範本套用至車輛時，Edge Agent 會根據stateTemplateUpdateStrategy您指定的 （變更中或定期） 開始傳送訊號更新至雲端。如需詳細資訊，請參閱將 an AWS IoT FleetWise 狀態範本與 車輛建立關聯。

      此外，您可以定義自動狀態範本停用時間，在指定的期間之後停止更新。如果未提供自動停用時間，狀態範本會持續傳送更新，直到發出停用呼叫為止。

      一旦收到activate命令，裝置應根據更新策略傳送狀態範本中指定的訊號。 AWS IoT FleetWise 建議裝置收到啟用命令時，其傳送的第一個訊息應包含狀態範本中所有訊號的快照。後續的訊息應根據更新策略傳送。

    • deactivate – Edge Agent 會停止傳送訊號更新至雲端。

    • fetchSnapshot – Edge Agent 會傳送狀態範本中定義的訊號的一次性快照stateTemplateUpdateStrategy，無論您在將狀態範本套用至車輛時指定的 為何。

  • （選用） $stateTemplate.deactivateAfterSeconds – 狀態範本會在指定的時間之後自動停用。此參數只能在 $stateTemplate.operation 參數的值為「啟用」時使用。如果未指定此參數，或者此參數的值為 0，則 Edge Agent 會持續傳送訊號更新至雲端，直到狀態範本收到「停用」操作為止。狀態範本永遠不會自動停用。

    最小值：0，最大值：4294967295。

注意

  • API 會傳回成功，以回應已處於作用中狀態之範本的啟用請求。

  • API 會傳回成功，以回應已處於停用狀態之範本的停用請求。

  • 您在狀態範本上提出的最新請求是生效的請求。例如，如果您在一小時內提出停用狀態範本的請求，然後在四小時內提出第二個停用相同範本的請求，四小時停用就會生效，因為它是最新的請求。

重要

驗證例外狀況可能發生在下列任一情況下：

  • 提供的狀態範本並非ASSOCIATED搭配 車輛使用。

  • 發出啟用狀態範本的請求，但尚未DEPLOYED在車輛上。

  • 向狀態範本提出請求，但正在DELETED車輛上。

範例：啟用狀態範本

若要啟用狀態範本，請先建立命令資源。然後，您可以將下列命令傳送至您要啟用狀態範本的車輛。此範例示範如何在建立命令時指定參數的預設值。啟動命令執行時，會使用這些參數及其值來啟用狀態範本。

  1. 建立命令資源

    您必須先建立命令資源，才能將命令傳送至車輛。當您將命令傳送至車輛時，您可以指定強制參數的替代值。如需詳細資訊，請參閱建立命令資源。

    重要

    $stateTemplate.name 和 $stateTemplate.operation 參數必須以字串資料類型提供。如果提供任何其他資料類型，或者如果缺少這兩個參數中的任何一個，則命令執行會失敗，並出現驗證例外狀況。$stateTemplate.deactivateAfterSeconds 參數必須以Long資料類型提供。

    aws iot create-command \
    --description "This command activates a state template on a vehicle"
    --command-id ActivateStateTemplate \
    --display-name "Activate State Template" \
    --namespace AWS-IoTFleetWise \
    --mandatory-parameters '[
    {
        "name": "$stateTemplate.name",
        "defaultValue": {"S": "ST123"}
    },
    {
        "name": "$stateTemplate.operation",
        "defaultValue": {"S": "activate"}
    },
    {
        "name": "$stateTemplate.deactivateAfterSeconds",
        "defaultValue": {"L": "120"}
    } 
]'
  2. 在車輛上啟動命令執行

    建立命令後，將命令傳送至車輛。如果您在建立命令資源時未指定必要參數的值，您現在必須指定這些參數。如需詳細資訊，請參閱傳送命令 (AWS CLI)。

    重要

    請確定您使用帳戶特定的 AWS IoT 任務資料平面 API 端點進行 API 操作。

    aws iot-jobs-data start-command-execution \
    --endpoint-url <endpoint-url> \
    --command-arn arn:aws:iot:region:111122223333:command/ActivateStateTemplate \
    --target-arn arn:aws:iot:region:111122223333:thing/<VEHICLE_NAME>
  3. 擷取狀態範本操作的狀態

    啟動命令執行後，您可以使用 GetCommandExecution API 來擷取狀態範本。

    aws iot get-command-execution --execution-id <EXECUTION_ID>

範例：停用狀態範本

若要停用狀態範本，請先建立命令資源。然後，您可以將下列命令傳送至您要停用狀態範本的車輛。此範例示範如何在建立命令時指定參數的預設值。啟動命令執行時，會使用這些參數及其值來停用狀態範本。

  1. 建立命令資源

    您必須先建立命令資源，才能將命令傳送至車輛。當您將命令傳送至車輛時，您可以指定強制參數的替代值。如需詳細資訊，請參閱建立命令資源。

    aws iot create-command \
    --description "This command deactivates a state template on a vehicle"
    --command-id DeactivateStateTemplate \
    --display-name "Deactivate State Template" \
    --namespace AWS-IoTFleetWise \
    --mandatory-parameters '[
    {
        "name": "$stateTemplate.name",
        "defaultValue": {"S": "ST123"}
    },
    {
        "name": "$stateTemplate.operation",
        "defaultValue": {"S": "deactivate"}
    }    
]'
  2. 在車輛上啟動命令執行

    建立命令後，將命令傳送至車輛。如果您在建立命令資源時未指定必要參數的值，您現在必須指定這些參數。如需詳細資訊，請參閱傳送命令 (AWS CLI)。

    aws iot-jobs-data start-command-execution \
    --endpoint-url <endpoint-url> \
    --command-arn arn:aws:iot:region:111122223333:command/DeactivateStateTemplate \
    --target-arn arn:aws:iot:region:111122223333:thing/<VEHICLE_NAME>
  3. 擷取狀態範本操作的狀態

    啟動命令執行後，您可以使用 GetCommandExecution API 來擷取狀態範本。

    aws iot get-command-execution  --execution-id <EXECUTION_ID>