コマンドの作成と管理

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

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

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

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

コマンドのペイロード形式

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

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

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

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

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

コマンドのペイロード

コマンドを作成するときは、ペイロードを指定する必要があります。指定したペイロードは 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 コンソールの [コマンドハブ] に移動し、作成したコマンドを選択してその詳細を表示します。

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

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

サンプルの IAM ポリシー

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

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

コマンド取得の例 (AWS CLI)

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

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 コンソールでは、[コマンドハブ]に移動して、作成したコマンドのリストとその詳細を確認することができます。

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

サンプルの 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 時間後にアカウントから完全に削除されます。

DeleteCommand HTTP コントロールプレーン API オペレーションまたは 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 を使用して、コマンドがアカウントに存在していないことを確認できます。