AWS API Changes

2024/11/22 - AWS IoT - 8 new api methods

Changes General Availability (GA) release of AWS IoT Device Management - Commands, to trigger light-weight remote actions on targeted devices

GetCommandExecution (new)

Link ¶

Gets information about the specific command execution on a single device.

See also: AWS API Documentation

Request Syntax

client.get_command_execution(
    executionId='string',
    targetArn='string',
    includeResult=True|False
)

type executionId:

string

param executionId:

[REQUIRED]

The unique identifier for the command execution. This information is returned as a response of the StartCommandExecution API request.

type targetArn:

string

param targetArn:

[REQUIRED]

The Amazon Resource Number (ARN) of the device on which the command execution is being performed.

type includeResult:

boolean

param includeResult:

Can be used to specify whether to include the result of the command execution in the GetCommandExecution API response. Your device can use this field to provide additional information about the command execution. You only need to specify this field when using the AWS-IoT namespace.

rtype:

dict

returns:

Response Syntax

{
    'executionId': 'string',
    'commandArn': 'string',
    'targetArn': 'string',
    'status': 'CREATED'|'IN_PROGRESS'|'SUCCEEDED'|'FAILED'|'REJECTED'|'TIMED_OUT',
    'statusReason': {
        'reasonCode': 'string',
        'reasonDescription': 'string'
    },
    'result': {
        'string': {
            'S': 'string',
            'B': True|False,
            'BIN': b'bytes'
        }
    },
    'parameters': {
        'string': {
            'S': 'string',
            'B': True|False,
            'I': 123,
            'L': 123,
            'D': 123.0,
            'BIN': b'bytes',
            'UL': 'string'
        }
    },
    'executionTimeoutSeconds': 123,
    'createdAt': datetime(2015, 1, 1),
    'lastUpdatedAt': datetime(2015, 1, 1),
    'startedAt': datetime(2015, 1, 1),
    'completedAt': datetime(2015, 1, 1),
    'timeToLive': datetime(2015, 1, 1)
}

Response Structure

(dict) --
- executionId (string) --
  
  The unique identifier of the command execution.
- commandArn (string) --
  
  The Amazon Resource Number (ARN) of the command. For example, arn:aws:iot:<region>:<accountid>:command/<commandId>
- targetArn (string) --
  
  The Amazon Resource Number (ARN) of the device on which the command execution is being performed.
- status (string) --
  
  The status of the command execution. After your devices receive the command and start performing the operations specified in the command, it can use the UpdateCommandExecution MQTT API to update the status information.
- statusReason (dict) --
  
  Your devices can use this parameter to provide additional context about the status of a command execution using a reason code and description.
  - reasonCode (string) --
    
    A code that provides additional context for the command execution status.
  - reasonDescription (string) --
    
    A literal string for devices to optionally provide additional information about the reason code for a command execution status.
- result (dict) --
  
  The result value for the current state of the command execution. The status provides information about the progress of the command execution. The device can use the result field to share additional details about the execution such as a return value of a remote function call.
  
  Note
  
  If you use the AWS-IoT-FleetWise namespace, then this field is not applicable in the API response.
  - (string) --
    - (dict) --
      
      The result value of the command execution. The device can use the result field to share additional details about the execution such as a return value of a remote function call.
      
      Note
      
      This field is not applicable if you use the AWS-IoT-FleetWise namespace.
      - S (string) --
        
        An attribute of type String. For example:
        
        "S": "Hello"
      - B (boolean) --
        
        An attribute of type Boolean. For example:
        
        "BOOL": true
      - BIN (bytes) --
        
        An attribute of type Binary.
- parameters (dict) --
  
  The list of parameters that the StartCommandExecution API used when performing the command on the device.
  - (string) --
    - (dict) --
      
      The range of possible values that's used to describe a specific command parameter.
      
      Note
      
      The commandParameterValue can only have one of the below fields listed.
      - S (string) --
        
        An attribute of type String. For example:
        
        "S": "Hello"
      - B (boolean) --
        
        An attribute of type Boolean. For example:
        
        "BOOL": true
      - I (integer) --
        
        An attribute of type Integer (Thirty-Two Bits).
      - L (integer) --
        
        An attribute of type Long.
      - D (float) --
        
        An attribute of type Double (Sixty-Four Bits).
      - BIN (bytes) --
        
        An attribute of type Binary. For example:
        
        "B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"
      - UL (string) --
        
        An attribute of type unsigned long.
- executionTimeoutSeconds (integer) --
  
  Specifies the amount of time in seconds that the device can take to finish a command execution. A timer starts when the command execution is created. If the command execution status is not set to another terminal state before the timer expires, it will automatically update to TIMED_OUT.
- createdAt (datetime) --
  
  The timestamp, when the command execution was created.
- lastUpdatedAt (datetime) --
  
  The timestamp, when the command execution was last updated.
- startedAt (datetime) --
  
  The timestamp, when the command execution was started.
- completedAt (datetime) --
  
  The timestamp, when the command execution was completed.
- timeToLive (datetime) --
  
  The time to live (TTL) parameter for the GetCommandExecution API.

DeleteCommand (new)

Link ¶

Delete a command resource.

See also: AWS API Documentation

Request Syntax

client.delete_command(
    commandId='string'
)

type commandId:

string

param commandId:

[REQUIRED]

The unique identifier of the command to be deleted.

rtype:

dict

returns:

Response Syntax

{
    'statusCode': 123
}

Response Structure

(dict) --
- statusCode (integer) --
  
  The status code for the command deletion request. The status code is in the 200 range for a successful request.
  - If the command hasn't been deprecated, or has been deprecated for a duration that is shorter than the maximum time out duration of 12 hours, when calling the DeleteCommand request, the deletion will be scheduled and a 202 status code will be returned. While the command is being deleted, it will be in a pendingDeletion state. Once the time out duration has been reached, the command will be permanently removed from your account.
  - If the command has been deprecated for a duration that is longer than the maximum time out duration of 12 hours, when calling the DeleteCommand request, the command will be deleted immediately and a 204 status code will be returned.

UpdateCommand (new)

Link ¶

Update information about a command or mark a command for deprecation.

See also: AWS API Documentation

Request Syntax

client.update_command(
    commandId='string',
    displayName='string',
    description='string',
    deprecated=True|False
)

type commandId:

string

param commandId:

[REQUIRED]

The unique identifier of the command to be updated.

type displayName:

string

param displayName:

The new user-friendly name to use in the console for the command.

type description:

string

param description:

A short text description of the command.

type deprecated:

boolean

param deprecated:

A boolean that you can use to specify whether to deprecate a command.

rtype:

dict

returns:

Response Syntax

{
    'commandId': 'string',
    'displayName': 'string',
    'description': 'string',
    'deprecated': True|False,
    'lastUpdatedAt': datetime(2015, 1, 1)
}

Response Structure

(dict) --
- commandId (string) --
  
  The unique identifier of the command.
- displayName (string) --
  
  The updated user-friendly display name in the console for the command.
- description (string) --
  
  The updated text description of the command.
- deprecated (boolean) --
  
  The boolean that indicates whether the command was deprecated.
- lastUpdatedAt (datetime) --
  
  The date and time (epoch timestamp in seconds) when the command was last updated.

ListCommands (new)

Link ¶

List all commands in your account.

See also: AWS API Documentation

Request Syntax

client.list_commands(
    maxResults=123,
    nextToken='string',
    namespace='AWS-IoT'|'AWS-IoT-FleetWise',
    commandParameterName='string',
    sortOrder='ASCENDING'|'DESCENDING'
)

type maxResults:

integer

param maxResults:

The maximum number of results to return in this operation. By default, the API returns up to a maximum of 25 results. You can override this default value to return up to a maximum of 100 results for this operation.

type nextToken:

string

param nextToken:

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to receive the first set of results.

type namespace:

string

param namespace:

The namespace of the command. By default, the API returns all commands that have been created for both AWS-IoT and AWS-IoT-FleetWise namespaces. You can override this default value if you want to return all commands that have been created only for a specific namespace.

type commandParameterName:

string

param commandParameterName:

A filter that can be used to display the list of commands that have a specific command parameter name.

type sortOrder:

string

param sortOrder:

Specify whether to list the commands that you have created in the ascending or descending order. By default, the API returns all commands in the descending order based on the time that they were created.

rtype:

dict

returns:

Response Syntax

{
    'commands': [
        {
            'commandArn': 'string',
            'commandId': 'string',
            'displayName': 'string',
            'deprecated': True|False,
            'createdAt': datetime(2015, 1, 1),
            'lastUpdatedAt': datetime(2015, 1, 1),
            'pendingDeletion': True|False
        },
    ],
    'nextToken': 'string'
}

Response Structure

(dict) --
- commands (list) --
  
  The list of commands.
  - (dict) --
    
    Summary information about a particular command resource.
    - commandArn (string) --
      
      The Amazon Resource Name (ARN) of the command.
    - commandId (string) --
      
      The unique identifier of the command.
    - displayName (string) --
      
      The display name of the command.
    - deprecated (boolean) --
      
      Indicates whether the command has been deprecated.
    - createdAt (datetime) --
      
      The timestamp, when the command was created.
    - lastUpdatedAt (datetime) --
      
      The timestamp, when the command was last updated.
    - pendingDeletion (boolean) --
      
      Indicates whether the command is pending deletion.
- nextToken (string) --
  
  The token to use to get the next set of results, or null if there are no additional results.

CreateCommand (new)

Link ¶

Creates a command. A command contains reusable configurations that can be applied before they are sent to the devices.

See also: AWS API Documentation

Request Syntax

client.create_command(
    commandId='string',
    namespace='AWS-IoT'|'AWS-IoT-FleetWise',
    displayName='string',
    description='string',
    payload={
        'content': b'bytes',
        'contentType': 'string'
    },
    mandatoryParameters=[
        {
            'name': 'string',
            'value': {
                'S': 'string',
                'B': True|False,
                'I': 123,
                'L': 123,
                'D': 123.0,
                'BIN': b'bytes',
                'UL': 'string'
            },
            'defaultValue': {
                'S': 'string',
                'B': True|False,
                'I': 123,
                'L': 123,
                'D': 123.0,
                'BIN': b'bytes',
                'UL': 'string'
            },
            'description': 'string'
        },
    ],
    roleArn='string',
    tags=[
        {
            'Key': 'string',
            'Value': 'string'
        },
    ]
)

type commandId:

string

param commandId:

[REQUIRED]

A unique identifier for the command. We recommend using UUID. Alpha-numeric characters, hyphens, and underscores are valid for use here.

type namespace:

string

param namespace:

The namespace of the command. The MQTT reserved topics and validations will be used for command executions according to the namespace setting.

type displayName:

string

param displayName:

The user-friendly name in the console for the command. This name doesn't have to be unique. You can update the user-friendly name after you define it.

type description:

string

param description:

A short text decription of the command.

type payload:

dict

param payload:

The payload object for the command. You must specify this information when using the AWS-IoT namespace.

You can upload a static payload file from your local storage that contains the instructions for the device to process. The payload file can use any format. To make sure that the device correctly interprets the payload, we recommend you to specify the payload content type.

content (bytes) --

The static payload file for the command.
contentType (string) --

The content type that specifies the format type of the payload file. This field must use a type/subtype format, such as application/json. For information about various content types, see Common MIME types.

type mandatoryParameters:

list

param mandatoryParameters:

A list of parameters that are required by the StartCommandExecution API. These parameters need to be specified only when using the AWS-IoT-FleetWise namespace. You can either specify them here or when running the command using the StartCommandExecution API.

(dict) --

A map of key-value pairs that describe the command.
- name (string) -- [REQUIRED]
  
  The name of a specific parameter used in a command and command execution.
- value (dict) --
  
  The value used to describe the command. When you assign a value to a parameter, it will override any default value that you had already specified.
  - S (string) --
    
    An attribute of type String. For example:
    
    "S": "Hello"
  - B (boolean) --
    
    An attribute of type Boolean. For example:
    
    "BOOL": true
  - I (integer) --
    
    An attribute of type Integer (Thirty-Two Bits).
  - L (integer) --
    
    An attribute of type Long.
  - D (float) --
    
    An attribute of type Double (Sixty-Four Bits).
  - BIN (bytes) --
    
    An attribute of type Binary. For example:
    
    "B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"
  - UL (string) --
    
    An attribute of type unsigned long.
- defaultValue (dict) --
  
  The default value used to describe the command. This is the value assumed by the parameter if no other value is assigned to it.
  - S (string) --
    
    An attribute of type String. For example:
    
    "S": "Hello"
  - B (boolean) --
    
    An attribute of type Boolean. For example:
    
    "BOOL": true
  - I (integer) --
    
    An attribute of type Integer (Thirty-Two Bits).
  - L (integer) --
    
    An attribute of type Long.
  - D (float) --
    
    An attribute of type Double (Sixty-Four Bits).
  - BIN (bytes) --
    
    An attribute of type Binary. For example:
    
    "B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"
  - UL (string) --
    
    An attribute of type unsigned long.
- description (string) --
  
  The description of the command parameter.

type roleArn:

string

param roleArn:

The IAM role that allows access to create the command.

type tags:

list

param tags:

Name-value pairs that are used as metadata to manage a command.

(dict) --

A set of key/value pairs that are used to manage the resource.
- Key (string) -- [REQUIRED]
  
  The tag's key.
- Value (string) --
  
  The tag's value.

rtype:

dict

returns:

Response Syntax

{
    'commandId': 'string',
    'commandArn': 'string'
}

Response Structure

(dict) --
- commandId (string) --
  
  The unique identifier for the command.
- commandArn (string) --
  
  The Amazon Resource Number (ARN) of the command. For example, arn:aws:iot:<region>:<accountid>:command/<commandId>

GetCommand (new)

Link ¶

Gets information about the specified command.

See also: AWS API Documentation

Request Syntax

client.get_command(
    commandId='string'
)

type commandId:

string

param commandId:

[REQUIRED]

The unique identifier of the command for which you want to retrieve information.

rtype:

dict

returns:

Response Syntax

{
    'commandId': 'string',
    'commandArn': 'string',
    'namespace': 'AWS-IoT'|'AWS-IoT-FleetWise',
    'displayName': 'string',
    'description': 'string',
    'mandatoryParameters': [
        {
            'name': 'string',
            'value': {
                'S': 'string',
                'B': True|False,
                'I': 123,
                'L': 123,
                'D': 123.0,
                'BIN': b'bytes',
                'UL': 'string'
            },
            'defaultValue': {
                'S': 'string',
                'B': True|False,
                'I': 123,
                'L': 123,
                'D': 123.0,
                'BIN': b'bytes',
                'UL': 'string'
            },
            'description': 'string'
        },
    ],
    'payload': {
        'content': b'bytes',
        'contentType': 'string'
    },
    'roleArn': 'string',
    'createdAt': datetime(2015, 1, 1),
    'lastUpdatedAt': datetime(2015, 1, 1),
    'deprecated': True|False,
    'pendingDeletion': True|False
}

Response Structure

(dict) --
- commandId (string) --
  
  The unique identifier of the command.
- commandArn (string) --
  
  The Amazon Resource Number (ARN) of the command. For example, arn:aws:iot:<region>:<accountid>:command/<commandId>
- namespace (string) --
  
  The namespace of the command.
- displayName (string) --
  
  The user-friendly name in the console for the command.
- description (string) --
  
  A short text description of the command.
- mandatoryParameters (list) --
  
  A list of parameters for the command created.
  - (dict) --
    
    A map of key-value pairs that describe the command.
    - name (string) --
      
      The name of a specific parameter used in a command and command execution.
    - value (dict) --
      
      The value used to describe the command. When you assign a value to a parameter, it will override any default value that you had already specified.
      - S (string) --
        
        An attribute of type String. For example:
        
        "S": "Hello"
      - B (boolean) --
        
        An attribute of type Boolean. For example:
        
        "BOOL": true
      - I (integer) --
        
        An attribute of type Integer (Thirty-Two Bits).
      - L (integer) --
        
        An attribute of type Long.
      - D (float) --
        
        An attribute of type Double (Sixty-Four Bits).
      - BIN (bytes) --
        
        An attribute of type Binary. For example:
        
        "B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"
      - UL (string) --
        
        An attribute of type unsigned long.
    - defaultValue (dict) --
      
      The default value used to describe the command. This is the value assumed by the parameter if no other value is assigned to it.
      - S (string) --
        
        An attribute of type String. For example:
        
        "S": "Hello"
      - B (boolean) --
        
        An attribute of type Boolean. For example:
        
        "BOOL": true
      - I (integer) --
        
        An attribute of type Integer (Thirty-Two Bits).
      - L (integer) --
        
        An attribute of type Long.
      - D (float) --
        
        An attribute of type Double (Sixty-Four Bits).
      - BIN (bytes) --
        
        An attribute of type Binary. For example:
        
        "B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"
      - UL (string) --
        
        An attribute of type unsigned long.
    - description (string) --
      
      The description of the command parameter.
- payload (dict) --
  
  The payload object that you provided for the command.
  - content (bytes) --
    
    The static payload file for the command.
  - contentType (string) --
    
    The content type that specifies the format type of the payload file. This field must use a type/subtype format, such as application/json. For information about various content types, see Common MIME types.
- roleArn (string) --
  
  The IAM role that allows access to retrieve information about the command.
- createdAt (datetime) --
  
  The timestamp, when the command was created.
- lastUpdatedAt (datetime) --
  
  The timestamp, when the command was last updated.
- deprecated (boolean) --
  
  Indicates whether the command has been deprecated.
- pendingDeletion (boolean) --
  
  Indicates whether the command is being deleted.

DeleteCommandExecution (new)

Link ¶

Delete a command execution.

See also: AWS API Documentation

Request Syntax

client.delete_command_execution(
    executionId='string',
    targetArn='string'
)

type executionId:

string

param executionId:

[REQUIRED]

The unique identifier of the command execution that you want to delete from your account.

type targetArn:

string

param targetArn:

[REQUIRED]

The Amazon Resource Number (ARN) of the target device for which you want to delete command executions.

rtype:

dict

returns:

Response Syntax

{}

Response Structure

(dict) --

ListCommandExecutions (new)

Link ¶

List all command executions.

See also: AWS API Documentation

Request Syntax

client.list_command_executions(
    maxResults=123,
    nextToken='string',
    namespace='AWS-IoT'|'AWS-IoT-FleetWise',
    status='CREATED'|'IN_PROGRESS'|'SUCCEEDED'|'FAILED'|'REJECTED'|'TIMED_OUT',
    sortOrder='ASCENDING'|'DESCENDING',
    startedTimeFilter={
        'after': 'string',
        'before': 'string'
    },
    completedTimeFilter={
        'after': 'string',
        'before': 'string'
    },
    targetArn='string',
    commandArn='string'
)

type maxResults:

integer

param maxResults:

The maximum number of results to return in this operation.

type nextToken:

string

param nextToken:

To retrieve the next set of results, the nextToken value from a previous response; otherwise null to receive the first set of results.

type namespace:

string

param namespace:

The namespace of the command.

type status:

string

param status:

List all command executions for the device that have a particular status. For example, you can filter the list to display only command executions that have failed or timed out.

type sortOrder:

string

param sortOrder:

Specify whether to list the command executions that were created in the ascending or descending order. By default, the API returns all commands in the descending order based on the start time or completion time of the executions, that are determined by the startTimeFilter and completeTimeFilter parameters.

type startedTimeFilter:

dict

param startedTimeFilter:

List all command executions that started any time before or after the date and time that you specify. The date and time uses the format yyyy-MM-dd'T'HH:mm.

after (string) --

Filter to display command executions that started or completed only after a particular date and time.
before (string) --

Filter to display command executions that started or completed only before a particular date and time.

type completedTimeFilter:

dict

param completedTimeFilter:

List all command executions that completed any time before or after the date and time that you specify. The date and time uses the format yyyy-MM-dd'T'HH:mm.

after (string) --

Filter to display command executions that started or completed only after a particular date and time.
before (string) --

Filter to display command executions that started or completed only before a particular date and time.

type targetArn:

string

param targetArn:

The Amazon Resource Number (ARN) of the target device. You can use this information to list all command executions for a particular device.

type commandArn:

string

param commandArn:

The Amazon Resource Number (ARN) of the command. You can use this information to list all command executions for a particular command.

rtype:

dict

returns:

Response Syntax

{
    'commandExecutions': [
        {
            'commandArn': 'string',
            'executionId': 'string',
            'targetArn': 'string',
            'status': 'CREATED'|'IN_PROGRESS'|'SUCCEEDED'|'FAILED'|'REJECTED'|'TIMED_OUT',
            'createdAt': datetime(2015, 1, 1),
            'startedAt': datetime(2015, 1, 1),
            'completedAt': datetime(2015, 1, 1)
        },
    ],
    'nextToken': 'string'
}

Response Structure

(dict) --
- commandExecutions (list) --
  
  The list of command executions.
  - (dict) --
    
    Summary information about a particular command execution.
    - commandArn (string) --
      
      The Amazon Resource Name (ARN) of the command execution.
    - executionId (string) --
      
      The unique identifier of the command execution.
    - targetArn (string) --
      
      The Amazon Resource Name (ARN) of the target device for which the command is being executed.
    - status (string) --
      
      The status of the command executions.
    - createdAt (datetime) --
      
      The date and time at which the command execution was created for the target device.
    - startedAt (datetime) --
      
      The date and time at which the command started executing on the target device.
    - completedAt (datetime) --
      
      The date and time at which the command completed executing on the target device.
- nextToken (string) --
  
  The token to use to get the next set of results, or null if there are no additional results.