"subscribeToMq" (jsonAction)
Use the "subscribeToMq" action to add or remove a client's subscriptions
The "subscribeToMq" action adds or removes a client's subscriptions, including those created by MQTT and the MQ API. It can change subscriptions without disconnecting an MQTT client. You can use the "subscribeToMq" action to manage the subscriptions of any session as long as your account has permission to do so. Thus, you can centrally manage the subscriptions for MQTT and MQ API sessions.
Use the required "clientName" property to identify the client's session. An MQTT or MQ API session with that client identifier must already exist; otherwise, the action returns an error. The FairCom server tracks session statistics so you can monitor the health of a client and its session, including the timestamp of the last received message, the client's subscription receive rate, the topics the session subscribes to, etc.
The "subscriptionActions" property contains a list of subscription objects that can add or remove a topic filter from a client's subscriptions.
Use the required
"subscriptionAction"property to add or remove a topic filter:"add"adds a topic filter to the subscription and"remove"removes it.Use the required
"topicFilter"property to specify a wildcard topic to subscribe to multiple topics.Use the optional
"subscriptionIdentifier"property to assign a unique identifier to the subscription. When the FairCom server sends an MQTT 5 message to the client, it includes the subscription identifier to help the client identify the subscription quickly and easily.Use the optional
"includeExpiredMessages": trueto include expired messages in the subscription. It defaults tofalse.Use the optional
"receiveRetainedMessages"property to control when the server sends retained messages to your subscription, which includes never sending the retained message, sending it only when the client subscribes for the first time, or sending it each time the client subscribes.Use the optional
"receiveMyMessages"property to prevent or allow the server to send messages to a client that the client published.Use the optional
"userProperties"property to set user defined subscription properties.
Tip
Use "subscribeToMq" to configure subscriptions for any MQ API and MQTT client. You can set MQTT 5 subscription properties for an MQTT 3.1.1 client. You can centrally manage subscriptions for clients.
Note
The account logged into the MQ API must have permission to access the session identified by "clientName".
Request example
{
"api": "mq",
"action": "subscribeToMq",
"params":
{
"clientName": "a unique MQTT client identifier",
"subscriptionActions": [
{
"subscriptionAction": "remove",
"topicFilter": "some/topic2/name/#"
},
"subscriptionAction": "add",
"topicFilter": "myTopic",
"subscriptionIdentifier": 268435455,
"binaryFormat": "base64 | hex | utf8 | json | byteArray",
"includeExpiredMessages": true,
"receiveMyMessages": false,
"receiveRetainedMessages": "onSubscription | onNewSubscription | never",
"receiveRetainedFlagAsPublished": true,
"userProperties": [
{
"key": "some key",
"value": "some value"
}
]
},
{
"subscriptionAction": "add",
"topicFilter": "some/topic2/name/#",
"userProperties": [
{
"key": "some key",
"value": "some value"
}
]
}
]
},
"apiVersion": "1.0",
"debug": "max",
"requestId": "optionalUniqueRequestIdFromTheClient",
"authToken": "replaceWithAuthTokenFromCreateSession"
}{
"requestId": "clientRequestId",
"result": {
"subscriptions": [
{
"topicFilter": "myTopic",
"matchingTopics": [
"myTopic"
],
"retainedMessages": [
{
"payload": "This is the message payload.",
"binaryFormat": "utf8",
"contentType": "IanaMediaType or a CustomType",
"correlationData": "any JSON value up to 65500 bytes",
"expirySeconds": 60,
"retain": true,
"responseTopic": "topic/name/for/subscriber/to/respond/to",
"userProperties": [
{
"key": "some key",
"value": "some value"
}
]
}
],
"errorCode": 0,
"errorMessage": "",
"debugInfo": {
}
},
{
"topicFilter": "some/topic2/name/#",
"matchingTopics": [
"some/topic2/name/1",
"some/topic2/name/2",
"some/topic2/name/3"
],
"errorCode": 0,
"errorMessage": "",
"debugInfo": {
}
}
]
},
"errorCode": 0,
"errorMessage": "",
"debugInfo": {}
}Use the "subscribeToMq" action to add or remove a client's subscriptions
Property | 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) specifies whether or not to include expired messages in a subscription |
| Boolean |
| ||||
(optional) allows a client's subscription to receive messages published by the client |
| Boolean |
| ||||
(optional) specifies how the FairCom server sets the retain flag on messages it sends to the subscriber |
| Boolean |
| ||||
(optional) specifies how MQTT 5 subscribers receive retained messages |
| enum |
| ||||
(optional) adds or removes a topic filter from a client's subscriptions |
| array | |||||
(optional) specifies an integer that uniquely identifies the |
| integer |
| ||||
(optional) specifies to include matching topics in the result |
| UTF-8 string | |||||
(optional) assigns key-value pairs to MQTT 5 messages |
| array |
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 "includeExpiredMessages" property to true to include expired messages in a subscription. A message has expired when the "messageHasExpired" property in the response is true.
The "receiveMyMessages" property is an optional Boolean property that allows a client's subscription to receive messages published by the client. It defaults to true.
The "receiveRetainedFlagAsPublished" is an optional Boolean property that specifies how the FairCom server sets the "retain" property on messages it sends to subscribers. When a client publishes a message, it sets the "retain" property to true to tell the FairCom server that it should retain the message and publish this message on behalf of the client when another client subscribes to a topic. A retained message is typically a special message that provides a new subscriber with status information about the topic.
When "receiveRetainedFlagAsPublished" is true, the FairCom server follows the MQTT 3 specification and passes the value of the "retain" property set by the publisher to the subscriber. Thus, a subscriber sees the value of the "retain" property that is set by the publisher. This notifies the subscriber that the message is a special status message from the client. This approach has the downside that a subscriber does not know when it gets a message sent by the FairCom server on behalf of the client in response to subscribing to a topic.
When "receiveRetainedFlagAsPublished" is false, the FairCom server follows the MQTT 5 specification and sets the "retain" property to true only when the FairCom server sends a retain message to a subscriber on behalf of a publisher, such as when a client subscribes to a topic. The MQTT 5 approach lets a subscriber know when it receives a retain message sent by the FairCom server vs. when it receives a normally published message from a client. This approach has the downside that a subscriber does not get the value of the "retain" property as set by the client who published the message. The MQTT 5 approach is generally better because the subscriber can tell when it is receiving a retained message in response to a subscription as opposed to a message published by a client.
The "receiveRetainedMessages" property is an optional enumerated string that specifies how MQTT 5 subscribers receive retained messages. It has three enumerated values: "onSubscription", "onNewSubscription", and "never". It defaults to "onSubscription".
"onSubscription"- the server sends a topic's retained message each time a client subscribes to a topic. Thus, a client can resubscribe to a topic to get the latest retained message."onNewSubscription"- the server only sends a topic's retained message when a client subscribes to a topic for the first time."never"- the server never sends a topic's retained message.
The "subscriptionActions" property is an array of subscription objects that add or remove a topic filter from a client's subscriptions. Each subscription object contains a "topicFilter" and an optional "subscriptionIdentifier".
Use the required
"subscriptionAction"property to add or remove a topic filter:"add"adds a topic filter to the subscription and"remove"removes it.Use the required
"topicFilter"property to a wildcard topic to subscribe to multiple topics.Use the optional
"subscriptionIdentifier"property to assign a unique identifier to the subscription. When the FairCom server sends an MQTT 5 message to the client, it includes the subscription identifier to help the client identify the subscription quickly and easily.Use the optional
"receiveRetainedMessages"property to control when the FairCom server sends the retained message to a topic subscription event, which includes never sending the retained message, sending it only when the client subscribes for the first time, or sending it each time the client subscribes.Use the optional
"receiveMyMessages"property to prevent or allow the FairCom server to send messages to a client that the client published.Use the optional
"userProperties"property to set user-defined subscription properties.
The "subscriptionIdentifier" is an integer number from 1 to 268435455 optionally provided by the subscriber that uniquely identifies the "topicFilter" to the subscriber. Each subscriber may assign its own "subscriptionIdentifier" to each "topicFilter". When the FairCom server delivers a message to the subscriber, it includes the "subscriptionIdentifier" with the message. The purpose of Subscription Identifiers is to make it easy and fast for an MQTT 5 client to process an incoming message. The client can use the Subscription Identifier in a message to associate a message with a specific handler. A client receiving a message with multiple Subscription Identifiers can send the message to multiple handlers – one for each Subscription Identifier.
The "topicFilter" property is an optional UTF-8 string containing a topic filter, which may contain MQTT wildcard characters, #, and +. Without wildcard characters, it matches one topic. When containing wildcard characters, it may match one or more topics.
The "userProperties" property is optional in the "publishMessagesToMq" action and defaults to null. When present, it is an array of key-value objects. A key-value object contains a "key" property and a "value" property with string values. You can assign multiple key-value pairs to an MQTT 5 message; the server includes them in the messages it delivers to subscribers. The server may process specific key-value pairs as instructions that modify its behavior.
"userProperties": [
{
"key": "some key",
"value": "some value"
}
]