The "describeTopics" action returns all available information about specified MQTT topics.
Request examples
Minimal
{
"apiVersion": "1.0",
"action": "describeTopics",
"params": {
"topics": [
"test/topic1"
]
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}
Response examples
Minimal
{
"result": {
"data": [
{
"name": "test/topic1",
"creationTime": "2024-02-01T23:47:45.814",
"messageCount": 2,
"lastMessageTime": "2024-02-01T23:47:51.716",
"averageMessagesPerMinute": 0,
"averageMessagesPerHour": 0,
"averageMessagesPerDay": 0,
"validateMqttPayload": "true",
"subscribeToExternalBrokers": [
{
"brokerConnectionName": "Broker1",
"topic": "test/topic1",
"qos": 1
},
{
"brokerConnectionName": "Broker2",
"topic": "test/topic1",
"qos": 2
}
],
"forwardToExternalBrokers": [
{
"brokerConnectionName": "Broker1",
"topic": "myForwardedTopicName1",
"qos": 1
},
{
"brokerConnectionName": "Broker2",
"topic": "myForwardedTopicName2",
"qos": 2
}
],
"subscriberList": [
{
"topicExpression": "#",
"connectionList": [
{
"connection": {
"clientId": "mqtt-explorer-001",
"ipaddress": "127.0.0.1",
"port": 35646,
"mqttProtocol": 4,
"keepAliveSeconds": 60,
"status": "Connected with clean flag = 1",
"connectionTime": "2024-01-31T17:31:19"
},
"qos": 0
}
]
},
{
"topicExpression": "test/#",
"connectionList": [
{
"connection": {
"clientId": "NodeREDSecure",
"ipaddress": "127.0.0.1",
"port": 36115,
"mqttProtocol": 4,
"keepAliveSeconds": 60,
"status": "Connected with clean flag = 1",
"connectionTime": "2024-01-31T17:31:30"
},
"qos": 1
}
]
}
],
"persistence": {
"topic": "test/topic1",
"mqttPayloadType": "json",
"databaseConnectionString": "FAIRCOMS",
"databaseUserName": "admin",
"databaseName": "faircom",
"tableName": "mqtt_msg_test_topic1",
"ownerName": "admin",
"threads": 1,
"tableAutoTimeStamp": true,
"tableAutoTimeStampIndex": true,
"tableReplicationReady": true,
"retentionPolicy": "autoPurge",
"retentionUnit": "week",
"retentionPeriod": 4,
"storeAndForward": true,
"maxDeliveryRatePerSecond": 0,
"newSubscriberDeliveryMode": "default",
"newSubscriberMaxDeliveredMessages": 0,
"retrySeconds": 20,
"outputPayloadField": "source_payload",
"label": {
"id": 1,
"group": "test",
"name": "test",
"value": null,
"enum": null,
"sequence": 0,
"deprecated": false,
"description": null,
"metadata": null
}
}
}
]
},
"errorCode": 0,
"errorMessage": "",
"authToken": "replaceWithAuthTokenFromCreateSession"
}
Properties
Request properties ("params")
| Property | Description | Default | Type | Limits (inclusive) |
|---|---|---|---|---|
topics |
The |
Optional with default of []
|
array |
0 or more topic strings |
Response properties ("result")
| Property | Description | Type | Limits (inclusive) |
|---|---|---|---|
data |
The |
array of objects | The action determines its contents. |
|
data .averageMessagesPerDay |
The "averageMessagesPerDay" property indicates how many messages MQTT clients or the MQ API publishes to the topic per day on average. It does not include records inserted into the topic's table by input connectors, SQL, the "insertRecords" action, etc. |
integer | The average number of messages published per day |
|
data .averageMessagesPerHour |
The "averageMessagesPerHour" property indicates how many messages MQTT clients or the MQ API publishes per hour on average. It does not include records inserted into the topic's table by input connectors, SQL, the "insertRecords" action, etc. |
integer | The average number of messages published per hour |
|
data .averageMessagesPerMinute |
The "averageMessagesPerMinute" property indicates how many messages MQTT clients or the MQ API publishes per minute on average. It does not include records inserted into the topic's table by input connectors, SQL, the "insertRecords" action, etc. |
integer | The average number of messages published per minute |
|
data .creationTime |
The "creationTime" property details the date and time when the specified topic was created. This property stores the creation date in an ISO 8601 timestamp. |
timestamp | An ISO 8601 timestamp |
|
data .forwardToExternalBrokers |
The "forwardToExternalBrokers" property specifies one or more brokers to forward the message to. All messages sent to this topic will be forwarded to each of these external brokers using the specified topic name. For more details, see "forwardToExternalBrokers". |
array of objects |
Zero or more objects including some or all of the following properties:
|
|
data forwardToExternalBrokers .brokerConnectionName |
The "brokerConnectionName" property specifies the unique user-defined name for the connection. |
string | 1 to 100 bytes |
|
data forwardToExternalBrokers .qos |
The "qos" property defines the MQTT quality of service for publishing the message that will be sent to the MQTT broker. |
integer enum |
|
|
data forwardToExternalBrokers .topic |
The
|
string | 1 to 65,500 bytes |
|
data .lastMessageTime |
The "lastMessageTime" property specifies the last time that a message was published by the topic. |
timestamp | An ISO 8601 timestamp |
|
data .messageCount |
The "messageCount" property indicates the total number of messages MQTT clients or the MQ API publishes to the topic. It does not include records inserted into the topic's table by input connectors, SQL, the "insertRecords" action, etc. |
BigInteger |
0 to 9223372036854775807
|
|
data .name |
The The The |
string | 1 to 64 bytes |
|
data .persistence |
The "persistence" property defines the parameters of the persistence table. |
object |
|
|
data persistence .databaseConnectionString |
The "databaseConnectionString" property specifies the connection string for the database that holds the persistence table. |
string | No limits |
|
data persistence .databaseName |
The
|
string | 1 to 64 bytes |
|
data persistence .databaseUserName |
The "databaseUserName" property specifies the user name of the account logged into the database that holds the persistence table. |
string | 0 to 64 bytes |
|
data persistence .label |
The A label is a tag that you can add to some objects, such as an MQTT topic or session. You can use list actions such as The |
object | "label": {
"group": "group name",
"name": "label name"
} |
|
data persistence label .deprecated |
The |
Boolean |
|
|
data persistence label .description |
The Markdown is a good language for formatting description text. You must ensure the text is compatible with a JSON string. For example, you must escape a double quote character using the backslash character:
In the Thing API, It defaults to
|
string | 1 to 65,500 bytes |
|
data persistence label .enum |
The
|
smallint |
-32768 to 32767
|
|
data persistence label .group |
The The If the When you assign a group name to a label, the server automatically checks whether the group name exists in the list of groups returned by the "listLabelGroups" action. If the group name does not exist, the server adds the group name to the list. When you rename a group assigned to a label, the server automatically adds a new group name to the list and removes the previous group name if no other label uses it.
|
string | 1 to 64 bytes |
|
data persistence label .id |
The |
integer |
|
|
data persistence label .metadata |
The |
JSON | 0 to 65,500 bytes |
|
data persistence label .name |
The The The
|
string | 1 to 64 bytes |
|
data persistence label .sequence |
The |
float | Any floating point or integer number. |
|
data persistence label .value |
The
When you use the
In Key-Value actions, the |
JSON | 0 to 65,500 bytes |
|
data persistence .maxDeliveryRatePerSecond |
The
|
integer |
0 to 2147483647
|
|
data persistence .mqttPayloadType |
The "mqttPayloadType" property specifies the variant type format of the "source_payload" field. For more details, see mqttPayloadType. |
string enum |
|
|
data persistence .newSubscriberDeliveryMode |
The
|
string enum |
|
|
data persistence .newSubscriberMaxDeliveredMessages |
The
|
integer |
-1 to 2147483647
|
|
data persistence .outputPayloadField |
The
This makes it possible for the output from any transform to be used as the payload delivered to subscribers. |
string |
"source_payload" or a user-defined field |
|
data persistence .ownerName |
The "ownerName" property identifies the user who owns an object (see Object owner). |
string | 0 to 64 bytes |
|
data persistence .retentionPeriod |
The
When partitions are auto-purged, some data are maintained Automatically purging data is important to ensure that retained data does not consume all storage and shut down the computer. The default value of 4 weeks allows FairCom's servers to store 1 TB of messages when 200 topics send one 2K message per second.
|
integer |
1 to 100
|
|
data persistence .retentionPolicy |
The Possible values:
|
string enum |
|
|
data persistence .retentionUnit |
Each time this unit cycles, FairCom purges expired messages. For example, if you want a week's worth of messages to be purged once a week, set
|
string enum |
|
|
data persistence .retrySeconds |
The
|
integer |
1 to 65535
|
|
data persistence .storeAndForward |
The "storeAndForward" property is true when the broker first stores each message before delivering it to subscribers. It is false when messages are delivered to subscribers without storing them. |
Boolean |
|
|
data persistence .tableAutoTimeStamp |
The "tableAutoTimeStamp" property specifies whether or not the server automatically sets the create_ts field to the current timestamp in UTC time when it inserts a record into the topic's integration table. |
Boolean |
|
|
data persistence .tableAutoTimeStampIndex |
The "tableAutoTimeStampIndex" property specifies whether or not the table has an index on the create_ts field. |
Boolean |
|
|
data persistence .tableName |
The See table name in System specifications for the table naming requirements and limitations. |
string | 1 to 64 bytes |
|
data persistence .tableReplicationReady |
The "tableReplicationReady" property enables the transaction log on the persistence table. Transaction logs must be enabled before a table can be replicated. |
Boolean |
|
|
data persistence .threads |
The
|
integer |
|
|
data persistence .topic |
The |
string | A topic name between 1 and 65,500 bytes |
|
data .subscribeToExternalBrokers |
The "subscribetoExternalBroker" property lists the external brokers to which you want to subscribe. |
array of objects |
|
|
data subscribeToExternalBrokers .brokerConnectionName |
The "brokerConnectionName" property specifies the unique user-defined name for the connection. |
string | 1 to 100 bytes |
|
data subscribeToExternalBrokers .qos |
The "qos" property defines the MQTT quality of service for publishing the message that will be sent to the MQTT broker. |
integer enum |
|
|
data subscribeToExternalBrokers .topic |
The
|
string | 1 to 65,500 bytes |
|
data .subscriberList |
The "subscriberList" property lists everything that is subscribed to the topic. |
array of objects |
|
|
data subscriberList .connectionList |
The "connectionList" property lists each connection to the topic. |
array of objects |
|
|
data subscriberList connectionList .connection |
The "connection" property lists the details of the specified connection. |
object |
|
|
data subscriberList connectionList connection .clientId |
The "clientId" property specifies the unique string that identifies the client and its session. |
string | 1 to 65,500 bytes |
|
data subscriberList connectionList connection .connectionTime |
The "connectionTime" property specifies the date and time when the connection was established. |
timestamp | An ISO 8601 timestamp |
|
data subscriberList connectionList connection .ipaddress |
The "ipAddress" property specifies the PLC/Equipment IPV4 Address. |
string | A valid IP address |
|
data subscriberList connectionList connection .keepAliveSeconds |
The |
integer | No limit |
|
data subscriberList connectionList connection .mqttProtocol |
The "mqttProtocol" property specifies the version of MQTT protocol to use in your session. |
string enum |
|
|
data subscriberList connectionList connection .port |
The |
integer | an integer port number |
|
data subscriberList connectionList connection .status |
The
When the
To create, alter, and list inactive items, set the |
string enum |
|
|
data subscriberList connectionList .qos |
The "qos" property defines the MQTT quality of service for publishing the message that will be sent to the MQTT broker. |
integer enum |
|
|
data subscriberList .topicExpression |
The "topicExpression" property is a topic or a topic wildcard that defines the topics in a subscription. A topic wildcard expression may contain the + symbol to match any value in one level of a topic hierarchy, such as baseball/+/collectables/. It may also contain the # symbol at the end of the expression to match all subsequent levels of the hierarchy, such as baseball/RedSox/#. |
string | 0 to 65,500 bytes |
|
data .validateMqttPayload |
The "defaultValidateMqttPayload" property determines if the broker validates the MQTT payload by default. Setting this property to true causes the broker to validate the MQTT message payload published to all topics to verify it matches the type specified by the "defaultMqttPayloadType" or "mqttPayloadType" properties. See "validateMqttPayload" for more information |
Boolean |
|