本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
命令概念和狀態
使用 AWS IoT 命令,將指示從雲端傳送至已連線的裝置 AWS IoT。若要使用命令功能:
-
首先,建立具有承載的命令資源,其中包含在裝置上執行命令所需的組態。
-
指定將接收承載的目標裝置,並執行指定的動作。
-
在目標裝置上執行 命令,並從裝置擷取狀態資訊。若要疑難排解任何問題,請參閱 CloudWatch 日誌。
如需有關此工作流程的詳細資訊,請參閱 高階命令工作流程。
命令關鍵概念
以下顯示使用 命令功能的一些關鍵概念。
- 命令
-
命令是從雲端傳送至 IoT 裝置的指示。這些指示 (命令承載) 會以MQTT訊息的形式傳送至裝置。在裝置收到命令承載之後,他們可以處理採取對應動作的指示。這類動作的範例包括修改裝置組態設定、傳輸感應器讀數或上傳日誌。裝置接著可以執行 命令,並將結果傳回至雲端。這可讓您遠端監控和控制連線的裝置。
- 命名空間
-
使用命令功能時,您可以指定命令的命名空間。當您想要在 中建立命令時 AWS IoT Device Management,您必須使用預設
AWS-IoT
命名空間。當您使用此命名空間時,您必須在建立命令時提供承載。當您在目標裝置上執行 命令時,將使用承載。如果您想要 AWS IoT FleetWise 改為為 建立命令,則必須改用AWS-IoT-FleetWise
命名空間。如需詳細資訊,請參閱《 命令開發人員指南》中的遠端AWS IoT FleetWise 命令。 - 承載
-
建立 命令時,您必須提供定義裝置必須執行之動作的承載。承載可以使用您選擇的任何格式。為了確保裝置可以正確讀取並了解您要傳送的資訊,建議您在 命令中指定承載格式類型。如果您的裝置使用 MQTT5,他們可以遵循 MQTT標準來識別承載格式。JSON 或 的格式指標CBOR將在命令請求主題中提供。
- 目標裝置
-
當您想要執行命令時,您必須指定將接收命令並執行動作的目標裝置。如果您的裝置已向 註冊為物件 AWS IoT,您可以使用物件名稱。如果您的裝置尚未註冊,您可以改為使用MQTT用戶端 ID。用戶端 ID 是MQTT通訊協定中定義的裝置或用戶端的唯一識別符。其可用於將您的裝置連接到 AWS IoT。
- 命令執行
-
命令執行是在目標裝置上執行的命令執行個體。當您開始執行時,命令 (承載) 會交付至目標裝置。現在會為目標產生唯一的命令執行 ID。然後,裝置可以執行命令並將其進度報告給 AWS IoT。裝置端邏輯決定如何執行命令,以及如何將狀態發佈到預留主題。
- 命令主題
-
在您執行命令之前,您的裝置必須已訂閱命令請求主題。當您將請求傳送至雲端以執行命令時,承載將傳送至命令請求主題上的裝置。裝置執行命令後,可以將執行的結果和狀態發佈至命令回應主題。如需詳細資訊,請參閱命令主題。
命令狀態
您在 中建立的命令 AWS 帳戶 可以是可用、已棄用或待定刪除狀態。
- 可用性
-
成功建立命令資源後,該資源將處於可用狀態。命令現在可用於將命令執行傳送至裝置。
- 已棄用
-
如果您不想再使用命令,可以將其標記為已棄用。在此狀態下,您無法將命令的任何新執行傳送至您的裝置。任何已啟動的待定執行都會繼續在裝置上執行,直到完成為止。若要傳送新的執行,您必須還原命令,使其變成可用。
- 待刪除
-
當您將命令標記為刪除時,如果命令已棄用超過最大逾時的持續時間,則命令將自動刪除。此動作為永久性且無法復原。根據預設,逾時持續時間上限為 12 小時。如果命令未取代,或已取代超過最大逾時的持續時間,則命令將處於待定刪除狀態。在逾時持續時間上限之後, 命令將自動從您的帳戶中移除。
命令執行狀態
當您在目標裝置上啟動命令執行時,命令執行會進入 CREATED
狀態。然後,它可以轉換到任何其他命令執行狀態,具體取決於裝置報告的狀態。然後,您可以擷取狀態資訊並追蹤命令執行。
注意
對於指定的目標裝置,您可以同時執行多個命令。您可以使用並行控制功能來限制傳送至相同裝置的執行數量上限,以防止裝置超載。如需您可以為每個裝置執行並行執行數目上限的相關資訊,請參閱AWS IoT Device Management 命令配額。
下表顯示命令執行的不同狀態,以及命令執行如何根據執行進度在各種狀態之間轉換。
命令執行狀態 | 由裝置/雲端啟動? | 終端機執行? | 允許的狀態轉換 |
---|---|---|---|
CREATED |
雲端 | 否 |
|
IN_PROGRESS |
裝置 | 否 |
|
TIMED_OUT |
裝置和雲端 | 否 |
|
SUCCEEDED |
裝置 | 是 | 不適用 |
FAILED |
裝置 | 是 | 不適用 |
REJECTED |
裝置 | 是 | 不適用 |
當您的裝置執行 命令時,可以使用命令預留MQTT主題,隨時將狀態和結果的更新發佈至雲端。若要將每個命令執行狀態的其他內容提供給雲端,可以使用 statusReason
物件中包含reasonDescription
的 reasonCode
和 。
下圖顯示各種命令執行狀態,以及它們之間的轉換方式。
下一節說明終端機和非終端機命令執行、各種執行狀態及其運作方式。
非終端機命令執行
如果執行可以接受來自裝置或用戶端的更新,您的命令執行即為非終端機。處於非終端機狀態的執行會被視為作用中。下列狀態為非終端機狀態。
-
CREATED
當您從 AWS IoT 主控台啟動命令執行時,或使用
StartCommandExecution
API ,使用命令請求主題將命令傳送至您的裝置。如果請求成功,命令執行狀態會變更為CREATED
。從此狀態,命令執行可以轉換到任何其他非終端機或終端機狀態。 -
IN_PROGRESS
收到命令承載後,您的裝置可以開始執行承載中的說明,並執行指定的動作。執行命令時,裝置可以將回應發佈至命令回應主題,並將命令執行狀態更新為
IN_PROGRESS
。從IN_PROGRESS
狀態,命令執行可以轉換到 以外的任何其他終端機或非終端機狀態CREATED
。注意
UpdateCommandExecution
API 可以多次叫用,狀態為IN_PROGRESS
。您可以使用statusReason
物件指定有關執行的其他詳細資訊。 -
TIMED_OUT
此命令執行狀態可由雲端和裝置觸發。由於下列原因,
CREATED
或IN_PROGRESS
狀態中的執行可能會變更為TIMED_OUT
狀態。-
命令傳送至裝置後,計時器便會啟動。如果裝置在指定的持續時間內沒有回應,雲端會將命令執行狀態變更為
TIMED_OUT
。在此情況下,命令執行是非終端機。 -
裝置可以將狀態覆寫為任何其他終端狀態,或回報執行命令時發生逾時,並將狀態設定為
TIMED_OUT
。在此情況下,執行狀態會保持在 ,TIMED_OUT
但StatusReason
物件的欄位會根據裝置報告的資訊而變更。命令執行現在會變成終端機。
如需詳細資訊,請參閱逾時值和TIMED_OUT執行狀態。
-
終端機命令執行
如果執行不再接受來自裝置的任何其他更新,則命令執行會變成終端機。下列狀態為終端機。執行可以從任何非終端機狀態 、 CREATED
IN_PROGRESS
或 轉換至終端機狀態TIMED_OUT
。
-
SUCCEEDED
如果裝置成功完成執行命令,則可以發佈回應至命令回應主題,並將命令執行狀態更新為
SUCCEEDED
。 -
FAILED
當您的裝置無法完成執行命令時,可以發佈對命令回應主題的回應,並將命令執行狀態更新為
FAILED
。您可以使用statusReason
物件的reasonCode
和reasonDescription
欄位或 CloudWatch 日誌,進一步對失敗進行故障診斷。 -
REJECTED
當您的裝置收到無效或不相容的請求時,裝置可以叫用狀態
UpdateCommandExecution
API為 的REJECTED
。您可以使用statusReason
物件的reasonCode
和reasonDescription
欄位或 CloudWatch 日誌,進一步疑難排解任何問題。