コマンドの作成と管理

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

コマンドレスポンストピックは、ペイロード形式タイプを使用する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 コンソールの コマンドハブに移動し、次の手順を実行します。

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

コマンドペイロード

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

サンプルの IAM ポリシー。

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

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

コマンドの作成例

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

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 コンソールの コマンドハブに移動し、作成したコマンドを選択してその詳細を表示します。

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

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

サンプルの IAM ポリシー。

この API オペレーションを使用する前に、IAM ポリシーでデバイスでこのアクションを実行することを許可していることを確認してください。次の例は、GetCommandアクションを実行するアクセス許可をユーザーに付与する 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 IoT コンソールでは、Command Hub に移動することで、作成したコマンドのリストとその詳細を確認できます。

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

サンプルの IAM ポリシー。

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

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

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

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

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

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

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

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

サンプルの IAM ポリシー。

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

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

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

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

サンプルの IAM ポリシー。

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

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

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

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

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

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