"getMessagesFromMqApiSession" (jsonAction)
Use the "getMessagesFromMqApiSession" action to retrieve undelivered messages from an MQ API client-subscribed topic
The "getMessagesFromMqApiSession" action retrieves undelivered messages from topics to which an MQ API client has subscribed.
The MQ client is identified by the required "clientName" property. An MQ API session with that client identifier must already exist; otherwise, it returns an error. It also returns an error when the "clientName" is used by an MQTT connection.
Each time you call this action with the same "clientName", the server starts where it left off and delivers the next set of messages published to that client. It retrieves undelivered messages up to the number specified by "maxMessages". The message payload is encoded according to the "binaryFormat" property.
If you subscribe to multiple topics, the server returns messages from all of them. You can use the "topic" property to retrieve messages from only one of your subscribed topics.
The typical pattern for using this action is to first call the "createMqApiSession" action to create a new session. Then, use the "subscribeToMq" action to subscribe to topics. You can then repeatedly call the "getMessagesFromMqApiSession" action to retrieve messages as clients publish them.
An application can retrieve messages sent to a shared topic, which is a topic starting with $share/. A shared topic works differently from a normal topic because the server distributes each message to a different subscriber rather than sending each message to each subscriber. Each time a subscriber uses the "getMessagesFromMqApiSession" action to retrieve a message, the server removes the message from the queue and prevents that message from being sent to another subscriber. If the application encounters an error processing a message, it must publish the message back to the topic so it can be processed by another subscriber.
Tip
An application can use "getMessagesFromMqApiTopic" to retrieve shared messages without removing them from the queue.
Warning
clients must use unique client names so they do not consume each other's messages. If multiple processes use the same value for the "clientName" property in the "getMessagesFromMqApiSession" action, each process denies other processes from retrieving messages that it has retrieved. You may want to do this to implement distributed command processing. On the other hand, if you want to use the event streaming technique to retrieve messages, do not subscribe to topics; Instead, use the "getMessagesFromMqTopic" action to retrieve messages.
Optionally, set "includeMqttProperties": true to include the message's MQTT properties. It defaults to false.
Optionally, set "includeTransformFields": true to include the custom fields used for the transformation process's inputs and outputs. It defaults to false.
Request examples
Maximal
{
"api": "mq",
"action": "getMessagesFromMqApiSession",
"params":
{
"topic": "optional topic name",
"clientName": "required unique MQ API client name",
"maxMessages": 100,
"binaryFormat": "base64 | hex | utf8 | json | byteArray",
"includeMessageMetadata": true,
"includeMqttProperties": true,
"includeTransformFields": true
},
"apiVersion": "1.0",
"debug": "max",
"requestId": "optionalUniqueRequestIdFromTheClient",
"authToken": "replaceWithAuthTokenFromCreateSession"
}{
"api": "mq",
"action": "getMessagesFromMqApiSession",
"params":
{
"clientName": "required unique MQ API client identifier",
"maxMessages": 100
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}{
"api": "mq",
"action": "getMessagesFromMqApiSession",
"params":
{
"clientName": "required unique MQ API client identifier"
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}{
"api": "mq",
"action": "getMessagesFromMqApiSession",
"params":
{
"clientName": "required unique MQ API client identifier",
"topicFilter": "topic#",
"maxMessages": 100,
"binaryFormat": "json",
"includeMessageMetadata": true,
"includeMqttProperties": true,
"includeTransformFields": true
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}{
"result": {
"messages":
[
{
"clientName": "Client identifier",
"topic": "test/topic1",
"subscriptionIdentifiers": [123],
"databaseName": "faircom",
"ownerName": "admin",
"tableName": "mqtt_msg_test_topic1",
"payload": "C3A3",
"binaryFormat": "base64 | hex | utf8 | json | byteArray",
"id": "263",
"timestamp": "2023-12-18T18:04:20:085",
"error": false,
"log": null,
"contentType": "IanaMediaType or a CustomType",
"correlationData": "any JSON value up to 65500 bytes",
"expirySeconds": 60,
"messageHasExpired": true,
"payloadFormat": "binary | utf8",
"publishedQoS": 2,
"retain": true,
"responseTopic": "topic/name/for/subscriber/to/respond/to",
"userProperties": [
{
"key": "some key",
"value": "some value"
}
],
"faircomClientId": 6732,
"faircomTopicId": 457,
"faircomForwardTopicId": 0,
"faircomMqttPacketId": 53736,
"faircomMqttSentReason": "Client | Retained | Will | Forwarded",
"transformFields": [
{ "fieldName": "t1", "fieldData": "some value" }
]
}
]
},
"errorCode": 0,
"errorMessage": "",
"debugInfo": {
},
"requestId": "optionalUniqueRequestIdFromTheClient",
"authToken": "replaceWithAuthTokenFromCreateSession"
}Use the "getMessagesFromMqApiSession" action to retrieve undelivered messages from an MQ API client-subscribed topic
"params" property summariesProperty | Description | Default | Type | Limits (inclusive) | ||
|---|---|---|---|---|---|---|
(optional) specifies how the |
| string | One of the following: | |||
(optional) specifies the unique name that identifies the client to the FairCom MQ engine |
| string | 0 to 65,550 bytes | |||
(optional) returns the message's |
| Boolean |
| |||
(optional) returns MQTT properties in the response |
| Boolean |
| |||
(optional) returns custom transform fields in the response |
| Boolean |
| |||
(optional) specifies the number of messages to return from a |
| integer |
| |||
(optional) specifies the name of a topic |
| UTF-8 string |
The "clientName" property is an optional string of up to 65,550 characters. It is the client identifier (or clientId) in the MQTT protocol. It uniquely identifies an MQ session, which contains information about a client's subscriptions, settings, and queue position of each topic to which the client is subscribed. The FairCom MQ engine stores this information and retrieves it when an MQTT or MQ API client connects.
Connection authorization is done using an account name with a password or a client certificate.
The "clientName" property does not authorize an MQTT or MQ API session. Another authentication technique authorizes the connection, such as an account name and password or a client certificate. Thus, any account may be used to authorize an MQ connection. Each account is assigned to roles that authorize access to specific topics, client names, actions, etc.
The MQ API allows multiple processes to simultaneously use the same client name to manage sessions, subscribe to topics, send messages to topics, and retrieve messages from topics.
The MQTT protocol allows only one connection per client identifier because each connection is stateful. If another client with the same "clientName" is already connected, the FairCom server disconnects the other client and vice-versa.
Set the "includeMessageMetadata" property to true to include the message's "id", "timestamp", "error", and "log" properties.
Set the "includeMqttProperties" property to true to include the MQTT properties in the response. Otherwise, omit the property or set it to false or null. MQTT properties are helpful when you need to troubleshoot MQTT messages.
Set the "includeTransformFields" property to true to include custom transform fields (if any) that a customer added to the integration table. Otherwise, omit the property or set it to false or null. Custom transform fields are helpful when you want to see the outputs and inputs of transformations assigned to the integration table.maxMessages.
The "maxMessages" property is optional and defaults to 20. It has a minimum value of 1 and a maximum value of 100000. It specifies the number of messages to return from a "getMessages…" action. The number of returned messages will be equal to or less than this maximum.
The "topic" property is a required, case-sensitive UTF-8 string containing the name of a topic. It must not contain MQTT wildcard characters, #, or +. It may contain multiple / characters, which segment a topic into a set of positional properties.