IoTDataPlane

Client

class IoTDataPlane.Client

A low-level client representing AWS IoT Data Plane

AWS IoT-Data enables secure, bi-directional communication between Internet-connected things (such as sensors, actuators, embedded devices, or smart appliances) and the AWS cloud. It implements a broker for applications and things to publish messages over HTTP (Publish) and retrieve, update, and delete shadows. A shadow is a persistent representation of your things and their state in the AWS cloud.

Find the endpoint address for actions in the AWS IoT data plane by running this CLI command:

aws iot describe-endpoint --endpoint-type iot:Data-ATS

The service name used by AWS Signature Version 4 to sign requests is: iotdevicegateway .

client = session.create_client('iot-data')

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.
delete_thing_shadow(**kwargs)

Deletes the shadow for the specified thing.

For more information, see DeleteThingShadow in the AWS IoT Developer Guide.

See also: AWS API Documentation

Request Syntax

response = client.delete_thing_shadow(
    thingName='string',
    shadowName='string'
)
Parameters
  • thingName (string) --

    [REQUIRED]

    The name of the thing.

  • shadowName (string) -- The name of the shadow.
Return type

dict

Returns

Response Syntax

{
    'payload': StreamingBody()
}

Response Structure

  • (dict) --

    The output from the DeleteThingShadow operation.

    • payload (StreamingBody) --

      The state information, in JSON format.

Exceptions

generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)

Generate a presigned url given a client, its method, and arguments

Parameters
  • ClientMethod (string) -- The client method to presign for
  • Params (dict) -- The parameters normally passed to ClientMethod.
  • ExpiresIn (int) -- The number of seconds the presigned url is valid for. By default it expires in an hour (3600 seconds)
  • HttpMethod (string) -- The http method to use on the generated url. By default, the http method is whatever is used in the method's model.
Returns

The presigned url

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_thing_shadow(**kwargs)

Gets the shadow for the specified thing.

For more information, see GetThingShadow in the AWS IoT Developer Guide.

See also: AWS API Documentation

Request Syntax

response = client.get_thing_shadow(
    thingName='string',
    shadowName='string'
)
Parameters
  • thingName (string) --

    [REQUIRED]

    The name of the thing.

  • shadowName (string) -- The name of the shadow.
Return type

dict

Returns

Response Syntax

{
    'payload': StreamingBody()
}

Response Structure

  • (dict) --

    The output from the GetThingShadow operation.

    • payload (StreamingBody) --

      The state information, in JSON format.

Exceptions

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
list_named_shadows_for_thing(**kwargs)

Lists the shadows for the specified thing.

See also: AWS API Documentation

Request Syntax

response = client.list_named_shadows_for_thing(
    thingName='string',
    nextToken='string',
    pageSize=123
)
Parameters
  • thingName (string) --

    [REQUIRED]

    The name of the thing.

  • nextToken (string) -- The token to retrieve the next set of results.
  • pageSize (integer) -- The result page size.
Return type

dict

Returns

Response Syntax

{
    'results': [
        'string',
    ],
    'nextToken': 'string',
    'timestamp': 123
}

Response Structure

  • (dict) --

    • results (list) --

      The list of shadows for the specified thing.

      • (string) --
    • nextToken (string) --

      The token for the next set of results, or null if there are no additional results.

    • timestamp (integer) --

      The Epoch date and time the response was generated by AWS IoT.

Exceptions

publish(**kwargs)

Publishes state information.

For more information, see HTTP Protocol in the AWS IoT Developer Guide.

See also: AWS API Documentation

Request Syntax

response = client.publish(
    topic='string',
    qos=123,
    payload=b'bytes'|file
)
Parameters
  • topic (string) --

    [REQUIRED]

    The name of the MQTT topic.

  • qos (integer) -- The Quality of Service (QoS) level.
  • payload (bytes or seekable file-like object) -- The state information, in JSON format.
Returns

None

Exceptions

update_thing_shadow(**kwargs)

Updates the shadow for the specified thing.

For more information, see UpdateThingShadow in the AWS IoT Developer Guide.

See also: AWS API Documentation

Request Syntax

response = client.update_thing_shadow(
    thingName='string',
    shadowName='string',
    payload=b'bytes'|file
)
Parameters
  • thingName (string) --

    [REQUIRED]

    The name of the thing.

  • shadowName (string) -- The name of the shadow.
  • payload (bytes or seekable file-like object) --

    [REQUIRED]

    The state information, in JSON format.

Return type

dict

Returns

Response Syntax

{
    'payload': StreamingBody()
}

Response Structure

  • (dict) --

    The output from the UpdateThingShadow operation.

    • payload (StreamingBody) --

      The state information, in JSON format.

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 IoTDataPlane.Client.exceptions.ConflictException

The specified version does not match the version of the document.

Example

try:
  ...
except client.exceptions.ConflictException 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

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

Structure

  • (dict) --

    The specified version does not match the version of the document.

    • message (string) --

      The message for the exception.

    • 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 IoTDataPlane.Client.exceptions.InternalFailureException

An unexpected error has occurred.

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

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

Structure

  • (dict) --

    An unexpected error has occurred.

    • message (string) --

      The message for the exception.

    • 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 IoTDataPlane.Client.exceptions.InvalidRequestException

The request is not valid.

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

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

Structure

  • (dict) --

    The request is not valid.

    • message (string) --

      The message for the exception.

    • 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 IoTDataPlane.Client.exceptions.MethodNotAllowedException

The specified combination of HTTP verb and URI is not supported.

Example

try:
  ...
except client.exceptions.MethodNotAllowedException 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

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

Structure

  • (dict) --

    The specified combination of HTTP verb and URI is not supported.

    • message (string) --

      The message for the exception.

    • 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 IoTDataPlane.Client.exceptions.RequestEntityTooLargeException

The payload exceeds the maximum size allowed.

Example

try:
  ...
except client.exceptions.RequestEntityTooLargeException 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

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

Structure

  • (dict) --

    The payload exceeds the maximum size allowed.

    • message (string) --

      The message for the exception.

    • 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 IoTDataPlane.Client.exceptions.ResourceNotFoundException

The specified resource does not exist.

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

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

Structure

  • (dict) --

    The specified resource does not exist.

    • message (string) --

      The message for the exception.

    • 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 IoTDataPlane.Client.exceptions.ServiceUnavailableException

The service is temporarily unavailable.

Example

try:
  ...
except client.exceptions.ServiceUnavailableException 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

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

Structure

  • (dict) --

    The service is temporarily unavailable.

    • message (string) --

      The message for the exception.

    • 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 IoTDataPlane.Client.exceptions.ThrottlingException

The rate exceeds the limit.

Example

try:
  ...
except client.exceptions.ThrottlingException 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

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

Structure

  • (dict) --

    The rate exceeds the limit.

    • message (string) --

      The message for the exception.

    • 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 IoTDataPlane.Client.exceptions.UnauthorizedException

You are not authorized to perform this operation.

Example

try:
  ...
except client.exceptions.UnauthorizedException 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

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

Structure

  • (dict) --

    You are not authorized to perform this operation.

    • message (string) --

      The message for the exception.

    • 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 IoTDataPlane.Client.exceptions.UnsupportedDocumentEncodingException

The document encoding is not supported.

Example

try:
  ...
except client.exceptions.UnsupportedDocumentEncodingException 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

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

Structure

  • (dict) --

    The document encoding is not supported.

    • message (string) --

      The message for the exception.

    • 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: