コマンドの作成と管理

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

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

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

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

コマンドペイロード形式

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

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

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

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

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

コマンドペイロード

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

サンプルIAMポリシー

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

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

{
    "Version": "2012-10-17",
    "Statement": 
    {
        "Action": "iot:CreateCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:<region>:<account_id>:command/command-id"          
    }
}

コマンドの作成例

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

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-commandCLI。

サンプルIAMポリシー

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

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

{
    "Version": "2012-10-17",
    "Statement": 
    {
        "Action": "iot:GetCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:<region>:<account_id>:command/command-id"          
    }
}

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

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

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

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

サンプルIAMポリシー

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

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

{
    "Version": "2012-10-17",
    "Statement": 
    {
        "Action": "iot:ListCommands",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:<region>:<account_id>:command/*"          
    }
}

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

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

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

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

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

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

サンプルIAMポリシー

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

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

{
    "Version": "2012-10-17",
    "Statement": 
    {
        "Action": "iot:UpdateCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:<region>:<account_id>:command/<command-id>"          
    }
}

コマンドの例に関する情報を更新する (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 コマンドを使用して、コマンドリソースを削除します。削除アクションが成功すると、204 または 202 HTTPstatusCodeの が表示され、最大タイムアウト期間が 12 時間経過すると、コマンドは自動的にアカウントから削除されます。204 ステータスの場合、コマンドが削除されたことを示します。

サンプルIAMポリシー

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

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

{
    "Version": "2012-10-17",
    "Statement": 
    {
        "Action": "iot:DeleteCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:<region>:<account_id>:command/command-id"          
    }
}

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

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

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

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