IoT1ClickDevicesService

Client

class IoT1ClickDevicesService.Client

A low-level client representing AWS IoT 1-Click Devices Service

Describes all of the AWS IoT 1-Click device-related API operations for the service. Also provides sample requests, responses, and errors for the supported web services protocols.

client = session.create_client('iot1click-devices')

These are the available methods:

can_paginate(operation_name)

Check if an operation can be paginated.

Parameters:

operation_name (string) – The operation name. This is the same name as the method name on the client. For example, if the method name is create_foo, and you’d normally invoke the operation as client.create_foo(**kwargs), if the create_foo operation can be paginated, you can use the call client.get_paginator("create_foo").

Returns:

True if the operation can be paginated, False otherwise.

claim_devices_by_claim_code(**kwargs)

Adds device(s) to your account (i.e., claim one or more devices) if and only if you received a claim code with the device(s).

See also: AWS API Documentation

Request Syntax

response = client.claim_devices_by_claim_code(
    ClaimCode='string'
)
Parameters:

ClaimCode (string) –

[REQUIRED]

The claim code, starting with “C-”, as provided by the device manufacturer.

Return type:

dict

Returns:

Response Syntax

{
    'ClaimCode': 'string',
    'Total': 123
}

Response Structure

  • (dict) –

    200 response

    • ClaimCode (string) –

      The claim code provided by the device manufacturer.

    • Total (integer) –

      The total number of devices associated with the claim code that has been processed in the claim request.

Exceptions

close()

Closes underlying endpoint connections.

describe_device(**kwargs)

Given a device ID, returns a DescribeDeviceResponse object describing the details of the device.

See also: AWS API Documentation

Request Syntax

response = client.describe_device(
    DeviceId='string'
)
Parameters:

DeviceId (string) –

[REQUIRED]

The unique identifier of the device.

Return type:

dict

Returns:

Response Syntax

{
    'DeviceDescription': {
        'Arn': 'string',
        'Attributes': {
            'string': 'string'
        },
        'DeviceId': 'string',
        'Enabled': True|False,
        'RemainingLife': 123.0,
        'Type': 'string',
        'Tags': {
            'string': 'string'
        }
    }
}

Response Structure

  • (dict) –

    200 response

    • DeviceDescription (dict) –

      Device details.

      • Arn (string) –

        The ARN of the device.

      • Attributes (dict) –

        An array of zero or more elements of DeviceAttribute objects providing user specified device attributes.

        • (string) –

          • (string) –

      • DeviceId (string) –

        The unique identifier of the device.

      • Enabled (boolean) –

        A Boolean value indicating whether or not the device is enabled.

      • RemainingLife (float) –

        A value between 0 and 1 inclusive, representing the fraction of life remaining for the device.

      • Type (string) –

        The type of the device, such as “button”.

      • Tags (dict) –

        The tags currently associated with the AWS IoT 1-Click device.

        • (string) –

          • (string) –

Exceptions

finalize_device_claim(**kwargs)

Given a device ID, finalizes the claim request for the associated device.

Note

Claiming a device consists of initiating a claim, then publishing a device event, and finalizing the claim. For a device of type button, a device event can be published by simply clicking the device.

See also: AWS API Documentation

Request Syntax

response = client.finalize_device_claim(
    DeviceId='string',
    Tags={
        'string': 'string'
    }
)
Parameters:
  • DeviceId (string) –

    [REQUIRED]

    The unique identifier of the device.

  • Tags (dict) –

    A collection of key/value pairs defining the resource tags. For example, { “tags”: {“key1”: “value1”, “key2”: “value2”} }. For more information, see AWS Tagging Strategies .

    • (string) –

      • (string) –

Return type:

dict

Returns:

Response Syntax

{
    'State': 'string'
}

Response Structure

  • (dict) –

    200 response

    • State (string) –

      The device’s final claim state.

Exceptions

get_device_methods(**kwargs)

Given a device ID, returns the invokable methods associated with the device.

See also: AWS API Documentation

Request Syntax

response = client.get_device_methods(
    DeviceId='string'
)
Parameters:

DeviceId (string) –

[REQUIRED]

The unique identifier of the device.

Return type:

dict

Returns:

Response Syntax

{
    'DeviceMethods': [
        {
            'DeviceType': 'string',
            'MethodName': 'string'
        },
    ]
}

Response Structure

  • (dict) –

    200 response

    • DeviceMethods (list) –

      List of available device APIs.

      • (dict) –

        • DeviceType (string) –

          The type of the device, such as “button”.

        • MethodName (string) –

          The name of the method applicable to the deviceType.

Exceptions

get_paginator(operation_name)

Create a paginator for an operation.

Parameters:

operation_name (string) – The operation name. This is the same name as the method name on the client. For example, if the method name is create_foo, and you’d normally invoke the operation as client.create_foo(**kwargs), if the create_foo operation can be paginated, you can use the call client.get_paginator("create_foo").

Raises:

OperationNotPageableError – Raised if the operation is not pageable. You can use the client.can_paginate method to check if an operation is pageable.

Return type:

L{botocore.paginate.Paginator}

Returns:

A paginator object.

get_waiter(waiter_name)

Returns an object that can wait for some condition.

Parameters:

waiter_name (str) – The name of the waiter to get. See the waiters section of the service docs for a list of available waiters.

Returns:

The specified waiter object.

Return type:

botocore.waiter.Waiter

initiate_device_claim(**kwargs)

Given a device ID, initiates a claim request for the associated device.

Note

Claiming a device consists of initiating a claim, then publishing a device event, and finalizing the claim. For a device of type button, a device event can be published by simply clicking the device.

See also: AWS API Documentation

Request Syntax

response = client.initiate_device_claim(
    DeviceId='string'
)
Parameters:

DeviceId (string) –

[REQUIRED]

The unique identifier of the device.

Return type:

dict

Returns:

Response Syntax

{
    'State': 'string'
}

Response Structure

  • (dict) –

    200 response

    • State (string) –

      The device’s final claim state.

Exceptions

invoke_device_method(**kwargs)

Given a device ID, issues a request to invoke a named device method (with possible parameters). See the “Example POST” code snippet below.

See also: AWS API Documentation

Request Syntax

response = client.invoke_device_method(
    DeviceId='string',
    DeviceMethod={
        'DeviceType': 'string',
        'MethodName': 'string'
    },
    DeviceMethodParameters='string'
)
Parameters:
  • DeviceId (string) –

    [REQUIRED]

    The unique identifier of the device.

  • DeviceMethod (dict) –

    The device method to invoke.

    • DeviceType (string) –

      The type of the device, such as “button”.

    • MethodName (string) –

      The name of the method applicable to the deviceType.

  • DeviceMethodParameters (string) – A JSON encoded string containing the device method request parameters.

Return type:

dict

Returns:

Response Syntax

{
    'DeviceMethodResponse': 'string'
}

Response Structure

  • (dict) –

    200 response

    • DeviceMethodResponse (string) –

      A JSON encoded string containing the device method response.

Exceptions

list_device_events(**kwargs)

Using a device ID, returns a DeviceEventsResponse object containing an array of events for the device.

See also: AWS API Documentation

Request Syntax

response = client.list_device_events(
    DeviceId='string',
    FromTimeStamp=datetime(2015, 1, 1),
    MaxResults=123,
    NextToken='string',
    ToTimeStamp=datetime(2015, 1, 1)
)
Parameters:
  • DeviceId (string) –

    [REQUIRED]

    The unique identifier of the device.

  • FromTimeStamp (datetime) –

    [REQUIRED]

    The start date for the device event query, in ISO8061 format. For example, 2018-03-28T15:45:12.880Z

  • MaxResults (integer) – The maximum number of results to return per request. If not set, a default value of 100 is used.

  • NextToken (string) – The token to retrieve the next set of results.

  • ToTimeStamp (datetime) –

    [REQUIRED]

    The end date for the device event query, in ISO8061 format. For example, 2018-03-28T15:45:12.880Z

Return type:

dict

Returns:

Response Syntax

{
    'Events': [
        {
            'Device': {
                'Attributes': {},
                'DeviceId': 'string',
                'Type': 'string'
            },
            'StdEvent': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) –

    200 response

    • Events (list) –

      An array of zero or more elements describing the event(s) associated with the device.

      • (dict) –

        • Device (dict) –

          An object representing the device associated with the event.

          • Attributes (dict) –

            The user specified attributes associated with the device for an event.

          • DeviceId (string) –

            The unique identifier of the device.

          • Type (string) –

            The device type, such as “button”.

        • StdEvent (string) –

          A serialized JSON object representing the device-type specific event.

    • NextToken (string) –

      The token to retrieve the next set of results.

Exceptions

list_devices(**kwargs)

Lists the 1-Click compatible devices associated with your AWS account.

See also: AWS API Documentation

Request Syntax

response = client.list_devices(
    DeviceType='string',
    MaxResults=123,
    NextToken='string'
)
Parameters:
  • DeviceType (string) – The type of the device, such as “button”.

  • MaxResults (integer) – The maximum number of results to return per request. If not set, a default value of 100 is used.

  • NextToken (string) – The token to retrieve the next set of results.

Return type:

dict

Returns:

Response Syntax

{
    'Devices': [
        {
            'Arn': 'string',
            'Attributes': {
                'string': 'string'
            },
            'DeviceId': 'string',
            'Enabled': True|False,
            'RemainingLife': 123.0,
            'Type': 'string',
            'Tags': {
                'string': 'string'
            }
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) –

    200 response

    • Devices (list) –

      A list of devices.

      • (dict) –

        • Arn (string) –

          The ARN of the device.

        • Attributes (dict) –

          An array of zero or more elements of DeviceAttribute objects providing user specified device attributes.

          • (string) –

            • (string) –

        • DeviceId (string) –

          The unique identifier of the device.

        • Enabled (boolean) –

          A Boolean value indicating whether or not the device is enabled.

        • RemainingLife (float) –

          A value between 0 and 1 inclusive, representing the fraction of life remaining for the device.

        • Type (string) –

          The type of the device, such as “button”.

        • Tags (dict) –

          The tags currently associated with the AWS IoT 1-Click device.

          • (string) –

            • (string) –

    • NextToken (string) –

      The token to retrieve the next set of results.

Exceptions

list_tags_for_resource(**kwargs)

Lists the tags associated with the specified resource ARN.

See also: AWS API Documentation

Request Syntax

response = client.list_tags_for_resource(
    ResourceArn='string'
)
Parameters:

ResourceArn (string) –

[REQUIRED]

The ARN of the resource.

Return type:

dict

Returns:

Response Syntax

{
    'Tags': {
        'string': 'string'
    }
}

Response Structure

  • (dict) –

    • Tags (dict) –

      A collection of key/value pairs defining the resource tags. For example, { “tags”: {“key1”: “value1”, “key2”: “value2”} }. For more information, see AWS Tagging Strategies .

      • (string) –

        • (string) –

Exceptions

tag_resource(**kwargs)

Adds or updates the tags associated with the resource ARN. See AWS IoT 1-Click Service Limits for the maximum number of tags allowed per resource.

See also: AWS API Documentation

Request Syntax

response = client.tag_resource(
    ResourceArn='string',
    Tags={
        'string': 'string'
    }
)
Parameters:
  • ResourceArn (string) –

    [REQUIRED]

    The ARN of the resource.

  • Tags (dict) –

    [REQUIRED]

    A collection of key/value pairs defining the resource tags. For example, { “tags”: {“key1”: “value1”, “key2”: “value2”} }. For more information, see AWS Tagging Strategies .

    • (string) –

      • (string) –

Returns:

None

Exceptions

unclaim_device(**kwargs)

Disassociates a device from your AWS account using its device ID.

See also: AWS API Documentation

Request Syntax

response = client.unclaim_device(
    DeviceId='string'
)
Parameters:

DeviceId (string) –

[REQUIRED]

The unique identifier of the device.

Return type:

dict

Returns:

Response Syntax

{
    'State': 'string'
}

Response Structure

  • (dict) –

    200 response

    • State (string) –

      The device’s final claim state.

Exceptions

untag_resource(**kwargs)

Using tag keys, deletes the tags (key/value pairs) associated with the specified resource ARN.

See also: AWS API Documentation

Request Syntax

response = client.untag_resource(
    ResourceArn='string',
    TagKeys=[
        'string',
    ]
)
Parameters:
  • ResourceArn (string) –

    [REQUIRED]

    The ARN of the resource.

  • TagKeys (list) –

    [REQUIRED]

    A collections of tag keys. For example, {“key1”,”key2”}

    • (string) –

Returns:

None

Exceptions

update_device_state(**kwargs)

Using a Boolean value (true or false), this operation enables or disables the device given a device ID.

See also: AWS API Documentation

Request Syntax

response = client.update_device_state(
    DeviceId='string',
    Enabled=True|False
)
Parameters:
  • DeviceId (string) –

    [REQUIRED]

    The unique identifier of the device.

  • Enabled (boolean) – If true, the device is enabled. If false, the device is disabled.

Return type:

dict

Returns:

Response Syntax

{}

Response Structure

  • (dict) –

    200 response

Exceptions

Client Exceptions

Client exceptions are available on a client instance via the exceptions property. For more detailed instructions and examples on the exact usage of client exceptions, see the error handling user guide.

The available client exceptions are:

class IoT1ClickDevicesService.Client.exceptions.ForbiddenException

Example

try:
  ...
except client.exceptions.ForbiddenException as e:
  print(e.response)
response

The parsed error response. All exceptions have a top level Error key that provides normalized access to common exception atrributes. All other keys are specific to this service or exception class.

Syntax

{
    'Code': 'string',
    'Message': 'string',
    'Error': {
        'Code': 'string',
        'Message': 'string'
    }
}

Structure

  • (dict) –

    • Code (string) –

      403

    • Message (string) –

      The 403 error message returned by the web server.

    • Error (dict) – Normalized access to common exception attributes.

      • Code (string) – An identifier specifying the exception type.

      • Message (string) – A descriptive message explaining why the exception occured.

class IoT1ClickDevicesService.Client.exceptions.InternalFailureException

Example

try:
  ...
except client.exceptions.InternalFailureException as e:
  print(e.response)
response

The parsed error response. All exceptions have a top level Error key that provides normalized access to common exception atrributes. All other keys are specific to this service or exception class.

Syntax

{
    'Code': 'string',
    'Message': 'string',
    'Error': {
        'Code': 'string',
        'Message': 'string'
    }
}

Structure

  • (dict) –

    • Code (string) –

      500

    • Message (string) –

      The 500 error message returned by the web server.

    • Error (dict) – Normalized access to common exception attributes.

      • Code (string) – An identifier specifying the exception type.

      • Message (string) – A descriptive message explaining why the exception occured.

class IoT1ClickDevicesService.Client.exceptions.InvalidRequestException

Example

try:
  ...
except client.exceptions.InvalidRequestException as e:
  print(e.response)
response

The parsed error response. All exceptions have a top level Error key that provides normalized access to common exception atrributes. All other keys are specific to this service or exception class.

Syntax

{
    'Code': 'string',
    'Message': 'string',
    'Error': {
        'Code': 'string',
        'Message': 'string'
    }
}

Structure

  • (dict) –

    • Code (string) –

      400

    • Message (string) –

      The 400 error message returned by the web server.

    • Error (dict) – Normalized access to common exception attributes.

      • Code (string) – An identifier specifying the exception type.

      • Message (string) – A descriptive message explaining why the exception occured.

class IoT1ClickDevicesService.Client.exceptions.PreconditionFailedException

Example

try:
  ...
except client.exceptions.PreconditionFailedException as e:
  print(e.response)
response

The parsed error response. All exceptions have a top level Error key that provides normalized access to common exception atrributes. All other keys are specific to this service or exception class.

Syntax

{
    'Code': 'string',
    'Message': 'string',
    'Error': {
        'Code': 'string',
        'Message': 'string'
    }
}

Structure

  • (dict) –

    • Code (string) –

      412

    • Message (string) –

      An error message explaining the error or its remedy.

    • Error (dict) – Normalized access to common exception attributes.

      • Code (string) – An identifier specifying the exception type.

      • Message (string) – A descriptive message explaining why the exception occured.

class IoT1ClickDevicesService.Client.exceptions.RangeNotSatisfiableException

Example

try:
  ...
except client.exceptions.RangeNotSatisfiableException as e:
  print(e.response)
response

The parsed error response. All exceptions have a top level Error key that provides normalized access to common exception atrributes. All other keys are specific to this service or exception class.

Syntax

{
    'Code': 'string',
    'Message': 'string',
    'Error': {
        'Code': 'string',
        'Message': 'string'
    }
}

Structure

  • (dict) –

    • Code (string) –

      416

    • Message (string) –

      The requested number of results specified by nextToken cannot be satisfied.

    • Error (dict) – Normalized access to common exception attributes.

      • Code (string) – An identifier specifying the exception type.

      • Message (string) – A descriptive message explaining why the exception occured.

class IoT1ClickDevicesService.Client.exceptions.ResourceConflictException

Example

try:
  ...
except client.exceptions.ResourceConflictException as e:
  print(e.response)
response

The parsed error response. All exceptions have a top level Error key that provides normalized access to common exception atrributes. All other keys are specific to this service or exception class.

Syntax

{
    'Code': 'string',
    'Message': 'string',
    'Error': {
        'Code': 'string',
        'Message': 'string'
    }
}

Structure

  • (dict) –

    • Code (string) –

      409

    • Message (string) –

      An error message explaining the error or its remedy.

    • Error (dict) – Normalized access to common exception attributes.

      • Code (string) – An identifier specifying the exception type.

      • Message (string) – A descriptive message explaining why the exception occured.

class IoT1ClickDevicesService.Client.exceptions.ResourceNotFoundException

Example

try:
  ...
except client.exceptions.ResourceNotFoundException as e:
  print(e.response)
response

The parsed error response. All exceptions have a top level Error key that provides normalized access to common exception atrributes. All other keys are specific to this service or exception class.

Syntax

{
    'Code': 'string',
    'Message': 'string',
    'Error': {
        'Code': 'string',
        'Message': 'string'
    }
}

Structure

  • (dict) –

    • Code (string) –

      404

    • Message (string) –

      The requested device could not be found.

    • Error (dict) – Normalized access to common exception attributes.

      • Code (string) – An identifier specifying the exception type.

      • Message (string) – A descriptive message explaining why the exception occured.

Paginators

The available paginators are:

class IoT1ClickDevicesService.Paginator.ListDeviceEvents
paginator = client.get_paginator('list_device_events')
paginate(**kwargs)

Creates an iterator that will paginate through responses from IoT1ClickDevicesService.Client.list_device_events().

See also: AWS API Documentation

Request Syntax

response_iterator = paginator.paginate(
    DeviceId='string',
    FromTimeStamp=datetime(2015, 1, 1),
    ToTimeStamp=datetime(2015, 1, 1),
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters:
  • DeviceId (string) –

    [REQUIRED]

    The unique identifier of the device.

  • FromTimeStamp (datetime) –

    [REQUIRED]

    The start date for the device event query, in ISO8061 format. For example, 2018-03-28T15:45:12.880Z

  • ToTimeStamp (datetime) –

    [REQUIRED]

    The end date for the device event query, in ISO8061 format. For example, 2018-03-28T15:45:12.880Z

  • PaginationConfig (dict) –

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) –

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) –

      The size of each page.

    • StartingToken (string) –

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type:

dict

Returns:

Response Syntax

{
    'Events': [
        {
            'Device': {
                'Attributes': {},
                'DeviceId': 'string',
                'Type': 'string'
            },
            'StdEvent': 'string'
        },
    ],

}

Response Structure

  • (dict) –

    200 response

    • Events (list) –

      An array of zero or more elements describing the event(s) associated with the device.

      • (dict) –

        • Device (dict) –

          An object representing the device associated with the event.

          • Attributes (dict) –

            The user specified attributes associated with the device for an event.

          • DeviceId (string) –

            The unique identifier of the device.

          • Type (string) –

            The device type, such as “button”.

        • StdEvent (string) –

          A serialized JSON object representing the device-type specific event.

class IoT1ClickDevicesService.Paginator.ListDevices
paginator = client.get_paginator('list_devices')
paginate(**kwargs)

Creates an iterator that will paginate through responses from IoT1ClickDevicesService.Client.list_devices().

See also: AWS API Documentation

Request Syntax

response_iterator = paginator.paginate(
    DeviceType='string',
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters:
  • DeviceType (string) – The type of the device, such as “button”.

  • PaginationConfig (dict) –

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) –

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) –

      The size of each page.

    • StartingToken (string) –

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type:

dict

Returns:

Response Syntax

{
    'Devices': [
        {
            'Arn': 'string',
            'Attributes': {
                'string': 'string'
            },
            'DeviceId': 'string',
            'Enabled': True|False,
            'RemainingLife': 123.0,
            'Type': 'string',
            'Tags': {
                'string': 'string'
            }
        },
    ],

}

Response Structure

  • (dict) –

    200 response

    • Devices (list) –

      A list of devices.

      • (dict) –

        • Arn (string) –

          The ARN of the device.

        • Attributes (dict) –

          An array of zero or more elements of DeviceAttribute objects providing user specified device attributes.

          • (string) –

            • (string) –

        • DeviceId (string) –

          The unique identifier of the device.

        • Enabled (boolean) –

          A Boolean value indicating whether or not the device is enabled.

        • RemainingLife (float) –

          A value between 0 and 1 inclusive, representing the fraction of life remaining for the device.

        • Type (string) –

          The type of the device, such as “button”.

        • Tags (dict) –

          The tags currently associated with the AWS IoT 1-Click device.

          • (string) –

            • (string) –