コマンド実行を開始してモニタリングする

コマンドを受信して実行するターゲットデバイスを指定します。登録済みデバイスにはモノの名前、未登録デバイスにはクライアント ID を使用します。ペイロードを受信すると、デバイスは コマンドを実行し、指定されたアクションを実行します。

AWS IoT モノ

ターゲットデバイスは、 AWS IoT レジストリに登録されているモノにすることができます。モノはデバイスの検索と管理を簡素化します。

Connect デバイスページから、または を使用して、デバイスをモノとして登録しますCreateThing。Thing Hub または を使用して既存のモノを検索しますDescribeThing。登録の詳細については、「レジストリでのモノの管理」を参照してください。

クライアント ID

未登録のデバイスの場合は、クライアント ID を使用します。

クライアント ID は、デバイスに割り当てる一意の識別子です。MQTT プロトコルで定義され、英数字、アンダースコア、またはダッシュが含まれます。に接続する各デバイスには、一意のクライアント ID AWS IoT が必要です。

クライアント ID は、デバイスが に接続するときに使用する MQTT クライアント ID です AWS IoT Core。 はこの ID AWS IoT を使用してデバイスを識別し、接続とサブスクリプションを管理します。

タイムアウトは、実行結果を提供するデバイスの期間 (秒単位) を指定します。

実行を作成すると、タイマーが開始されます。デバイスがオフラインになるか、タイムアウト内に結果を報告できない場合、実行はステータス でタイムアウトしますTIMED_OUT。

デフォルト: 10 秒。最大: 12 時間。

タイムアウト値と TIMED_OUT 実行ステータス

クラウドとデバイスの両方がタイムアウトをレポートできます。

コマンドを送信すると、タイマーが開始されます。タイムアウト内にデバイスレスポンスが到着しない場合、クラウドは理由コード TIMED_OUTを使用して実行ステータスを に設定します$NO_RESPONSE_FROM_DEVICE。

これは、次の場合に発生します。

この場合、TIMED_OUT の実行ステータスがクラウドから報告されると、コマンドの実行は非終了の状態です。デバイスは、ステータスをターミナルステータス SUCCEEDED、、FAILEDまたは のいずれかに上書きするレスポンスを発行できますREJECTED。その後、コマンド実行はターミナルになり、それ以降の更新は受け付けません。

デバイスは、コマンドの実行時にタイムアウトが発生したことを報告することで、クラウドによって開始されたTIMED_OUTステータスを更新することもできます。この場合、コマンドの実行ステータスは のままですがTIMED_OUT、statusReasonオブジェクトはデバイスによって報告された情報に基づいて更新されます。その後、コマンド実行はターミナルになり、それ以上の更新は受け入れられません。

MQTT 永続的セッションの使用

AWS IoT Device Management コマンド機能で使用するように MQTT 永続セッションを設定できます。この機能は、デバイスがオフラインになり、タイムアウト時間前にオンラインに戻ったときに、デバイスがコマンドを受信して指定された手順を実行できるようにする場合などに、特に便利です。

デフォルトでは、MQTT 永続セッションの有効期限は 60 分に設定されています。コマンド実行タイムアウトがこの期間を超える値に設定されている場合、60 分以上実行されるコマンド実行はメッセージブローカーによって拒否され、失敗する可能性があります。実行時間が 60 分を超えるコマンドを実行するには、永続セッションの有効期限の延長をリクエストできます。

コンソールからコマンドの実行を開始するには、 AWS IoT コンソールの コマンドハブページに移動し、次の手順を実行します。

StartCommandExecution HTTP データプレーン API オペレーションを使用して、コマンド実行を開始します。API リクエストとレスポンスは、コマンド実行 ID と相関しています。デバイスは、コマンドの実行を完了すると、コマンドレスポンストピックにメッセージを発行することで、ステータスと実行結果をクラウドに報告できます。カスタムレスポンスコードの場合、所有しているアプリケーションコードはレスポンスメッセージを処理して結果を投稿できます AWS IoT。

デバイスがコマンドリクエストトピックをサブスクライブしている場合は、StartCommandExecution API がペイロードメッセージをトピックに発行します。ペイロードには、任意の形式を使用できます。詳細については、「コマンドのペイロード」を参照してください。

$aws/commands/<devices>/<DeviceID>/executions/+/request/<PayloadFormat>

ペイロード形式が JSON または CBOR でない場合、コマンドリクエストトピックの形式を以下に示します。

$aws/commands/<devices>/<DeviceID>/executions/+/request

サンプルの IAM ポリシー

この API オペレーションを使用する前に、デバイスでこのアクションを実行することを IAM ポリシーが許可していることを確認してください。以下に、StartCommandExecution アクションの実行をユーザーに許可する IAM ポリシーの例を示しています。

この例では、次のように置き換えます。

{
  "Effect": "Allow",
  "Action": [
      "iot:StartCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

でサポートされている条件キーのリストを確認するにはStartCommandExecution、IAM ユーザーガイドの「 の条件キー AWS IoT」を参照してください。

アカウント固有のデータプレーンエンドポイントを取得する

API コマンドを実行する前に、エンドポイントのアカウント固有のエンドポイント URL を取得する必要があります。デュアルスタックエンドポイント (IPv4 と IPv6) を使用している場合は、iot:Data-ATS を使用します。iot:Jobs エンドポイントは IPv4 専用です。たとえば、次のコマンドを実行するとします。

aws iot describe-endpoint --endpoint-type iot:Data-ATS

以下のレスポンスの例に示すように、アカウント固有のエンドポイント URL を返します。

{
    "endpointAddress":
    "<account-specific-prefix>-ats.iot.<region>.api.com"
}

コマンド実行を開始する例 (AWS CLI)

次の例は、 コマンドを使用してstart-command-execution AWS CLI コマンドの実行を開始する方法を示しています。

この例では、次のように置き換えます。

このコマンドを実行すると、コマンド実行 ID が返されます。この ID を使用して、コマンド実行ステータス、詳細、およびコマンド実行履歴をクエリすることができます。

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}

この API オペレーションを使用する前に、デバイスがこれらのアクションを実行することを IAM ポリシーで許可していることを確認してください。以下に、デバイスがアクションを実行することを許可するポリシーの例を示しています。UpdateCommandExecution MQTT アクションを実行するアクセス許可をユーザーに付与する追加のサンプル IAM ポリシーについては、「」を参照してください接続および公開ポリシーの例。

この例では、次のように置き換えます。

MQTT クライアント ID の IAM ポリシーの例

次のコードは、MQTT クライアント ID を使用する場合のデバイスポリシーの例を示しています。

IoT のモノの IAM ポリシーの例

次のコードは、 AWS IoT のモノを使用する場合のデバイスポリシーの例を示しています。

コマンド実行がリクエストトピックで受信されると、デバイスはコマンドを処理します。デバイスはその後、UpdateCommandExecution API を使用して、コマンド実行のステータスと結果を次のレスポンストピックに更新します。

$aws/commands/<devices>/<DeviceID>/executions/<ExecutionId>/response/<PayloadFormat>

この例では、<DeviceID> はターゲットデバイスの一意の識別子であり、<execution-id> はターゲットデバイスでのコマンド実行の識別子です。<PayloadFormat> は JSON または CBOR です。

$aws/commands/clients/<ClientID>/executions/<ExecutionId>/response/<PayloadFormat>

実行ステータスに対する更新をデバイスで報告する

デバイスは、API を使用することで、コマンド実行に対する以下のステータス更新を報告できます。これらのステータスの詳細については、「コマンド実行ステータス」を参照してください。

TIMED_OUT ステータスの詳細については、「タイムアウト値と TIMED_OUT 実行ステータス」を参照してください。

UpdateCommandExecution API を使用するときの考慮事項

UpdateCommandExecution API を使用する際の重要な考慮事項を以下に示しています。

UpdateCommandExecution API の例

次のコードは、デバイスが UpdateCommandExecution API を使用して実行ステータスを報告する方法の例を示しています。statusReason フィールドには、ステータスに関する追加情報が提供され、result フィールドには、この例の場合は自動車のバッテリー残量のパーセントなど、実行の結果に関する情報が提供されます。

{
  "status": "IN_PROGRESS",
  "statusReason": {
    "reasonCode": "200",
    "reasonDescription": "Execution_in_progress"
  },
  "result": {
        "car_battery": {
            "s": "car battery at 50 percent"
        }
    }
}

次のいずれかの方法を使用して、コンソールからコマンド実行を取得できます。

GetCommandExecution AWS IoT Core コントロールプレーンの HTTP API オペレーションを使用して、コマンド実行に関する情報を取得します。StartCommandExecution API オペレーションを使用して、このコマンドがあらかじめ実行されている必要があります。

サンプルの IAM ポリシー

この API オペレーションを使用する前に、デバイスでこのアクションを実行することを IAM ポリシーが許可していることを確認してください。以下に、GetCommandExecution アクションの実行をユーザーに許可する IAM ポリシーの例を示しています。

この例では、次のように置き換えます。

{
  "Effect": "Allow",
  "Action": [
      "iot:GetCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

コマンド実行を取得する例

次の例は、 コマンドを使用して実行されたstart-command-execution AWS CLI コマンドに関する情報を取得する方法を示しています。次の例では、ステアリングホイールモードをオフにするために実行されたコマンドに関する情報を取得する方法が示されています。

この例では、次のように置き換えます。

aws iot get-command-execution  
    --execution-id <execution-id> \ 
    --target-arn <target-arn> \
    --include-result

このコマンドを実行すると、コマンド実行の ARN、実行ステータス、実行開始時刻、完了時刻に関する情報を含むレスポンスが生成されます。また、ステータスに関する追加情報を含む statusReason オブジェクトも提供されます。それぞれのステータスとステータスの理由については、「コマンド実行ステータス」を参照してください。

次のコードは、API リクエストからのレスポンスの例を示しています。

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor",
    "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/myRegisteredThing",
    "status": "SUCCEEDED",
    "statusReason": {
        "reasonCode": "DEVICE_SUCCESSFULLY_EXECUTED",
        "reasonDescription": "SUCCESS"
    },
    "result": {
        "sn": { "s": "ABC-001" },
        "digital": { "b": true }        
    },
    "createdAt": "2024-03-23T00:50:10.095000-07:00",
    "completedAt": "2024-03-23T00:50:10.095000-07:00"    
}

次のいずれかの方法を使用して、コンソールからすべてのコマンド実行を表示できます。

ListCommandExecutions AWS IoT Core コントロールプレーンの HTTP API オペレーションを使用して、アカウント内のすべてのコマンド実行を一覧表示します。

サンプルの IAM ポリシー

この API オペレーションを使用する前に、デバイスでこのアクションを実行することを IAM ポリシーが許可していることを確認してください。以下に、ListCommandExecutions アクションの実行をユーザーに許可する IAM ポリシーの例を示しています。

この例では、次のように置き換えます。

{
  "Effect": "Allow",
  "Action": "iot:ListCommandExecutions",
  "Resource": *
}

コマンド実行を一覧表示する例

次の例は、 AWS アカウントのコマンド実行を一覧表示する方法を示しています。

コマンドを実行するときは、リストをフィルタリングして、targetArn を使用して特定のデバイスに対して作成されたコマンド実行のみを表示するか、commandArn を使用して指定された特定のコマンドの実行のみを表示するかを指定する必要があります。

この例では、次のように置き換えます。

aws iot list-command-executions \ 
--target-arn <target-arn> \ 
--started-time-filter '{after=<after>}' \
--sort-order "ASCENDING"

このコマンドを実行すると、作成したコマンド実行のリスト、実行の開始時刻、完了時刻を含むレスポンスが生成されます。また、ステータス情報と、ステータスに関する追加情報を含む statusReason オブジェクトも提供されます。

{
    "commandExecutions": [
        {
            "commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002",
            "executionId": "b2b654ca-1a71-427f-9669-e74ae9d92d24",
            "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f",
            "status": "TIMED_OUT",
            "createdAt": "2024-11-24T14:39:25.791000-08:00",
            "startedAt": "2024-11-24T14:39:25.791000-08:00"
        },
        {
            "commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002",
            "executionId": "34bf015f-ef0f-4453-acd0-9cca2d42a48f",
            "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f",
            "status": "IN_PROGRESS",
            "createdAt": "2024-11-24T14:05:36.021000-08:00",
            "startedAt": "2024-11-24T14:05:36.021000-08:00"
        }
    ]
}

それぞれのステータスとステータスの理由については、「コマンド実行ステータス」を参照してください。

この API オペレーションを使用する前に、デバイスがこれらのアクションを実行することを IAM ポリシーで許可していることを確認してください。以下に、デバイスがアクションを実行することを許可するポリシーの例を示しています。

この例では、次のように置き換えます。

{
  "Effect": "Allow",
  "Action": [
      "iot:DeleteCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

次の例は、 コマンドを使用してdelete-command AWS CLI コマンドを削除する方法を示しています。用途に応じて、<execution-id> を削除するコマンド実行の識別子に置き換え、<target-arn> をターゲットデバイスの ARN に置き換えてください。

aws iot delete-command-execution \ 
--execution-id <execution-id> \ 
--target-arn <target-arn>

API リクエストが成功すると、コマンド実行は 200 のステータスコードを生成します。GetCommandExecution API を使用して、コマンド実行がアカウントに存在していないことを確認できます。