コマンド実行の開始とモニタリング - AWS IoT Core
コマンド実行を開始するコマンド実行の結果を更新するコマンド実行を取得するMQTT テストクライアントを使用したコマンドの更新の表示でコマンド実行を一覧表示する AWS アカウントコマンド実行を削除する

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

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

コマンドリソースを作成したら、ターゲットデバイスでコマンド実行を開始できます。デバイスがコマンドの実行を開始すると、コマンド実行の結果の更新を開始し、ステータスの更新と結果情報を MQTT 予約済みトピックに発行できます。その後、コマンド実行のステータスを取得し、アカウントの実行のステータスをモニタリングできます。

このセクションでは、 AWS IoT コンソールと の両方を使用してコマンドを起動およびモニタリングする方法について説明します AWS CLI。

コマンド実行を開始する

重要

お客様は、安全かつ適用法に準拠した方法でコマンドをデプロイする責任を単独で負います。

コマンドの実行を開始する前に、以下を確認する必要があります。

  • AWS IoT 名前空間にコマンドを作成し、ペイロード情報を提供しました。コマンドの実行を開始すると、デバイスはペイロードの指示を処理し、指定されたアクションを実行します。コマンドの作成については、「」を参照してくださいコマンドリソースを作成する。

  • デバイスが コマンドの MQTT 予約トピックをサブスクライブしています。コマンドの実行を開始すると、ペイロード情報が次の予約済み MQTT リクエストトピックに発行されます。

    この場合、<devices> は IoT モノまたは MQTT クライアントのいずれかで、<DeviceID> はモノの名前またはクライアント ID です。サポートされている <PayloadFormat> は JSON と CBOR です。コマンドトピックの詳細については、「」を参照してくださいコマンドトピック。

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

    <PayloadFormat> が JSON および CBOR でない場合、コマンドトピックの形式を次に示します。

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

コマンドを実行する場合は、コマンドを受信するターゲットデバイスを指定し、指定された手順を実行する必要があります。ターゲットデバイスは、 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。

注記

  • デバイスが AWS IoT レジストリにモノとして登録されている場合、クライアント ID はモノの名前と同じにすることができます。

  • コマンド実行が特定の MQTT クライアント ID を対象としている場合、クライアント ID ベースのコマンドトピックからコマンドペイロードを受信するには、デバイスは同じクライアント 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がクラウドから報告されると、コマンドの実行は非ターミナルです。デバイスは、ステータスをターミナルステータス 、、SUCCEEDEDFAILEDまたは のいずれかに上書きするレスポンスを発行できますREJECTED。コマンドの実行がターミナルになり、それ以降の更新は受け入れられなくなりました。

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

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

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

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

注記

MQTT 永続セッション機能を正しく使用するには、クリーンスタートフラグがゼロに設定されていることを確認します。詳細については、「MQTT 永続セッション」を参照してください。

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

  1. 作成したコマンドを実行するには、コマンドの実行を選択します。

  2. 作成したコマンド、ペイロードファイルと形式タイプ、予約された MQTT トピックに関する情報を確認します。

  3. コマンドを実行するターゲットデバイスを指定します。デバイスが に登録されている場合は AWS IoT モノとして指定でき AWS IoT、デバイスがまだ登録されていない場合はクライアント ID を使用できます。詳細については、ターゲットデバイスの考慮事項を参照してください。

  4. （オプション) コマンドのタイムアウト値を設定し、タイムアウトまでにコマンドを実行する期間を決定します。コマンドの実行時間が 60 分を超える場合は、MQTT 永続セッションの有効期限を長くする必要がある場合があります。詳細については、「コマンド実行タイムアウトに関する考慮事項」を参照してください。

  5. [Run command] を選択してください。

HTTP データプレーン API StartCommandExecution オペレーションを使用して、コマンド実行を開始します。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 ポリシーを示しています。

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

  • region を AWS リージョンなどの で使用しますap-south-1。

  • account-id は、 などの AWS アカウント 番号に置き換えます123456789012。

  • command-id など、 AWS IoT コマンドの一意の識別子を持つ LockDoor。複数のコマンドを送信する場合は、IAM ポリシーでこれらのコマンドを指定できます。

  • devices デバイスが AWS IoT モノとして登録されているか、MQTT クライアントとして指定されているかclientに応じて、 thingまたは のいずれかを使用します。

  • device-id thing-nameまたは AWS IoT を使用しますclient-id。

{
  "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 コマンドを実行する前に、エンドポイントのアカウント固有のiot:Jobsエンドポイント URL を取得する必要があります。たとえば、次のコマンドを実行するとします。

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 コマンドの実行を開始する方法を示しています。

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

  • <command-arn> 実行するコマンドの ARN を指定します。この情報は、 create-commandCLI コマンドのレスポンスから取得できます。たとえば、ステアリングホイールモードを変更するために コマンドを実行する場合は、 を使用しますarn:aws:iot:region:account-id:command/SetComfortSteeringMode。

  • <target-arn> ターゲットデバイスのモノの ARN を使用します。これは、コマンドを実行する IoT モノまたは MQTT クライアントです。たとえば、ターゲットデバイス に対して コマンドを実行する場合はmyRegisteredThing、 を使用しますarn:aws:iot:region:account-id:thing/myRegisteredThing。

  • <endpoint-url> は、 で取得したアカウント固有のエンドポイントでアカウント固有のデータプレーンエンドポイントを取得する、プレフィックスは ですhttps://。例えば、https://123456789012abcd.jobs.iot.ap-south-1.amazonaws.com。

  • （オプション) StartCommandExecution API オペレーションを実行するexecutionTimeoutSecondsときに、追加のパラメータ を指定することもできます。このオプションフィールドは、デバイスがコマンドの実行を完了する必要がある時間を秒単位で指定します。デフォルトでは、値は 10 秒です。コマンドの実行ステータスが の場合CREATED、タイマーが開始されます。タイマーの有効期限が切れる前にコマンド実行結果が受信されない場合、ステータスは自動的に に変わりますTIMED_OUT。

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

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

注記

コマンドが廃止された場合、StartCommandExecutionAPI リクエストは検証例外で失敗します。このエラーを修正するには、まず UpdateCommand API を使用してコマンドを復元し、次にStartCommandExecutionリクエストを実行します。

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

コマンド実行の結果を更新する

UpdateCommandExecution MQTT データプレーン API オペレーションを使用して、コマンド実行のステータスまたは結果を更新します。

注記

この API を使用する前に：

  • デバイスは MQTT 接続を確立し、コマンドのリクエストとレスポンスのトピックをサブスクライブしている必要があります。詳細については、「高レベルのコマンドワークフロー」を参照してください。

  • StartCommandExecution API オペレーションを使用してこのコマンドをすでに実行している必要があります。

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

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

  • Region など AWS リージョン、 で を使用しますap-south-1。

  • AccountID は、 などの AWS アカウント 番号に置き換えます123456789012。

  • ThingName は、 など、コマンド実行をターゲットとする AWS IoT モノの名前で指定しますmyRegisteredThing。

  • commands-request-topic および AWS IoT コマンドリクエストおよびレスポンストピックcommands-response-topicの名前。詳細については、「高レベルのコマンドワークフロー」を参照してください。

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

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

JSON
{
  "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 のサンプルデバイスポリシーを示しています。

JSON
{
  "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}"
    }
  ]
}

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

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

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

注記

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

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

実行ステータスに対するデバイスレポートの更新

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

  • IN_PROGRESS: デバイスがコマンドの実行を開始すると、ステータスを に更新できますIN_PROGRESS。

  • SUCCEEDED: デバイスがコマンドを正常に処理して実行を完了すると、デバイスは応答トピックにメッセージを として発行できますSUCCEEDED。

  • FAILED: デバイスがコマンドの実行に失敗した場合、レスポンストピックにメッセージを として発行できますFAILED。

  • REJECTED: デバイスがコマンドの受け入れに失敗した場合、レスポンストピックにメッセージを として発行できますREJECTED。

  • TIMED_OUT: コマンドの実行ステータスは、次のいずれかTIMED_OUTの理由で に変わることがあります。

    • コマンド実行の結果が受信されませんでした。これは、実行が指定された期間内に完了しなかったか、デバイスがレスポンストピックにステータス情報を公開できなかったために発生する可能性があります。

    • デバイスは、コマンドを実行しようとしたときにタイムアウトが発生したことを報告します。

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

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

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

  • デバイスは、実行に関する追加情報を提供するために使用できるオプションの statusReason オブジェクトを使用できます。デバイスがこのオブジェクトを提供する場合、 オブジェクトの reasonCode フィールドは必須ですが、 reasonDescriptionフィールドはオプションです。

  • デバイスが statusReason オブジェクトを使用する場合、 はパターン を使用するreasonCode必要があり[A-Z0-9_-]+、64 文字を超えることはできません。を指定する場合はreasonDescription、1,024 文字を超えないようにしてください。新しい行などのコントロール文字以外の任意の文字を使用できます。

  • デバイスは、オプションの result オブジェクトを使用して、リモート関数呼び出しの戻り値など、コマンド実行の結果に関する情報を提供できます。を指定する場合はresult、少なくとも 1 つのエントリが必要です。

  • result フィールドで、エントリをキーと値のペアとして指定します。エントリごとに、データ型情報を文字列、ブール値、またはバイナリとして指定する必要があります。文字列データ型はキー を使用しs、ブールデータ型はキー を使用しb、バイナリデータ型はキー を使用する必要がありますbin。これらのデータ型が小文字として記述されていることを確認する必要があります。

  • UpdateCommandExecution API の実行中にエラーが発生した場合は、Amazon CloudWatch のAWSIoTLogsV2ロググループでエラーを表示できます。ログの有効化と表示については、「」を参照してくださいAWS IoT ログ記録の設定。

UpdateCommandExecution API の例

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

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

コマンド実行を取得する

コマンドを実行したら、 AWS IoT コンソールと を使用してコマンド実行に関する情報を取得できます AWS CLI。以下の情報を取得できます。

注記

最新のコマンド実行ステータスを取得するには、以下で説明するように、デバイスが UpdateCommandExecution MQTT API を使用してレスポンストピックにステータス情報を公開する必要があります。デバイスがこのトピックに発行されるまで、GetCommandExecutionAPI はステータスを CREATEDまたは として報告しますTIMED_OUT。

作成する各コマンド実行には、次のものが含まれます。

  • 実行 ID。コマンド実行の一意の識別子です。

  • コマンド実行のステータス。ターゲットデバイスで コマンドを実行すると、コマンドの実行は CREATED状態になります。その後、以下で説明するように、他のコマンド実行ステータスに移行できます。

  • コマンド実行の結果。

  • 実行が作成された一意のコマンド ID とターゲットデバイス。

  • コマンド実行が作成された時刻を示す開始日。

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

  • コマンドハブページから

    AWS IoT コンソールの Command Hub ページに移動し、以下の手順を実行します。

    1. ターゲットデバイスで実行を作成したコマンドを選択します。

    2. コマンドの詳細ページの コマンド履歴タブに、作成した実行が表示されます。情報を取得する実行を選択します。

    3. デバイスが UpdateCommandExecution API を使用して結果情報を提供した場合は、このページの結果タブでこの情報を確認できます。

  • モノのハブページから

    コマンドの実行時にターゲットデバイスとして AWS IoT モノを選択した場合は、モノのハブページから実行の詳細を表示できます。

    1. AWS IoT コンソールの Thing Hub ページに移動し、コマンド実行を作成したモノを選択します。

    2. モノの詳細ページのコマンド履歴に、作成した実行が表示されます。情報を取得する実行を選択します。

    3. デバイスが UpdateCommandExecution API を使用して結果情報を提供した場合は、このページの結果タブでこの情報を確認できます。

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

サンプルの IAM ポリシー。

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

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

  • region AWS リージョンなどの を使用しますap-south-1。

  • account-id は、 などの AWS アカウント 番号に置き換えます123456789012。

  • command-id などの一意の AWS IoT コマンド識別子を使用しますLockDoor。

  • devices デバイスが AWS IoT モノとして登録されているか、MQTT クライアントとして指定されているかclientに応じて、 thingまたは のいずれかを使用します。

  • device-id thing-nameまたは AWS IoT を使用しますclient-id。

{
  "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 コマンドに関する情報を取得する方法を示しています。次の例は、ステアリングホイールモードをオフにするために実行されたコマンドに関する情報を取得する方法を示しています。

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

  • <execution-id> 情報を取得するコマンド実行の識別子。

  • <target-arn> 実行をターゲットとするデバイスの Amazon リソースナンバー (ARN) を使用します。この情報は、 start-command-executionCLI コマンドのレスポンスから取得できます。

  • オプションで、デバイスが UpdateCommandExection API を使用して実行結果を提供した場合、 GetCommandExecution API を使用して GetCommandExecution API のレスポンスにコマンド実行結果を含めるかどうかを指定できます。

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

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

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

注記

実行レスポンスの completedAtフィールドは、デバイスがターミナルステータスをクラウドにレポートする時間に対応します。TIMED_OUT ステータスの場合、このフィールドはデバイスがタイムアウトを報告した場合にのみ設定されます。TIMED_OUT ステータスがクラウドによって設定されている場合、TIMED_OUTステータスは更新されません。タイムアウト動作の詳細については、「」を参照してくださいコマンド実行タイムアウトに関する考慮事項。

{
    "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"    
}

MQTT テストクライアントを使用したコマンドの更新の表示

MQTT テストクライアントを使用して、 コマンド機能を使用するときに MQTT 経由でメッセージ交換を表示できます。デバイスが との MQTT 接続を確立したら AWS IoT、コマンドを作成してペイロードを指定し、デバイスで実行できます。コマンドを実行すると、デバイスがコマンドの MQTT 予約済みリクエストトピックをサブスクライブしている場合、このトピックに発行されたペイロードメッセージが表示されます。

その後、デバイスはペイロード指示を受け取り、IoT デバイスで指定されたオペレーションを実行します。次に、 UpdateCommandExecution API を使用してコマンド実行結果とステータス情報を command. AWS IoT Device Management listens の MQTT 予約レスポンストピックに発行し、レスポンストピックを更新して更新された情報を保存し、 AWS CloudTrail と Amazon CloudWatch にログを発行します。その後、コンソールまたは GetCommandExecution API を使用して、最新のコマンド実行情報を取得できます。

次の手順は、MQTT テストクライアントを使用してメッセージを観察する方法を示しています。

  1. AWS IoT コンソールで MQTT テストクライアントを開きます。

  2. Subscribe タブで、次のトピックを入力し、Subscribe を選択します。<thingId> は、登録したデバイスのモノの名前です AWS IoT。

    注記

    デバイスのモノの名前は、 AWS IoT コンソールの Thing Hub ページから確認できます。デバイスをモノとして登録していない場合は、Connect デバイスページ AWS IoT から に接続するときにデバイスを登録できます。 https://console.aws.amazon.com/iot/home#/connect-overview

    $aws/commands/things/<thingId>/executions/+/request

  3. （オプション) Subscribe タブで、次のトピックを入力し、Subscribe を選択することもできます。

    $aws/commands/things/+/executions/+/response/accepted/json
$aws/commands/things/+/executions/+/response/rejected/json

  4. コマンドの実行を開始すると、デバイスがサブスクライブしているリクエストトピック を使用して、メッセージペイロードがデバイスに送信されます$aws/commands/things/<thingId>/executions/+/request。MQTT テストクライアントには、デバイスがコマンドを処理する手順を含むコマンドペイロードが表示されます。

  5. デバイスがコマンドの実行を開始すると、次の MQTT 予約レスポンストピックにコマンドのステータス更新を発行できます。

    $aws/commands/<devices>/<device-id>/executions/<executionId>/response/json

    例えば、車の AC をオンにして温度を目的の値に減らすために実行したコマンドを考えてみましょう。次の JSON は、車両がコマンドの実行に失敗したことを示すレスポンストピックに発行したサンプルメッセージを示しています。

    {
  "deviceId": "My_Car",
  "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
  "status": "FAILED",
  "statusReason": {
    "reasonCode": "CAR_LOW_ON_BATTERY",
    "reasonDescription": "Car battery is lower than 5 percent"
  }
}

    この場合、車のバッテリーを充電し、コマンドを再度実行できます。

でコマンド実行を一覧表示する AWS アカウント

コマンドを実行したら、 AWS IoT コンソールと を使用してコマンド実行に関する情報を取得できます AWS CLI。以下の情報を取得できます。

  • 実行 ID。コマンド実行の一意の識別子です。

  • コマンド実行のステータス。ターゲットデバイスで コマンドを実行すると、コマンドの実行は CREATED状態になります。その後、以下で説明するように、他のコマンド実行ステータスに移行できます。

  • 実行が作成された一意のコマンド ID とターゲットデバイス。

  • コマンド実行が作成された時刻を示す開始日。

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

  • コマンドハブページから

    AWS IoT コンソールの Command Hub ページに移動し、以下の手順を実行します。

    1. ターゲットデバイスで実行を作成したコマンドを選択します。

    2. コマンドの詳細ページで、コマンド履歴タブに移動すると、作成した実行のリストが表示されます。

  • モノのハブページから

    コマンドの実行時にターゲットデバイスとして AWS IoT モノを選択し、1 つのデバイスに複数のコマンド実行を作成した場合は、モノのハブページからデバイスの実行を表示できます。

    1. AWS IoT コンソールの Thing Hub ページに移動し、実行を作成したモノを選択します。

    2. モノの詳細ページのコマンド履歴に、デバイス用に作成した実行のリストが表示されます。

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

サンプルの IAM ポリシー。

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

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

  • region AWS リージョンなどの を使用しますap-south-1。

  • account-id は、 などの AWS アカウント 番号に置き換えます123456789012。

  • command-id などの一意の AWS IoT コマンド識別子を使用しますLockDoor。

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

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

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

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

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

  • <target-arn> は、 など、実行をターゲットとするデバイスの Amazon リソースナンバー (ARN) を使用しますarn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f。

  • <target-arn> は、 など、実行をターゲットとするデバイスの Amazon リソースナンバー (ARN) を使用しますarn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f。

  • <after> を、作成された実行を一覧表示する時間に設定します。例: 2024-11-01T03:00。

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

さまざまなステータスとステータスの理由の詳細については、「」を参照してくださいコマンド実行ステータス。

コマンド実行を削除する

コマンド実行が不要になった場合は、アカウントから完全に削除できます。

注記

  • コマンド実行は、、、 SUCCEEDED FAILEDなどのターミナルステータスになった場合にのみ削除できますREJECTED。

  • このオペレーションは、 AWS IoT Core API または を使用してのみ実行できます AWS CLI。コンソールからは使用できません。

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

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

  • Region など AWS リージョン、 で を使用しますap-south-1。

  • AccountID は、 などの AWS アカウント 番号に置き換えます123456789012。

  • CommandID 実行を削除するコマンドの識別子。

  • devices デバイスが AWS IoT モノとして登録されているか、MQTT クライアントとして指定されているかclientに応じて、 thingまたは のいずれかを使用します。

  • device-id thing-nameまたは AWS IoT を使用しますclient-id。

{
  "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 のステータスコードを生成します。GetCommandExecution API を使用して、コマンド実行がアカウントに存在しなくなったことを確認できます。