コマンドの作成と管理

コマンド予約 トピックは、ペイロード形式タイプに基づく形式を使用します。

コマンドレスポンス Topic は、ペイロードタイプに関係なく jsonまたは cbor形式を使用します。<PayloadFormat> は jsonまたは である必要がありますcbor。

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

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

静的コマンドペイロード形式

ペイロードは、最大 32 KB の任意の形式をサポートします。安全で正しいデバイス解釈のためにペイロード形式タイプを指定します。

形式 (例: application/jsonまたは application/cbor) を使用してペイロードtype/subtype形式タイプを指定します。デフォルト: application/octet-stream。サポートされている形式については、「一般的な MIME タイプ」を参照してください。

動的コマンドペイロード形式

payloadTemplate は、少なくとも 1 つのプレースホルダー、最大 32 KB の有効な JSON である必要があります。

AwsJsonSubstitution プリプロセッサの場合、 AWS IoT Device Management コマンドはプリプロセッサ設定に基づいて JSON または CBOR 形式で通知を送信します。

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

コンソールからコマンドを作成するには、Command Hub に移動し、次の手順に従います。

CreateCommand API または create-command CLI コマンドを使用して コマンドを作成します。

コマンドのペイロード

静的ペイロードまたはペイロードテンプレートを指定します。静的ペイロードは 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:us-east-1:123456789012:command/LockDoor"
}

動的コマンド作成の例

次の例は、動的コマンドを作成する方法を示しています。用途に応じて、以下を置き換えてください。

aws iot create-command \
    --command-id Light_Power_Status \
    --description "Turn a light ON or OFF" \
    --namespace AWS-IoT \
    --payload-template '{"powerStatus":"${aws:iot:commandexecution::parameter:powerStatus}"}' \
    --preprocessor awsJsonSubstitution={outputFormat=JSON} \
    --mandatory-parameters "name=powerStatus, defaultValue={S=OFF}, valueConditions=[{comparisonOperator=IN_SET, operand={strings=['ON','OFF']}}]"
                    

このコマンドを実行すると、コマンドの ID と ARN (Amazon リソース名) を含むレスポンスが生成されます。たとえば以下は、作成時に Light_Power_Status コマンドを指定した場合の、コマンド実行の出力例です。

{
    "commandId": "Light_Power_Status",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status"
}

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

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

HTTP コントロールプレーン API GetCommand オペレーションまたは 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 コンソールでは、Command Hub に移動して、作成したコマンドのリストとその詳細を確認できます。

作成したコマンドを一覧表示するには、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:us-east-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 を使用して、コマンドがアカウントに存在していないことを確認できます。