本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 用於收集和處理資料的狀態範本操作 **重要** 對特定 AWS IoT FleetWise 功能的存取目前受到鎖定。如需詳細資訊，請參閱[AWS AWS IoT FleetWise 中的區域和功能可用性](fleetwise-regions.md)。 下列各節說明如何使用狀態範本來啟用和停用資料收集、執行擷取操作，以及處理您車輛的狀態資料。 **Topics** + [使用狀態範本啟用和停用狀態資料收集](start-stop-data-ingestion.md) + [使用狀態範本擷取車輛狀態快照](on-demand-operations.md) + [使用 MQTT 訊息處理上次已知狀態車輛資料](process-last-known-state-vehicle-data.md) # 使用狀態範本啟用和停用狀態資料收集 **重要** 對特定 AWS IoT FleetWise 功能的存取目前受到鎖定。如需詳細資訊，請參閱[AWS AWS IoT FleetWise 中的區域和功能可用性](fleetwise-regions.md)。 下列各節說明如何使用 啟用和停用狀態範本的資料擷取 AWS CLI。 **重要** 開始之前，請確定您已建立[狀態範本](state-templates.md)，並將其及其更新策略與車輛建立關聯。 您必須啟用狀態範本， Edge Agent 才能將訊號更新傳送至雲端。 若要使用狀態範本執行這些操作，請先建立命令資源，然後在車輛上啟動命令執行。下一節說明如何使用此 API，以及如何啟用和停用資料擷取。 **Topics** + [使用 `CreateCommand` API](#start-stop-ingestion-create-command) + [範例：啟用狀態範本](#start-stop-ingestion-activate-template) + [範例：停用狀態範本](#start-stop-ingestion-deactivate-template) ## 使用 `CreateCommand` API 在「`AWS-IoTFleetwise`」命名空間中建立命令資源，並在為狀態範本建立或傳送命令資源時使用下列參數： + `$stateTemplate.name` – 要在其中執行操作的狀態範本名稱。狀態範本必須套用至車輛，您才能執行 操作。如需詳細資訊，請參閱[將 an AWS IoT FleetWise 狀態範本與 車輛建立關聯](state-templates.md#apply-state-templates)。 + `$stateTemplate.operation` – 要在狀態範本上執行的操作。針對此參數使用下列其中一個值： + `activate` – 當您將狀態範本套用至車輛時，Edge Agent 會根據`stateTemplateUpdateStrategy`您指定的 （變更中或定期） 開始傳送訊號更新至雲端。如需詳細資訊，請參閱[將 an AWS IoT FleetWise 狀態範本與 車輛建立關聯](state-templates.md#apply-state-templates)。 此外，您可以定義自動狀態範本停用時間，在指定的期間之後停止更新。如果未提供自動停用時間，狀態範本會持續傳送更新，直到發出停用呼叫為止。 一旦收到`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. **建立命令資源** 您必須先建立命令資源，才能將命令傳送至車輛。當您將命令傳送至車輛時，您可以指定強制參數的替代值。如需詳細資訊，請參閱[建立命令資源](create-manage-remote-command-cli.md#create-remote-command-cli)。 **重要** `$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"} } ]' ``` 1. **在車輛上啟動命令執行** 建立命令後，將命令傳送至車輛。如果您在建立命令資源時未指定必要參數的值，您現在必須指定這些參數。如需詳細資訊，請參閱[傳送命令 (AWS CLI)](send-monitor-remote-command-cli.md#send-remote-command-cli)。 **重要** 請確定您使用帳戶特定的 AWS IoT 任務資料平面 API 端點進行 API 操作。 ``` aws iot-jobs-data start-command-execution \ --endpoint-url \ --command-arn arn:aws:iot:region:111122223333:command/ActivateStateTemplate \ --target-arn arn:aws:iot:region:111122223333:thing/ ``` 1. **擷取狀態範本操作的狀態** 啟動命令執行後，您可以使用 `GetCommandExecution` API 來擷取狀態範本。 ``` aws iot get-command-execution --execution-id ``` ## 範例：停用狀態範本 若要停用狀態範本，請先建立命令資源。然後，您可以將下列命令傳送至您要停用狀態範本的車輛。此範例示範如何在建立命令時指定參數的預設值。啟動命令執行時，會使用這些參數及其值來停用狀態範本。 1. **建立命令資源** 您必須先建立命令資源，才能將命令傳送至車輛。當您將命令傳送至車輛時，您可以指定強制參數的替代值。如需詳細資訊，請參閱[建立命令資源](create-manage-remote-command-cli.md#create-remote-command-cli)。 ``` 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"} } ]' ``` 1. **在車輛上啟動命令執行** 建立命令後，將命令傳送至車輛。如果您在建立命令資源時未指定必要參數的值，您現在必須指定這些參數。如需詳細資訊，請參閱[傳送命令 (AWS CLI)](send-monitor-remote-command-cli.md#send-remote-command-cli)。 ``` aws iot-jobs-data start-command-execution \ --endpoint-url \ --command-arn arn:aws:iot:region:111122223333:command/DeactivateStateTemplate \ --target-arn arn:aws:iot:region:111122223333:thing/ ``` 1. **擷取狀態範本操作的狀態** 啟動命令執行後，您可以使用 `GetCommandExecution` API 來擷取狀態範本。 ``` aws iot get-command-execution --execution-id ``` # 使用狀態範本擷取車輛狀態快照 **重要** 對特定 AWS IoT FleetWise 功能的存取目前受到鎖定。如需詳細資訊，請參閱[AWS AWS IoT FleetWise 中的區域和功能可用性](fleetwise-regions.md)。 您可以使用[https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html) AWS IoT Core 控制平面 API 操作或 AWS IoT FleetWise 主控台擷取車輛的上次已知狀態。 **重要** 驗證例外狀況可能發生在下列任一情況下： 提供的狀態範本並非`ASSOCIATED`搭配 車輛使用。 提出啟用狀態範本的請求，但尚未`DEPLOYED`在車輛上。 系統會向狀態範本提出請求，但正在`DELETED`車輛上。 ## 擷取車輛狀態快照 （主控台） 您可以使用 AWS IoT FleetWise 主控台來擷取車輛的上次已知狀態。 AWS IoT FleetWise 會為您建立命令來擷取資料。 **擷取車輛狀態** 1. 開啟 [AWS IoT FleetWise 主控台](https://console.aws.amazon.com/iotfleetwise)。 1. 在導覽窗格中，選擇 **車輛**。 1. 從清單中選擇車輛以開啟其詳細資訊頁面。 1. 在**狀態範本**索引標籤上，選擇**擷取資料**。 1. 選取授予 AWS IoT FleetWise 許可的 IAM 角色，以傳送命令並擷取資料。請參閱[控制存取](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/controlling-access.html#generate-command-payload)。 1. 選擇**擷取狀態**。 ## 擷取車輛狀態快照 (AWS CLI) 若要擷取狀態快照，請先建立命令資源。然後，您可以將下列命令傳送至您要為其擷取狀態快照的車輛。如需使用 `CreateCommand` API 及其參數的詳細資訊，請參閱 [使用 `CreateCommand` API](start-stop-data-ingestion.md#start-stop-ingestion-create-command)。 1. **建立命令資源** 下列範例示範如何建立命令資源來執行擷取操作。當您將命令傳送至車輛時，您可以指定強制參數的替代值。如需詳細資訊，請參閱[建立命令資源](create-manage-remote-command-cli.md#create-remote-command-cli)。 ``` aws iot create-command \ --command-id \ --display-name "FetchSnapshot State Template" \ --namespace AWS-IoTFleetWise \ --mandatory-parameters '[ { "name": "$stateTemplate.name", "defaultValue": {"S": "ST123"} }, { "name": "$stateTemplate.operation", "defaultValue": {"S": "fetchSnapshot"} } ]' ``` 回應： ``` { "commandId": "", "commandArn": "arn:aws:iot::111122223333:command/" } ``` 1. **開始命令執行以擷取狀態快照** 建立命令後，將命令傳送至車輛。如果您在建立命令資源時未指定必要參數的值，您現在必須指定這些參數。如需詳細資訊，請參閱[傳送命令 (AWS CLI)](send-monitor-remote-command-cli.md#send-remote-command-cli)。 ``` aws iot-jobs-data start-command-execution \ --command-arn arn:aws:iot:region:111122223333:command/ \ --target-arn arn:aws:iot:region:111122223333:thing/ ``` 回應： ``` { "executionId": "" } ``` 1. 擷取狀態範本操作的狀態 啟動命令執行後，您可以使用 `GetCommandExecution` API 來擷取狀態範本。 ``` aws iot get-command-execution --execution-id ``` # 使用 MQTT 訊息處理上次已知狀態車輛資料 **重要** 對特定 AWS IoT FleetWise 功能的存取目前受到鎖定。如需詳細資訊，請參閱[AWS AWS IoT FleetWise 中的區域和功能可用性](fleetwise-regions.md)。 若要從您的車輛接收更新並處理其資料，請訂閱下列 MQTT 主題。如需詳細資訊，請參閱《 開發人員指南》中的 [MQTT 主題](https://docs.aws.amazon.com/iot/latest/developerguide/iot-connect-devices.html)。 *AWS IoT Core * ``` $aws/iotfleetwise/vehicles/$vehicle_name/last_known_state/$state_template_name/data ``` 上一個已知狀態訊號更新訊息可能未依順序接收，因為 MQTT 不保證排序。使用 MQTT 接收和處理車輛資料的任何用戶端都必須處理此問題。上次已知狀態訊號更新訊息遵循 MQTT 5 訊息通訊協定。 每個 MQTT 訊息的訊息標頭具有下列使用者屬性： + **vehicleName** – [車輛](vehicles.md)的唯一識別符。 + **stateTemplateName** – 上次已知[狀態範本](state-templates.md)的唯一識別符。 此外，您可以在更新或建立狀態範本時指定`metadataExtraDimensions`請求參數，以指定要包含在 MQTT 訊息標頭中的[車輛屬性](signal-catalogs.md)。（請參閱[狀態範本](state-templates.md)。) MQTT 訊息標頭中的使用者屬性有助於將訊息路由到不同的目的地，而無需檢查承載。 MQTT 訊息承載包含從車輛收集的資料。您可以在建立或更新狀態範本時指定`extraDimensions`請求參數，以指定要包含在 MQTT 訊息承載中的車輛屬性 （請參閱 [建立 an AWS IoT FleetWise 狀態範本](state-templates.md))。額外維度會透過將額外維度與車輛建立關聯，來豐富從車輛收集的資料。 MQTT 訊息承載是通訊協定緩衝區 (Protobuf) 編碼，MQTT 訊息標頭包含定義為 application/octet-stream 的內容類型指標。Protobuf 編碼結構描述如下所示： ``` // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 syntax = "proto3"; option java_package = "com.amazonaws.iot.autobahn.schemas.lastknownstate"; package Aws.IoTFleetWise.Schemas.CustomerMessage; message LastKnownState { /* * The absolute timestamp in milliseconds since Unix Epoch of when the event was triggered in vehicle. */ uint64 time_ms = 1; /* * This field is deprecated, use signals instead */ repeated Signal signal = 2 [ deprecated = true ]; repeated Signal signals = 3; repeated ExtraDimension extra_dimensions = 4; } message Signal { /* * The Fully Qualified Name of the signal is the path to the signal plus the signal's name. * For example, Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringState * The fully qualified name can have up to 150 characters. Valid characters: a-z, A-Z, 0-9, : (colon), and _ (underscore). */ string name = 1; /* * The FWE reported signal value can be one of the following data types. */ oneof SignalValue { double double_value = 2; bool boolean_value = 3; sint32 int8_value = 4; uint32 uint8_value = 5; sint32 int16_value = 6; uint32 uint16_value = 7; sint32 int32_value = 8; uint32 uint32_value = 9; sint64 int64_value = 10; uint64 uint64_value = 11; float float_value = 12; /* * An UTF-8 encoded or 7-bit ASCII string */ string string_value = 13; } } message ExtraDimension { /* * The Fully Qualified Name of the attribute is the path to the attribute plus the attribute's name. * For example, Vehicle.Model.Color * The fully qualified name can have up to 150 characters. Valid characters: a-z, A-Z, 0-9, : (colon), and _ (underscore). */ string name = 1; oneof ExtraDimensionValue { /* * An UTF-8 encoded or 7-bit ASCII string */ string string_value = 2; } } ``` 其中： + `time_ms`: 在車輛中觸發事件時的絕對時間戳記 （自 Unix Epoch 起以毫秒為單位）。Edge Agent 軟體會針對此時間戳記，在車輛的時鐘上使用 。 + `signal`: `Signal`包含訊號資訊的 陣列： `name`（字串） `signalValue` 和 支援下列資料類型 - `double`、`bool`、`int8`、`uint8`、`int16`、`uint16`、`int32``uint32``int64`、、`uint64`、`float`、、`string`、。 + `extra_dimensions`: `ExtraDimensions` 包含車輛屬性資訊的 陣列： `name`（字串）`extraDimensionValue`，目前僅支援 `string`資料類型。