翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# コマンド実行を開始およびモニタリングする
コマンドを作成したら、ターゲットデバイスで実行を開始します。デバイスは結果を更新し、MQTT 予約済みトピックにステータスを発行します。アカウントから実行ステータスを取得してモニタリングします。
AWS IoT コンソールまたは を使用して、 コマンドを起動およびモニタリングします AWS CLI。
**Topics**
+ [コマンド実行を開始する](#iot-remote-command-execution-start)
+ [コマンド実行の結果を更新する](#iot-remote-command-execution-update)
+ [コマンド実行を取得する](#iot-remote-command-execution-get)
+ [MQTT テストクライアントを使用したコマンドの更新の表示](#iot-remote-command-execution-update-mqtt)
+ [でコマンド実行を一覧表示する AWS アカウント](#iot-remote-command-execution-list)
+ [コマンド実行を削除する](#iot-remote-command-execution-delete)
## コマンド実行を開始する
**重要**
お客様は、安全かつ適用法に準拠した方法でコマンドをデプロイすることに全責任を負います。
実行を開始する前に、以下を確認してください。
+ ペイロード情報を使用して AWS IoT 名前空間に コマンドを作成しました。実行を開始すると、デバイスはペイロード命令を処理し、指定されたアクションを実行します。コマンドの作成[コマンドリソースを作成する](iot-remote-command-create-manage.md#iot-remote-command-create)については、「」を参照してください。
+ デバイスが コマンド用に MQTT 予約トピックにサブスクライブしました。Execution を開始すると、ペイロード情報は、この予約された MQTT リクエストトピックに発行されます。
** は Things または MQTT クライアントです。** はモノの名前またはクライアント ID です。サポートされている ** 値: JSON および CBOR。詳細については、「[コマンドトのピック](reserved-topics.md#reserved-topics-commands)」を参照してください。
```
$aws/commands///executions/+/request/
```
JSON/CBOR ** 以外の場合は、次のコマンドトピック形式を使用します。
```
$aws/commands///executions/+/request
```
### ターゲットデバイスに関する考慮事項
コマンドを受信して実行するターゲットデバイスを指定します。登録済みデバイスにはモノの名前、未登録デバイスにはクライアント ID を使用します。ペイロードを受信すると、デバイスは コマンドを実行し、指定されたアクションを実行します。
#### AWS IoT モノ
ターゲットデバイスは、 AWS IoT レジストリに登録されているモノにすることができます。モノはデバイスの検索と管理を簡素化します。
[Connect デバイスページまたは を使用して、デバイスを](https://console.aws.amazon.com/iot/home#/connect-overview)モノとして登録します[https://docs.aws.amazon.com/iot/latest/apireference/API_CreateThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateThing.html)。[Thing Hub ](https://console.aws.amazon.com/iot/home#/thinghub)または を使用して既存のモノを検索します[https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeThing.html)。登録の詳細については[、「レジストリでのモノの管理](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry)」を参照してください。
#### クライアント ID
未登録のデバイスの場合は、クライアント ID を使用します。
クライアント ID は、デバイスに割り当てる一意の識別子です。MQTT プロトコルで定義され、英数字、アンダースコア、またはダッシュが含まれます。に接続する各デバイスには、一意のクライアント ID AWS IoT が必要です。
**注記**
登録済みのモノの場合、クライアント 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` の実行ステータスがクラウドから報告されると、コマンドの実行は非終了の状態です。デバイスは、ステータスをターミナルステータス `SUCCEEDED`、、`FAILED`または のいずれかに上書きするレスポンスを発行できます`REJECTED`。その後、コマンド実行はターミナルになり、それ以降の更新は受け付けません。
デバイスは、コマンドの実行時にタイムアウトが発生したことを報告することで、クラウドによって開始された`TIMED_OUT`ステータスを更新することもできます。この場合、コマンドの実行ステータスは のままですが`TIMED_OUT`、`statusReason`オブジェクトはデバイスによって報告された情報に基づいて更新されます。その後、コマンドの実行はターミナルになり、それ以上の更新は受け入れられません。
#### MQTT 永続的セッションの使用
AWS IoT Device Management コマンド機能で使用するように MQTT 永続セッションを設定できます。この機能は、デバイスがオフラインになり、タイムアウト時間前にオンラインに戻ったときに、デバイスがコマンドを受信して指定された手順を実行できるようにする場合などに、特に便利です。
デフォルトでは、MQTT 永続セッションの有効期限は 60 分に設定されています。コマンド実行タイムアウトがこの期間を超える値に設定されている場合、60 分以上実行されるコマンド実行はメッセージブローカーによって拒否され、失敗する可能性があります。実行時間が 60 分を超えるコマンドを実行するには、永続セッションの有効期限の延長をリクエストできます。
**注記**
MQTT 永続セッション機能を正しく使用するには、クリーンスタートフラグをゼロに設定します。詳細については、「[MQTT 永続セッション](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html#mqtt-persistent-sessions)」を参照してください。
### コマンド実行を開始する (コンソール)
コンソールからコマンドの実行を開始するには、 AWS IoT コンソールの [コマンドハブ](https://console.aws.amazon.com/iot/home#/commandHub)ページに移動し、次の手順を実行します。
1. 作成したコマンドを実行するには、**[コマンドの実行]** を選択します。
1. MQTT 予約トピックや該当する場合はパラメータなど、作成したコマンドに関する情報を確認します。
動的コマンドの場合は、パラメータ値を入力するか、デフォルトのままにします。デフォルト値を持たないパラメータの場合、この実行の一部として送信される値を指定する必要があります。
1. コマンドを受信して実行するターゲットデバイスを指定します。デバイスが に登録されている場合は AWS IoT モノとして指定でき AWS IoT、デバイスがまだ登録されていない場合はクライアント ID を使用できます。詳細については、[ターゲットデバイスに関する考慮事項](#iot-command-execution-target)を参照してください。
1. (オプション) コマンドのタイムアウト値を設定し、タイムアウトまでにコマンドを実行する期間を決定します。コマンドを 60 分よりも長く実行させる場合は、MQTT 永続セッションの有効期間を延長する必要がある可能性があります。詳細については、「[コマンド実行のタイムアウトに関する考慮事項](#iot-command-execution-timeout)」を参照してください。
1. [**Run command**] を選択してください。
### コマンド実行を開始する (AWS CLI)
[https://docs.aws.amazon.com/iot/latest/apireference/API_StartCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_StartCommandExecution.html) HTTP データプレーン API オペレーションを使用して、コマンド実行を開始します。API リクエストとレスポンスは、コマンド実行 ID と相関しています。デバイスは、コマンドの実行を完了すると、コマンドレスポンストピックにメッセージを発行することで、ステータスと実行結果をクラウドに報告できます。カスタムレスポンスコードの場合、所有しているアプリケーションコードはレスポンスメッセージを処理して結果を投稿できます AWS IoT。
デバイスがコマンドリクエストトピックをサブスクライブしている場合は、`StartCommandExecution` API がペイロードメッセージをトピックに発行します。ペイロードには、任意の形式を使用できます。詳細については、「[コマンドのペイロード](iot-remote-command-create-manage.md#iot-commands-payload)」を参照してください。
```
$aws/commands///executions/+/request/
```
ペイロード形式が JSON または CBOR でない場合、コマンドリクエストトピックの形式を次に示します。
```
$aws/commands///executions/+/request
```
#### サンプルの IAM ポリシー
この API オペレーションを使用する前に、デバイスでこのアクションを実行することを IAM ポリシーが許可していることを確認してください。以下に、`StartCommandExecution` アクションの実行をユーザーに許可する IAM ポリシーの例を示しています。
この例では、次のように置き換えます。
+ `region` を `us-east-1` などお客様ご自身の AWS リージョンに置き換えます。
+ `account-id` を `123456789012` などの AWS アカウント 番号に置き換えます。
+ `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"
]
}
```
でサポートされている条件キーのリストを確認するには`StartCommandExecution`、*IAM ユーザーガイド*の「 [の条件キー AWS IoT](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html#awsiot-policy-keys)」を参照してください。
#### アカウント固有のデータプレーンエンドポイントを取得する
API コマンドを実行する前に、エンドポイントのアカウント固有のエンドポイント URL を取得する必要があります。デュアルスタックエンドポイント (IPv4 と IPv6) を使用している場合は、`iot:Data-ATS` を使用します。`iot:Jobs` エンドポイントは IPv4 専用です。たとえば、次のコマンドを実行するとします。
```
aws iot describe-endpoint --endpoint-type iot:Data-ATS
```
以下のレスポンスの例に示すように、アカウント固有のエンドポイント URL を返します。
```
{
"endpointAddress":
"-ats.iot..api.com"
}
```
#### コマンド実行を開始する例 (AWS CLI)
次の例は、 コマンドを使用して`start-command-execution` AWS CLI コマンドの実行を開始する方法を示しています。
この例では、次のように置き換えます。
+ *``* を実行するコマンドの ARN に置き換えます。この情報は、`create-command` CLI コマンドのレスポンスから取得できます。たとえば、ステアリングホイールモードを変更するためのコマンドを実行する場合は、`arn:aws:iot:region:account-id:command/SetComfortSteeringMode` を使用します。
+ *``* をターゲットデバイスのモノの ARN に置き換えます。これは、コマンド実行のターゲットとなる IoT のモノ、または MQTT クライアントです。たとえば、ターゲットデバイス `myRegisteredThing` に対してコマンドを実行する場合は、`arn:aws:iot:region:account-id:thing/myRegisteredThing` を使用します。
+ *``* を、[アカウント固有のデータプレーンエンドポイントを取得する](#iot-remote-command-execution-start-endpoint) で取得したアカウント固有のエンドポイントに `https://` のプレフィックスを付けて置き換えます。例えば、`https://123456789012abcd.jobs.iot.us-east-1.amazonaws.com`。
+ (オプション) `StartCommandExecution` API オペレーションを実行するときに、追加のパラメータ `executionTimeoutSeconds` を指定することもできます。このオプションフィールドは、デバイスがコマンドの実行を完了する必要がある時間枠を秒単位で指定します。デフォルト値は 10 秒です。コマンドの実行ステータスが `CREATED` になると、タイマーが開始されます。タイマーの有効期限が切れる前にコマンド実行結果が受信されない場合は、ステータスは自動的に `TIMED_OUT` に変わります。
+
```
aws iot-jobs-data start-command-execution \
--command-arn \
--target-arn \
--endpoint \
--execution-timeout-seconds 900
```
+ (オプション) 動的コマンドの場合は、置換に使用するパラメータとその値を指定します。コマンドの作成時に defaultValue が設定されていないパラメータの値を指定する必要があります。パラメータに defaultValue がある場合、ここで指定するパラメータ値が優先されます。valueConditions が設定されているパラメータの場合、ここで指定するパラメータ値は 条件を満たす必要があります。
`Light_Power_Status` 動的コマンドの例に基づく:
+
```
aws iot-jobs-data start-command-execution \
--command-arn arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status \
--target-arn arn:aws:iot:us-east-1:123456789012:thing/exampleThing \
--endpoint \
--execution-timeout-seconds 900 \
--parameters "powerStatus={S=ON}"
```
このコマンドを実行すると、コマンド実行 ID が返されます。この ID を使用して、コマンド実行ステータス、詳細、およびコマンド実行履歴をクエリすることができます。
**注記**
コマンドが非推奨になった場合、`StartCommandExecution` API リクエストは検証の例外で失敗します。このエラーを修正するには、まず `UpdateCommand` API を使用してコマンドを復元してから、`StartCommandExecution` リクエストを実行します。
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}
```
## コマンド実行の結果を更新する
コマンド実行のステータスまたは結果を更新するには、`UpdateCommandExecution` MQTT データプレーン API オペレーションを使用します。
**注記**
この API を使用する前に:
デバイスで MQTT 接続が確立されており、コマンドのリクエストとレスポンスのトピックがサブスクライブされている必要があります。詳細については、「[高レベルのコマンドワークフロー](iot-remote-command-workflow.md)」を参照してください。
`StartCommandExecution` API オペレーションを使用して、このコマンドがあらかじめ実行されている必要があります。
### サンプルの IAM ポリシー
この API オペレーションを使用する前に、デバイスがこれらのアクションを実行することを IAM ポリシーで許可していることを確認してください。以下に、デバイスがアクションを実行することを許可するポリシーの例を示しています。`UpdateCommandExecution` MQTT アクションを実行するアクセス許可をユーザーに付与する追加のサンプル IAM ポリシーについては、「」を参照してください[接続および公開ポリシーの例](connect-and-pub.md)。
この例では、次のように置き換えます。
+ `Region` など AWS リージョン、 で を使用します`us-east-1`。
+ `AccountID` を *`123456789012`* などの AWS アカウント 番号に置き換えます。
+ `ThingName` は、 など、コマンド実行をターゲットとする AWS IoT モノの名前で指定します*`myRegisteredThing`*。
+ `commands-request-topic` および AWS IoT コマンドリクエストおよびレスポンストピック`commands-response-topic`の名前。詳細については、「[高レベルのコマンドワークフロー](iot-remote-command-workflow.md)」を参照してください。
#### 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}"
}
]
}
```
### `UpdateCommandExecution` API の使用方法
コマンド実行がリクエストトピックで受信されると、デバイスはコマンドを処理します。デバイスはその後、`UpdateCommandExecution` API を使用して、コマンド実行のステータスと結果を次のレスポンストピックに更新します。
```
$aws/commands///executions//response/
```
この例では、*``* はターゲットデバイスの一意の識別子であり、*``* はターゲットデバイスでのコマンド実行の識別子です。** は JSON または CBOR です。
**注記**
デバイスを に登録していない場合は AWS IoT、モノの名前の代わりにクライアント ID を識別子として使用できます。
```
$aws/commands/clients//executions//response/
```
#### 実行ステータスに対する更新をデバイスで報告する
デバイスは、API を使用することで、コマンド実行に対する以下のステータス更新を報告できます。これらのステータスの詳細については、「[コマンド実行ステータス](iot-remote-command-concepts.md#iot-command-execution-status)」を参照してください。
+ `IN_PROGRESS`: デバイスでコマンドの実行が開始されると、デバイスはステータスを `IN_PROGRESS` に更新できます。
+ `SUCCEEDED`: コマンドが正常に処理されて実行が完了すると、デバイスは応答トピックに `SUCCEEDED` としてメッセージを発行できます。
+ `FAILED`: コマンドの実行に失敗した場合は、デバイスはレスポンストピックに `FAILED` としてメッセージを発行できます。
+ `REJECTED`: デバイスがコマンドを受け入れなかった場合、デバイスはレスポンストピックに `REJECTED` としてメッセージを発行できます。
+ `TIMED_OUT`: コマンドの実行ステータスは、次のいずれかの理由で `TIMED_OUT` に変わる場合があります。
+ コマンド実行の結果が受信されなかった。これは、実行が指定された期間内に完了しなかったか、デバイスがレスポンストピックにステータス情報を発行できなかったために発生する可能性があります。
+ デバイスは、コマンドの実行を試行したときにタイムアウトが発生したことを報告します。
`TIMED_OUT` ステータスの詳細については、「[タイムアウト値と `TIMED_OUT` 実行ステータス](#iot-command-execution-timeout-status)」を参照してください。
#### `UpdateCommandExecution` API を使用するときの考慮事項
`UpdateCommandExecution` API を使用する際の重要な考慮事項を以下に示しています。
+ デバイスは、オプションの `statusReason` オブジェクトを使用して、実行に関する追加情報を提供できます。デバイスがこのオブジェクトを提供する場合、 オブジェクトの `reasonCode` フィールドは必須ですが、 `reasonDescription`フィールドはオプションです。
+ デバイスが `statusReason` オブジェクトを使用する場合、 は パターンを使用し`[A-Z0-9_-]+`、64 文字を超えないように`reasonCode`する必要があります。を指定する場合は`reasonDescription`、1,024 文字を超えないようにしてください。改行などのコントロール文字を除く任意の文字を使用できます。
+ デバイスは、オプションの `result` オブジェクトを使用することで、リモート関数呼び出しの戻り値など、コマンド実行の結果に関する情報を提供できます。`result` を指定する場合は、少なくとも 1 つのエントリが必要です。
+ `result` フィールドでは、エントリをキーと値のペアとして指定します。エントリごとに、データ型情報を文字列、ブール値、またはバイナリとして指定する必要があります。文字列データ型はキー `s` を使用し、ブール値データ型はキー `b` を使用し、バイナリデータ型はキー `bin` を使用する必要があります。これらのキーが小文字であることを確認します。
+ `UpdateCommandExecution` API の実行中にエラーが発生した場合は、Amazon CloudWatch の `AWSIoTLogsV2` ロググループでエラーを表示できます。ログの有効化とログの表示については、「[AWS IoT ログ記録の設定](configure-logging.md)」を参照してください。
#### `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"
}
}
}
```
## コマンド実行を取得する
コマンドを実行したら、 AWS IoT コンソールと を使用してコマンド実行に関する情報を取得できます AWS CLI。取得できる情報は次のとおりです。
**注記**
最新のコマンド実行ステータスを取得するには、以下で説明するように、デバイスが `UpdateCommandExecution` MQTT API を使用してレスポンストピックにステータス情報を発行する必要があります。デバイスがこのトピックに発行するまで、`GetCommandExecution` API はステータスを `CREATED` または `TIMED_OUT` として報告します。
作成する各コマンドの実行には以下が含まれます。
+ **実行 ID**。これはコマンド実行の一意の識別子です。
+ コマンド実行の**ステータス**。ターゲットデバイスでコマンドを実行すると、コマンド実行は `CREATED` ステータスになります。その後、以下で説明するように、他のコマンド実行ステータスに移行できます。
+ コマンド実行の**結果**。
+ 一意の**コマンド ID** と、実行が作成されたターゲットデバイス。
+ **開始日**。コマンド実行が作成された日時を示します。
### コマンド実行を取得する (コンソール)
次のいずれかの方法を使用して、コンソールからコマンド実行を取得できます。
+
**[コマンドハブ] ページから**
AWS IoT コンソールの [コマンドハブ](https://console.aws.amazon.com/iot/home#/commandHub)ページに移動し、以下の手順を実行します。
1. ターゲットデバイスで実行を作成したコマンドを選択します。
1. コマンドの詳細ページの **[コマンド履歴]** タブに、作成した実行が表示されます。情報を取得する実行を選択します。
1. デバイスが `UpdateCommandExecution` API を使用して結果情報を提供した場合は、このページの **[結果]** タブでこの情報を確認できます。
+
**[モノのハブ] ページから**
コマンドの実行時にターゲットデバイスとして AWS IoT モノを選択した場合は、モノのハブページから実行の詳細を表示できます。
1. AWS IoT コンソールの [Thing Hub ](https://console.aws.amazon.com/iot/home#/thinghub)ページに移動し、コマンド実行を作成したモノを選択します。
1. モノの詳細ページの **[コマンド履歴]** に、作成した実行が表示されます。情報を取得する実行を選択します。
1. デバイスが `UpdateCommandExecution` API を使用して結果情報を提供した場合は、このページの **[結果]** タブでこの情報を確認できます。
### コマンド実行を取得する (CLI)
[https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html) AWS IoT Core コントロールプレーンの HTTP API オペレーションを使用して、コマンド実行に関する情報を取得します。`StartCommandExecution` API オペレーションを使用して、このコマンドがあらかじめ実行されている必要があります。
#### サンプルの IAM ポリシー
この API オペレーションを使用する前に、デバイスでこのアクションを実行することを IAM ポリシーが許可していることを確認してください。以下に、`GetCommandExecution` アクションの実行をユーザーに許可する IAM ポリシーの例を示しています。
この例では、次のように置き換えます。
+ `region` を `us-east-1` などお客様ご自身の AWS リージョンに置き換えます。
+ `account-id` を `123456789012` などの AWS アカウント 番号に置き換えます。
+ `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 コマンドに関する情報を取得する方法を示しています。次の例では、ステアリングホイールモードをオフにするために実行されたコマンドに関する情報を取得する方法が示されています。
この例では、次のように置き換えます。
+ *``* を情報を取得するコマンド実行の識別子に置き換えます。
+ *``* を実行のターゲットとするデバイスの Amazon リソース番号 (ARN) に置き換えます。この情報は、`start-command-execution` CLI コマンドのレスポンスから取得できます。
+ オプションで、デバイスが `UpdateCommandExection` API を使用して実行結果を提供した場合、`GetCommandExecution` API を使用して `GetCommandExecution` API のレスポンスにコマンド実行結果を含めるかどうかを指定できます。
```
aws iot get-command-execution
--execution-id \
--target-arn \
--include-result
```
このコマンドを実行すると、コマンド実行の ARN、実行ステータス、実行開始時刻、完了時刻に関する情報を含むレスポンスが生成されます。また、ステータスに関する追加情報を含む `statusReason` オブジェクトも提供されます。それぞれのステータスとステータスの理由については、「[コマンド実行ステータス](iot-remote-command-concepts.md#iot-command-execution-status)」を参照してください。
次のコードは、API リクエストからのレスポンスの例を示しています。
**注記**
実行レスポンスの `completedAt` フィールドは、デバイスが終了ステータスをクラウドに報告する時間に対応します。`TIMED_OUT` ステータスの場合、このフィールドはデバイスがタイムアウトを報告した場合にのみ設定されます。`TIMED_OUT` ステータスがクラウドによって設定された場合は、`TIMED_OUT` ステータスは更新されません。このタイムアウトの動作の詳細については、「[コマンド実行のタイムアウトに関する考慮事項](#iot-command-execution-timeout)」を参照してください。
```
{
"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"
}
```
## MQTT テストクライアントを使用したコマンドの更新の表示
MQTT テストクライアントを使用すると、コマンド機能を使用の際に、MQTT 経由でのメッセージの送受信を表示できます。デバイスが との MQTT 接続を確立したら AWS IoT、コマンドを作成してペイロードを指定し、デバイスで実行できます。コマンドを実行すると、デバイスがコマンドの MQTT 予約済みリクエストトピックをサブスクライブしている場合、このトピックに発行されたペイロードメッセージが表示されます。
その後、デバイスはペイロードの指示を受け取り、 AWS IoT デバイスで指定されたオペレーションを実行します。次に、 `UpdateCommandExecution` API を使用してコマンド実行結果とステータス情報を command. AWS IoT Device Management listens の MQTT 予約レスポンストピックに発行し、レスポンストピックを更新して更新された情報を保存し、 AWS CloudTrail と Amazon CloudWatch にログを発行します。その後、コンソールから、または `GetCommandExecution` API を使用して、最新のコマンド実行情報を取得できます。
次の手順は、MQTT テストクライアントを使用してメッセージを観察する方法を示しています。
1. AWS IoT コンソールで [MQTT テストクライアント](https://console.aws.amazon.com/iot/home#/test)を開きます。
1. **Subscribe** タブで、次のトピックを入力し、**Subscribe** を選択します。** は、登録したデバイスのモノの名前です AWS IoT。
**注記**
デバイスのモノの名前は、 AWS IoT コンソールの [Thing Hub ](https://console.aws.amazon.com/iot/home#/thinghub)ページから確認できます。デバイスをモノとして登録していない場合は、Connect device ページ AWS IoT から に接続するときにデバイスを登録できます。 [https://console.aws.amazon.com/iot/home#/connect-overview](https://console.aws.amazon.com/iot/home#/connect-overview)
```
$aws/commands/things//executions/+/request
```
1. (オプション) **[サブスクライブ]** タブで、次のトピックを入力し、**[サブスクライブ]** を選択することもできます。
```
$aws/commands/things/+/executions/+/response/accepted/json
$aws/commands/things/+/executions/+/response/rejected/json
```
1. コマンド実行が開始されると、デバイスがサブスクライブしているリクエストトピック `$aws/commands/things//executions/+/request` を使用して、メッセージペイロードがデバイスに送信されます。MQTT テストクライアントには、デバイスがコマンドを処理する手順を含むコマンドペイロードが表示されます。
1. コマンドの実行を開始した後、デバイスは、次の MQTT 予約済みレスポンストピックにコマンドのステータス更新を発行することができます。
```
$aws/commands///executions//response/json
```
例えば、車の空調をオンにして温度を目的の値まで下げるために実行したコマンドを考えてみましょう。次の 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 コンソールの [コマンドハブ](https://console.aws.amazon.com/iot/home#/commandHub)ページに移動し、以下の手順を実行します。
1. ターゲットデバイスで実行を作成したコマンドを選択します。
1. コマンドの詳細ページで、**[コマンド履歴]** タブに移動すると、作成した実行が一覧表示されます。
+
**[モノのハブ] ページから**
コマンドの実行時にターゲットデバイスとして AWS IoT モノを選択し、1 つのデバイスに複数のコマンド実行を作成した場合は、モノのハブページからデバイスの実行を表示できます。
1. AWS IoT コンソールの [Thing Hub ](https://console.aws.amazon.com/iot/home#/thinghub)ページに移動し、実行を作成したモノを選択します。
1. モノの詳細ページの **[コマンド履歴]** に、デバイスに対して作成した実行のリストが表示されます。
### アカウントのコマンド実行を一覧表示する (CLI)
[https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommandExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommandExecutions.html) AWS IoT Core コントロールプレーンの HTTP API オペレーションを使用して、アカウント内のすべてのコマンド実行を一覧表示します。
#### サンプルの IAM ポリシー
この API オペレーションを使用する前に、デバイスでこのアクションを実行することを IAM ポリシーが許可していることを確認してください。以下に、`ListCommandExecutions` アクションの実行をユーザーに許可する IAM ポリシーの例を示しています。
この例では、次のように置き換えます。
+ `region` を `us-east-1` などお客様ご自身の AWS リージョンに置き換えます。
+ `account-id` を `123456789012` などの AWS アカウント 番号に置き換えます。
+ `command-id` などの一意の AWS IoT コマンド識別子を使用します`LockDoor`。
```
{
"Effect": "Allow",
"Action": "iot:ListCommandExecutions",
"Resource": *
}
```
#### コマンド実行を一覧表示する例
次の例は、 AWS アカウントのコマンド実行を一覧表示する方法を示しています。
コマンドを実行するときは、リストをフィルタリングして、`targetArn` を使用して特定のデバイスに対して作成されたコマンド実行のみを表示するか、`commandArn` を使用して指定された特定のコマンドの実行のみを表示するかを指定する必要があります。
この例では、次のように置き換えます。
+ *``* を、`arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f` などの、実行のターゲットとするデバイスの Amazon リソース番号 (ARN) に置き換えます。
+ *``* を、`arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f` などの、実行のターゲットとするデバイスの Amazon リソース番号 (ARN) に置き換えます。
+ *``* は、特定の日時以降に作成された実行を一覧表示する場合の日時に置き換えます。たとえば、`2024-11-01T03:00`。
```
aws iot list-command-executions \
--target-arn \
--started-time-filter '{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"
}
]
}
```
それぞれのステータスとステータスの理由については、「[コマンド実行ステータス](iot-remote-command-concepts.md#iot-command-execution-status)」を参照してください。
## コマンド実行を削除する
コマンド実行が不要になった場合は、アカウントから完全に削除することができます。
**注記**
コマンド実行は、`SUCCEEDED`、`FAILED`、`REJECTED` などの終了ステータスになった場合にのみ削除できます。
このオペレーションは、 AWS IoT Core API または を使用してのみ実行できます AWS CLI。これはコンソールからは利用できません。
### サンプルの IAM ポリシー
この API オペレーションを使用する前に、デバイスがこれらのアクションを実行することを IAM ポリシーで許可していることを確認してください。以下に、デバイスがアクションを実行することを許可するポリシーの例を示しています。
この例では、次のように置き換えます。
+ `Region` など AWS リージョン、 で を使用します`us-east-1`。
+ `AccountID` を *`123456789012`* などの AWS アカウント 番号に置き換えます。
+ `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 コマンドを削除する方法を示しています。用途に応じて、*``* を削除するコマンド実行の識別子に置き換え、*``* をターゲットデバイスの ARN に置き換えてください。
```
aws iot delete-command-execution \
--execution-id \
--target-arn
```
API リクエストが成功すると、コマンド実行は 200 のステータスコードを生成します。`GetCommandExecution` API を使用して、コマンド実行がアカウントに存在していないことを確認できます。