コマンド実行の開始とモニタリング

コマンドを実行する場合は、コマンドを受け取るターゲットデバイスを指定し、指定された手順を実行する必要があります。ターゲットデバイスは、 AWS IoT モノでも、デバイスが AWS IoT レジストリに登録されていない場合はクライアント ID でもかまいません。コマンドペイロードを受け取ると、デバイスはコマンドの実行を開始し、指定されたアクションを実行できます。

AWS IoT モノ

コマンドのターゲットデバイスは、 AWS IoT モノレジストリに登録した AWS IoT モノにすることができます。のモノ AWS IoT を使用すると、デバイスの検索と管理が容易になります。

デバイスをモノとして登録するには、Connect デバイスページ AWS IoT から、または CreateThing を使用して にデバイスを接続しますAPI。 https://console.aws.amazon.com/iot/home#/connect-overviewコマンドを実行する既存のモノは、 AWS IoT コンソールの Thing Hub ページまたは DescribeThing を使用して見つけることができますAPI。デバイスを AWS IoT モノとして登録する方法については、「 レジストリでのモノの管理」を参照してください。

クライアント ID

デバイスが にモノとして登録されていない場合は AWS IoT、代わりにクライアント ID を使用できます。

クライアント ID は、デバイスまたはクライアントに割り当てる一意の識別子です。クライアント ID はMQTTプロトコルで定義され、英数字、アンダースコア、またはダッシュを含めることができます。が接続する各デバイスに一意である必要があります 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。

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

$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"
  ]
}

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

API コマンドを実行する前に、エンドポイントのアカウント固有のURLiot:Jobsエンドポイントを取得する必要があります。たとえば、次のコマンドを実行するとします。

aws iot describe-endpoint --endpoint-type iot:Jobs

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

{
    "endpointAddress": "<account-specific-prefix>.jobs.iot.<region>.amazonaws.com"
}

コマンド実行の開始例 (AWS CLI）

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

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

aws iot-jobs-data start-command-execution \ 
    --command-arn <command-arn>  \
    --target-arn <target-arn> \  
    --endpoint <endpoint-url> \ 
    --executionTimeoutSeconds 900

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

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

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

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

MQTT クライアント ID のサンプルIAMポリシー

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

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:Publish",
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/json"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "iot:Receive",
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request/json",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted/json",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected/json"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "iot:Subscribe",
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request/json",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted/json",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected/json"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "iot:Connect",
      "Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}"
    }
  ]
}

IoT モノのサンプルIAMポリシー

次のコードは、 モノを使用する AWS IoT ときのサンプルデバイスポリシーを示しています。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:Publish",
      "Resource": "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response"
    },
    {
      "Effect": "Allow",
      "Action": "iot:Receive",
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request/json",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted/json",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected/json"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "iot:Subscribe",
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request/json",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted/json",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected/json"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "iot:Connect",
      "Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}"
    }
  ]
}

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

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

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

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

デバイスが実行ステータスの更新を報告しました

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

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

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

以下は、 UpdateCommandExecution を使用する際の重要な考慮事項ですAPI。

UpdateCommandExecution API 例

次のコードは、デバイスが を使用して実行ステータスUpdateCommandExecutionAPIを報告する方法、ステータスに関する追加情報を提供する statusReasonフィールド、およびこの場合は自動車バッテリーの割合など、実行の結果に関する情報を提供する 結果フィールドの例を示しています。

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

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

GetCommandExecution AWS IoT Core コントロールプレーンHTTPAPIオペレーションを使用して、コマンド実行に関する情報を取得します。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:ap-south-1:123456789012:command/LockDoor",
    "targetArn": "arn:aws:iot:ap-south-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 コントロールプレーンHTTPAPIオペレーションを使用して、アカウント内のすべてのコマンド実行を一覧表示します。

サンプル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>に置き換え、 をターゲットデバイスの ARN <target-arn>に置き換えます。

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

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