connections

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

Overview

Name	connections
Type	Resource
Id	aws.iot_data.connections

Fields

The following fields are returned by SELECT queries:

get_connection

Name	Datatype	Description
clean_session	boolean	Indicates whether the client is using a clean session. Returns true for clean sessions or false for persistent sessions.
client_id	string	The unique identifier of the MQTT client. This is the same client ID that was used when the client established the connection. (pattern: <code>^[^$].*</code>)
connected	boolean	The connection state of the client. Returns true if the client is currently connected, or false if the client is not connected.
connected_since	integer (int64)	Unix timestamp (in milliseconds) indicating when the client connected. Present only when connected is true.
disconnect_reason	string	The reason for the last disconnection, if the client is currently disconnected. See the developer guide for valid disconnect reasons.
disconnected_since	integer (int64)	Unix timestamp (in milliseconds) indicating when the client disconnected. Present only when connected is false. This information is available for 30 minutes after the client disconnects.
keep_alive_duration	integer	The keep-alive interval in seconds that the client specified when establishing the connection.
session_expiry	integer (int64)	The session expiry interval in seconds for the MQTT client connection. This is configured by the user. This value indicates how long the session will remain active after the client disconnects.
source_ip	string	The IP address of the client that initiated the connection.
source_port	integer	The client's source port.
target_ip	string	The IP address of the Amazon Web Services IoT Core endpoint that the client connected to. For clients connected to VPC endpoints, this is the private IP address of the network interface the client is connected to.
target_port	integer	The port number of the Amazon Web Services IoT Core endpoint that the client connected to.
thing_name	string	The name of the thing associated with the principal of the MQTT client, if applicable. (pattern: <code>[a-zA-Z0-9:_-]+</code>)
vpc_endpoint_id	string	The ID of the VPC endpoint. Present for clients connected to IoT Core via a VPC endpoint.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_connection	select	client_id, region	includeSocketInformation	Retrieves connection information for the specified MQTT client. Requires permission to access the GetConnection action.
delete_connection	delete	client_id, region	cleanSession, preventWillMessage	Disconnects a connected MQTT client from Amazon Web Services IoT Core. When you disconnect a client, Amazon Web Services IoT Core closes the client's network connection and optionally cleans the session state. Requires permission to access the DeleteConnection action.

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
client_id	string	The unique identifier of the MQTT client to disconnect. The client ID can't start with a dollar sign ($). MQTT client IDs must be URL encoded (percent-encoded) when they contain characters that are not valid in HTTP requests, such as spaces, forward slashes (/), and UTF-8 characters.
region	string	AWS region (default: us-east-1)
cleanSession	boolean	Specifies whether to remove the client's persistent session state when disconnecting. Set to TRUE to delete all session information, including subscriptions and queued messages. Set to FALSE to preserve the session state for persistent sessions. For clean sessions this parameter will be ignored. By default, this is set to FALSE (preserves the session state).
includeSocketInformation	boolean	Specifies if socket information (sourcePort, targetPort, sourceIp, targetIp) should be included in the GetConnection response. Set to TRUE to include socket information. Set to FALSE to omit socket information. By default, this is set to FALSE. See the developer guide for how to authorize this parameter.
preventWillMessage	boolean	Controls if Amazon Web Services IoT Core publishes the client's Last Will and Testament (LWT) message upon disconnection. Set to TRUE to prevent publishing the LWT message. Set to FALSE to ensure that LWT is published. By default, this is set to FALSE (LWT message is published).

SELECT examples

get_connection

Retrieves connection information for the specified MQTT client. Requires permission to access the GetConnection action.

SELECT
clean_session,
client_id,
connected,
connected_since,
disconnect_reason,
disconnected_since,
keep_alive_duration,
session_expiry,
source_ip,
source_port,
target_ip,
target_port,
thing_name,
vpc_endpoint_id
FROM aws.iot_data.connections
WHERE client_id = '{{ client_id }}' -- required
AND region = '{{ region }}' -- required
AND includeSocketInformation = '{{ includeSocketInformation }}'
;

DELETE examples

delete_connection

Disconnects a connected MQTT client from Amazon Web Services IoT Core. When you disconnect a client, Amazon Web Services IoT Core closes the client's network connection and optionally cleans the session state. Requires permission to access the DeleteConnection action.

DELETE FROM aws.iot_data.connections
WHERE client_id = '{{ client_id }}' --required
AND region = '{{ region }}' --required
AND cleanSession = '{{ cleanSession }}'
AND preventWillMessage = '{{ preventWillMessage }}'
;