:doc:`IoTDataPlane <../../iot-data>` / Client / get_retained_message

********************
get_retained_message
********************



.. py:method:: IoTDataPlane.Client.get_retained_message(**kwargs)

  

  Gets the details of a single retained message for the specified topic.

   

  This action returns the message payload of the retained message, which can incur messaging costs. To list only the topic names of the retained messages, call `ListRetainedMessages <https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_ListRetainedMessages.html>`__.

   

  Requires permission to access the `GetRetainedMessage <https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html>`__ action.

   

  For more information about messaging costs, see `Amazon Web Services IoT Core pricing - Messaging <http://aws.amazon.com/iot-core/pricing/#Messaging>`__.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/iot-data-2015-05-28/GetRetainedMessage>`_  


  **Request Syntax**
  ::

    response = client.get_retained_message(
        topic='string'
    )
    
  :type topic: string
  :param topic: **[REQUIRED]** 

    The topic name of the retained message to retrieve.

    

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'topic': 'string',
          'payload': b'bytes',
          'qos': 123,
          'lastModifiedTime': 123,
          'userProperties': b'bytes'
      }
      
    **Response Structure**

    

    - *(dict) --* 

      The output from the GetRetainedMessage operation.

      
      

      - **topic** *(string) --* 

        The topic name to which the retained message was published.

        
      

      - **payload** *(bytes) --* 

        The Base64-encoded message payload of the retained message body.

        
      

      - **qos** *(integer) --* 

        The quality of service (QoS) level used to publish the retained message.

        
      

      - **lastModifiedTime** *(integer) --* 

        The Epoch date and time, in milliseconds, when the retained message was stored by IoT.

        
      

      - **userProperties** *(bytes) --* 

        A base64-encoded JSON string that includes an array of JSON objects, or null if the retained message doesn't include any user properties.

         

        The following example ``userProperties`` parameter is a JSON string that represents two user properties. Note that it will be base64-encoded:

         

        ``[{"deviceName": "alpha"}, {"deviceCnt": "45"}]``

        
  
  **Exceptions**
  
  *   :py:class:`IoTDataPlane.Client.exceptions.InvalidRequestException`

  
  *   :py:class:`IoTDataPlane.Client.exceptions.ResourceNotFoundException`

  
  *   :py:class:`IoTDataPlane.Client.exceptions.ThrottlingException`

  
  *   :py:class:`IoTDataPlane.Client.exceptions.UnauthorizedException`

  
  *   :py:class:`IoTDataPlane.Client.exceptions.ServiceUnavailableException`

  
  *   :py:class:`IoTDataPlane.Client.exceptions.InternalFailureException`

  
  *   :py:class:`IoTDataPlane.Client.exceptions.MethodNotAllowedException`

  