retained_messages

Creates, updates, deletes, gets or lists a retained_messages resource.

Overview

Name	retained_messages
Type	Resource
Id	aws.iot_data.retained_messages

Fields

The following fields are returned by SELECT queries:

get_retained_message

Name	Datatype	Description
last_modified_time	integer (int64)	The Epoch date and time, in milliseconds, when the retained message was stored by IoT.
payload	string (byte)	The Base64-encoded message payload of the retained message body.
qos	integer	The quality of service (QoS) level used to publish the retained message.
topic	string	The topic name to which the retained message was published.
user_properties	string (byte)	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"}]

list_retained_messages

Name	Datatype	Description
last_modified_time	integer (int64)	The Epoch date and time, in milliseconds, when the retained message was stored by IoT.
payload_size	integer (int64)	The size of the retained message's payload in bytes.
qos	integer	The quality of service (QoS) level used to publish the retained message.
topic	string	The topic name to which the retained message was published.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_retained_message	select	topic, region		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. Requires permission to access the GetRetainedMessage action. For more information about messaging costs, see Amazon Web Services IoT Core pricing - Messaging.
list_retained_messages	select	region	nextToken, maxResults	Lists summary information about the retained messages stored for the account. This action returns only the topic names of the retained messages. It doesn't return any message payloads. Although this action doesn't return a message payload, it can still incur messaging costs. To get the message payload of a retained message, call GetRetainedMessage with the topic name of the retained message. Requires permission to access the ListRetainedMessages action. For more information about messaging costs, see Amazon Web Services IoT Core pricing - Messaging.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)
topic	string	The topic name of the retained message to retrieve.
maxResults	integer	The maximum number of results to return at one time.
nextToken	string	To retrieve the next set of results, the nextToken value from a previous response; otherwise null to receive the first set of results.

SELECT examples

get_retained_message

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. Requires permission to access the GetRetainedMessage action. For more information about messaging costs, see Amazon Web Services IoT Core pricing - Messaging.

SELECT
last_modified_time,
payload,
qos,
topic,
user_properties
FROM aws.iot_data.retained_messages
WHERE topic = '{{ topic }}' -- required
AND region = '{{ region }}' -- required
;

list_retained_messages

Lists summary information about the retained messages stored for the account. This action returns only the topic names of the retained messages. It doesn't return any message payloads. Although this action doesn't return a message payload, it can still incur messaging costs. To get the message payload of a retained message, call GetRetainedMessage with the topic name of the retained message. Requires permission to access the ListRetainedMessages action. For more information about messaging costs, see Amazon Web Services IoT Core pricing - Messaging.

SELECT
last_modified_time,
payload_size,
qos,
topic
FROM aws.iot_data.retained_messages
WHERE region = '{{ region }}' -- required
AND nextToken = '{{ nextToken }}'
AND maxResults = '{{ maxResults }}'
;