コマンドリソースを作成するコマンドに関する情報を取得するでコマンドを一覧表示する AWS アカウントコマンドリソースを更新するコマンドリソースを非推奨または復元するコマンドリソースを削除する

Create and manage commands

AWS IoT Device Management コマンド機能を使用して、再利用可能なリモートアクションを設定するか、デバイスに 1 回限りの即時の指示を送信できます。以下のセクションでは、 AWS IoT コンソールとを使用してコマンドを作成および管理する方法を示します AWS CLI。

コマンドオペレーションの作成と管理

コマンドリソースを作成する
コマンドに関する情報を取得する
でコマンドを一覧表示する AWS アカウント
コマンドリソースを更新する
コマンドリソースを非推奨または復元する
コマンドリソースを削除する

コマンドリソースを作成する

コマンドを作成するときは、次の情報を指定する必要があります。

一般情報

コマンドを作成するときは、ターゲットデバイスでコマンドを実行するときにコマンドを識別するのに役立つ一意の識別子であるコマンド ID を指定する必要があります。オプションで、表示名、説明、タグを指定して、コマンドをさらに管理することもできます。
Payload

また、デバイスが実行する必要があるアクションを定義するペイロードを指定する必要があります。オプションですが、ペイロード形式タイプを指定して、デバイスが正しくペイロードを抑制できるようにすることをお勧めします。

コマンドの予約済みトピックは、ペイロード形式タイプに依存する形式を使用します。

ペイロードコンテンツタイプを application/jsonまたはに指定するとapplication/cbor、リクエストトピックは次のようになります。
```
$aws/commands/<devices>/<DeviceID>/executions/+/request/<PayloadFormat>
```
application/json または以外のペイロードコンテンツタイプを指定する場合application/cbor、またはペイロード形式タイプを指定しない場合、リクエストトピックは次のようになります。この場合、ペイロード形式は MQTT メッセージヘッダーに含まれます。
```
$aws/commands/<devices>/<DeviceID>/executions/+/request
```

コマンドレスポンストピックは、ペイロード形式タイプを使用するjsonか、ペイロード形式タイプcborに依存しない形式を返します。レスポンストピックでは、<PayloadFormat> が jsonまたはである必要がある次の形式を使用しますcbor。


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

以下のセクションでは、コマンドペイロード形式の考慮事項と、コンソールからコマンドを作成する方法について説明します。

コマンドペイロード形式

ペイロードは任意の形式を使用できます。ペイロードの最大サイズは 32 KB を超えることはできません。デバイスがペイロードを安全かつ正しく解釈できるように、ペイロード形式タイプを指定することをお勧めします。

ペイロード形式タイプは、 application/jsonやなどのtype/subtype形式を使用して指定しますapplication/cbor。デフォルトでは、に設定されますapplication/octet-stream。指定できるペイロード形式の詳細については、「一般的な MIME タイプ」を参照してください。

コマンドの作成方法 (コンソール)

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

新しいコマンドリソースを作成するには、コマンドの作成を選択します。
ターゲットデバイスで実行するコマンドを識別するのに役立つ一意のコマンド ID を指定します。
(オプション) コマンドのタグとして、オプションの表示名、説明、および名前と値のペアを指定します。
デバイスが実行する必要があるアクションを含むペイロードファイルをローカルストレージからアップロードします。オプションですが、ペイロード形式タイプを指定して、デバイスがファイルを正しく解釈して指示を処理するようにすることをお勧めします。
コマンドの作成を選択します。

このセクションでは、コマンドリソースを作成するためにcreate-command実行できる HTTP コントロールプレーン API オペレーション AWS CLI 、、CreateCommandおよび対応するコマンドについて説明します。

トピック

コマンドペイロード
サンプルの IAM ポリシー。
コマンドの作成例

コマンドペイロード

コマンドを作成するときは、ペイロードを指定する必要があります。指定したペイロードは base64 でエンコードされています。デバイスがコマンドを受信すると、デバイス側のロジックはペイロードを処理し、指定されたアクションを実行できます。デバイスがコマンドとペイロードを正しく受信できるように、ペイロードコンテンツタイプを指定することをお勧めします。

注記

コマンドを作成した後は、ペイロードを変更することはできません。ペイロードを変更するには、新しいコマンドを作成する必要があります。

サンプルの IAM ポリシー。

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

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

region AWS リージョンなどのを使用しますap-south-1。
account-id は、などの AWS アカウント番号に置き換えます123456789012。
command-id など、 AWS IoT コマンド ID の一意の識別子を持つ LockDoor。複数のコマンドを送信する場合は、IAM ポリシーのリソースセクションでこれらのコマンドを指定できます。

コマンドの作成例

次の例は、コマンドを作成する方法を示しています。アプリケーションに応じて、以下を置き換えます。

<command-id> コマンドの一意の識別子を持つ。たとえば、家の doc-history をロックするには、を指定できますLockDoor。UUID を使用することをお勧めします。英数字、「-」、「_」を使用することもできます。
(オプション) <display-name>および <description> 。これは、などのコマンドのわかりやすい名前とわかりやすい説明を提供するために使用できるオプションのフィールドですLock the doors of my home。
namespaceコマンドの名前空間を指定するために使用できる。これはである必要がありますAWS-IoT。
payload には、コマンドの実行時に使用するペイロードとそのコンテンツタイプに関する情報が含まれています。


aws iot create-command \ 
    --command-id <command-id> \
    --display-name <display-name> \
    --description <description> \ 
    --namespace AWS-IoT \ 
    --payload '{"content":"eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=","contentType":"application/json"}'

このコマンドを実行すると、コマンドの ID と ARN (Amazon リソース名) を含むレスポンスが生成されます。たとえば、作成時に LockDoor コマンドを指定した場合、コマンドを実行するサンプル出力を次に示します。


{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:ap-south-1:123456789012:command/LockDoor"
}

コマンドに関する情報を取得する

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

コマンド ID、Amazon リソースネーム (ARN)、コマンドに指定した表示名と説明。
コマンドの状態。ターゲットデバイスでコマンドを実行できるかどうか、または非推奨または削除されているかどうかを示します。
指定したペイロードと形式タイプ。
コマンドが作成され、最後にアップデートされた時刻。

コンソールからコマンドを取得するには、 AWS IoT コンソールのコマンドハブに移動し、作成したコマンドを選択して詳細を表示します。

コマンドの詳細に加えて、ターゲットデバイスでのコマンドの実行に関する情報を提供するコマンド履歴を確認できます。デバイスでこのコマンドを実行すると、このタブで実行に関する情報を確認できます。

HTTP コントロールプレーン API GetCommand オペレーションまたは get-command AWS CLI コマンドを使用して、コマンドリソースに関する情報を取得します。CreateCommand API リクエストまたは CLI create-command を使用してコマンドを既に作成しておく必要があります。

サンプルの IAM ポリシー。

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

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

region AWS リージョンなどのを使用しますap-south-1。
account-id は、などの AWS アカウント番号に置き換えます123456789023。
command-id などの一意のコマンド識別子を使用します AWS IoT LockDoor。複数のコマンドを取得する場合は、IAM ポリシーのリソースセクションでこれらのコマンドを指定できます。

コマンド例を取得する (AWS CLI)

次の例は、を使用してコマンドに関する情報を取得する方法を示していますget-command AWS CLI。アプリケーションに応じて、を情報を取得するコマンドの識別子<command-id>に置き換えます。この情報は、 CLI create-command のレスポンスから取得できます。


aws iot get-command --command-id <command-id>

このコマンドを実行すると、コマンド、ペイロード、作成されて最後に更新された時刻に関する情報を含むレスポンスが生成されます。また、コマンドが廃止されたか、削除されているかどうかを示す情報も提供します。

たとえば、次のコードはサンプルレスポンスを示しています。


{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:<region>:<account>:command/LockDoor",
    "namespace": "AWS-IoT",
    "payload":{
        "content": "eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=",
        "contentType": "application/json"
    },
    "createdAt": "2024-03-23T00:50:10.095000-07:00",
    "lastUpdatedAt": "2024-03-23T00:50:10.095000-07:00",
    "deprecated": false,
    "pendingDeletion": false
}

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

コマンドを作成したら、アカウントで作成したコマンドを表示できます。リストには、以下に関する情報が記載されています。

コマンド ID、およびコマンドに指定した表示名。
コマンドの Amazon リソースネーム (ARN)。
コマンドがターゲットデバイスで実行できるかどうか、または非推奨かどうかを示すコマンド状態。

注記
アカウントから削除されているリストは表示されません。コマンドの削除が保留中の場合でも、コマンド ID を使用してこれらのコマンドの詳細を表示できます。
コマンドが作成され、最後に更新された時刻。

AWS IoT コンソールでは、Command Hub に移動して、作成したコマンドのリストとその詳細を確認できます。

作成したコマンドを一覧表示するには、 ListCommands API オペレーションまたは CLI list-commands を使用します。

サンプルの IAM ポリシー。

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

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

region を AWS リージョンなどので使用しますap-south-1。
account-id は、などの AWS アカウント番号を使用します123456789012。

アカウントのコマンドを一覧表示する例

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


aws iot list-commands --namespace "AWS-IoT"

このコマンドを実行すると、作成したコマンドのリスト、コマンドが作成された時刻、最後に更新された時刻を含むレスポンスが生成されます。また、コマンドが廃止されたか、ターゲットデバイスで実行できるかを示すコマンド状態情報も提供します。さまざまなステータスとステータスの理由の詳細については、「」を参照してくださいコマンド実行ステータス。

コマンドリソースを更新する

コマンドを作成したら、コマンドの表示名と説明を更新できます。

注記

コマンドのペイロードは更新できません。この情報を更新したり、変更されたペイロードを使用するには、新しいコマンドを作成する必要があります。

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

既存のコマンドリソースを更新するには、更新するコマンドを選択し、アクションで編集を選択します。
使用する表示名と説明、および名前と値のペアをコマンドのタグとして指定します。
編集を選択して、コマンドを新しい設定で保存します。

UpdateCommand コントロールプレーン API オペレーションまたは update-command AWS CLI を使用して、コマンドリソースを更新します。この API を使用すると、次のことができます。

作成したコマンドの表示名と説明を編集します。
コマンドリソースを非推奨にするか、既に非推奨になっているコマンドを復元します。

サンプルの IAM ポリシー。

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

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

region を AWS リージョンなどので使用しますap-south-1。
account-id は、などの AWS アカウント番号を使用します123456789012。
command-id などの一意のコマンド識別子を使用します AWS IoT LockDoor。複数のコマンドを取得する場合は、IAM ポリシーのリソースセクションでこれらのコマンドを指定できます。

コマンドの例に関する情報を更新する (AWS CLI)

次の例は、コマンドを使用してupdate-command AWS CLI コマンドに関する情報を更新する方法を示しています。この API を使用してコマンドリソースを非推奨または復元する方法については、「」を参照してくださいコマンドリソースを更新する (CLI)。

この例では、コマンドの表示名と説明を更新する方法を示します。アプリケーションに応じて、を情報を取得するコマンドの識別子<command-id>に置き換えます。


aws iot update-command \ 
    --command-id <command-id>    
    --displayname <display-name> \
    --description <description>

このコマンドを実行すると、コマンドに関する更新された情報と最後に更新された時刻を含むレスポンスが生成されます。次のコードは、AC をオフにするコマンドの表示名と説明を更新するためのリクエストとレスポンスの例を示しています。


aws iot update-command \ 
    --command-id <LockDoor> \ 
    --displayname <Secondary lock door> \
    --description <Locks doors to my home>

このコマンドを実行すると、次のレスポンスが生成されます。


{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:ap-south-1:123456789012:command/LockDoor",
    "displayName": "Secondary lock door",
    "description": "Locks doors to my home",
    "lastUpdatedAt": "2024-05-09T23:15:53.899000-07:00"
}

コマンドリソースを非推奨または復元する

コマンドを作成した後、コマンドの使用を継続しない場合は、非推奨としてマークできます。コマンドを非推奨にすると、保留中のすべてのコマンド実行は、ターミナルステータスに達するまでターゲットデバイスで実行され続けます。コマンドが非推奨になったら、新しいコマンド実行をターゲットデバイスに送信するなどに使用する場合は、復元する必要があります。

注記

廃止されたコマンドを編集したり、新しい実行を実行したりすることはできません。デバイスで新しいコマンドを実行するには、コマンドの状態が Available に変わるように復元する必要があります。

コマンドの廃止と復元、およびその考慮事項の詳細については、「」を参照してくださいDeprecate a command resource。

コマンドリソースを削除する

コマンドが不要になった場合は、アカウントから完全に削除できます。削除アクションが成功した場合:

コマンドが最大タイムアウトの 12 時間より長い期間廃止された場合、コマンドはすぐに削除されます。
コマンドが非推奨になっていない場合、または最大タイムアウトより短い期間非推奨になっている場合、コマンドは pending deletion状態になります。最大タイムアウトの 12 時間後に、アカウントから自動的に削除されます。

注記

コマンドの実行が保留中であっても、コマンドは削除される可能性があります。コマンドは保留中の削除状態になり、アカウントから自動的に削除されます。

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

削除するコマンドを選択し、アクションで削除を選択します。
コマンドを削除することを確認し、削除を選択します。

コマンドは削除対象としてマークされ、12 時間後にアカウントから完全に削除されます。

HTTP コントロールプレーン API DeleteCommand オペレーションまたは delete-command AWS CLI コマンドを使用して、コマンドリソースを削除します。削除アクションが成功すると、HTTP statusCodeが 204 または 202 と表示され、最大タイムアウト時間の 12 時間後にコマンドが自動的にアカウントから削除されます。204 ステータスの場合、コマンドが削除されたことを示します。

サンプルの IAM ポリシー。

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

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

region を AWS リージョンなどので使用しますap-south-1。
account-id は、などの AWS アカウント番号を使用します123456789012。
command-id などの一意のコマンド識別子を使用します AWS IoT LockDoor。複数のコマンドを取得する場合は、IAM ポリシーのリソースセクションでこれらのコマンドを指定できます。

コマンド例を削除する (AWS CLI)

次の例は、コマンドを使用してdelete-command AWS CLI コマンドを削除する方法を示しています。アプリケーションに応じて、を、削除するコマンドの識別子<command-id>に置き換えます。


aws iot delete-command --command-id <command-id>

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

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

コマンドワークフロー

コマンド実行を開始およびモニタリングする

Create and manage commands

コマンドオペレーションの作成と管理

コマンドリソースを作成する

一般情報

Payload

トピック

コマンドペイロード形式

コマンドの作成方法 (コンソール)

トピック

コマンドペイロード

注記

サンプルの IAM ポリシー。

コマンドの作成例

コマンドに関する情報を取得する

サンプルの IAM ポリシー。

コマンド例を取得する (AWS CLI)

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

注記

サンプルの IAM ポリシー。

アカウントのコマンドを一覧表示する例

コマンドリソースを更新する

注記

サンプルの IAM ポリシー。

コマンドの例に関する情報を更新する (AWS CLI)

コマンドリソースを非推奨または復元する

注記

コマンドリソースを削除する

注記

サンプルの IAM ポリシー。

コマンド例を削除する (AWS CLI)