"describeTopics" (JSON Action)
JSON MQ "describeTopics" action returns info about MQTT topics
The "describeTopics" action returns all available information about specified MQTT topics.
Request examples
Minimal
{
"api": "mq",
"apiVersion": "1.0",
"action": "describeTopics",
"params": {
"topics": [
"test/topic1"
]
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}
{
"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,
"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",
"sourcePayloadFormat": "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"
}
The "describeTopics" JSON action retrieves information about MQTT topics using action parameters, notably "topics", while the "result" object returns data, including topic details and "sourcePayloadFormat", which specifies the data type of the MQTT payload. The document also specifies how the server handles different "sourcePayloadFormat" values, including validation and conversion, and highlights that it's a hint for the server's handling of the payload rather than a strict validation rule in most cases.
The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties. See System limits for a comprehensive look at property requirements and limitations.
"params" property summariesProperty | Description | Default | Type | Limits (inclusive) |
|---|---|---|---|---|
topics | (optional) contains |
| array |
Properties summary
"result" property summariesProperty | Description | Type | Limits (inclusive) | ||||||
|---|---|---|---|---|---|---|---|---|---|
data | (optional) specifies an array or object that the server returns, such as records returned by a query. It is always included in a response but contains an empty array when no results are available. It is an empty array when there are no results available | array | Its contents are determined by the action | ||||||
(optional) specifies the variant type format of the | string |
|
The "sourcePayloadFormat" property is an optional string that specifies the expected data type of the MQTT payload. When omitted or set to null, it defaults to "binary". When the server receives an MQTT message, it always takes the binary value from the MQTT payload and stores it in the source_payload field. The source_payload field is a variant, which means it stores the type of data it contains. If there are no errors in validating the MQTT payload to match the type specified in "sourcePayloadFormat", the server assigns the value of "sourcePayloadFormat" as the variant field's type.
Depending on the values of the "sourcePayloadFormat" and "validateMqttPayload" properties, the server may validate the MQTT payload to ensure it matches the type. The default value for the "validateMqttPayload" property is true. The server may also convert the MQTT payload into another form before storing it. If the MQTT payload does not match the type or cannot be converted, the server stores the payload in the source_payload field, sets its variant type to "binary", and sets the error field to 1 to indicate there is an error. It also adds an error entry to the JSON array in the log field.
FairCom's MQTT server does the following when a topic receives an MQTT message and "sourcePayloadFormat" is set to one of the following values:
"sourcePayloadFormat" Value | Description |
|---|---|
| The server stores the MQTT payload in the |
| The server stores the MQTT payload in the
|
| The server stores the MQTT payload in the
|
| The server validates the payload as a variant object.
The server ignores the value of |
| The server stores the MQTT payload in the |
| The server stores the MQTT payload in the |
| The server stores the MQTT payload in the |
This property is a hint to the server about the format and type of the MQTT message payload.
This property does not cause server to validate the MQTT payload to see if it matches the type you set. The server stores the payload as is without validation. For example, setting the type to
"json", it does not stop the server from receiving and storing a non-JSON value or invalid JSON document in the source payload.The FairCom Edge Explorer application may use the value of this property to determine the default way to display a topic's payload.
The transform engine may use the value of this property to help it transform the source payload.