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
Minimal
{
"action": "subscribeToMq",
"params": {
"clientName": "client1",
"subscriptionActions": [
{
"subscriptionAction": "remove",
"topicFilter": "Test/Topic1",
"subscriptionIdentifier": 268435455,
"binaryFormat": "hex",
"includeExpiredMessages": true,
"receiveMyMessages": false,
"receiveRetainedMessages": "onSubscription",
"receiveRetainedFlagAsPublished": true,
"userProperties": [
{
"key": "some key",
"value": "some value"
}
]
},
{
"subscriptionAction": "add",
"topicFilter": "Test/Topic2",
"userProperties": [
{
"key": "some key",
"value": "some value"
}
]
}
]
},
"responseOptions": {
"dataFormat": "arrays",
"numberFormat": "number",
"binaryFormat": "base64",
"variantFormat": "json"
},
"apiVersion": "1.0",
"debug": "max",
"requestId": "optionalUniqueRequestIdFromTheClient",
"authToken": "replaceWithAuthTokenFromCreateSession"
}
Response example
Success
{
"authToken": "authToken",
"result": {
"subscriptions": [
{
"matchingTopics": [
],
"topicFilter": "Test/Topic1",
"errorCode": 0,
"errorMessage": "",
"debugInfo": {
}
},
{
"matchingTopics": [
],
"topicFilter": "Test/Topic2",
"errorCode": 0,
"errorMessage": "",
"debugInfo": {
}
}
]
},
"requestId": "5",
}
Properties
Request properties ("params")
| Property | Description | Default | Type | Limits (inclusive) |
|---|---|---|---|---|
clientName |
The "clientName" property specifies the unique name that identifies the client to the FairCom MQ engine. |
Optional with default of ""
|
string | 0 to 65,550 bytes |
subscriptionActions |
The
|
Optional with default of []
|
array |
|
|
subscriptionActions .binaryFormat |
The "binaryFormat" property designates the format of binary values embedded in JSON strings. For more details, see "binaryFormat". |
Optional with default of "hex"
|
string | One of the following: "base64", "hex", or "byteArray". |
|
subscriptionActions .includeExpiredMessages |
The
|
Optional with default of true
|
Boolean |
|
|
subscriptionActions .receiveMyMessages |
The |
Optional with default of true
|
Boolean |
|
|
subscriptionActions .receiveRetainedFlagAsPublished |
The When When |
Optional with default of true
|
Boolean |
|
|
subscriptionActions .receiveRetainedMessages |
The
|
Optional with default of "onSubscription"
|
enum |
|
|
subscriptionActions .subscriptionAction |
The "subscriptionAction" property specifies whether the action will add or remove the specified subscription. |
Optional with default of "add"
|
string enum |
|
|
subscriptionActions .subscriptionIdentifier |
The |
Optional with default of 268435455
|
integer |
0 to 268435455
|
|
subscriptionActions .topicFilter |
The |
Optional with default of ""
|
UTF-8 string | topic names |
|
subscriptionActions .userProperties |
The "userProperties": [
{
"key": "some key",
"value": "some value"
}
] |
Optional with default of null
|
array | 0 or more key/value pairs |
|
subscriptionActions userProperties .key |
The "key" property is part of an optional key-value object that is defined in an array in the "userProperties" property. It is a user-defined string value. |
Optional with default of
Required in the Key-Value API |
string | 1 to 128 bytes |
|
subscriptionActions userProperties .value |
The
In Key-Value actions, the required |
Required - No default value | string |
|
Response properties ("result")
| Property | Description | Type | Limits (inclusive) |
|---|---|---|---|
subscriptions |
The "subscriptions" property details information about each subscription that matches the parameters of the request. |
array |
|
|
subscriptions .debugInfo |
The "debugInfo" property specifies debugging information for use in troubleshooting. |
object | No limit |
|
subscriptions .errorCode |
The "errorCode" property indicates an error when set to a non-zero integer or success when 0.
|
integer | -2147483648 to 2147483647 |
|
subscriptions .errorMessage |
The "errorMessage" property displays a human-readable error message. |
string | 0 to 256 bytes |
|
subscriptions .matchingTopics |
The "matchingTopics" property lists the topics that match the parameters specified in the request. |
array | No limit |
|
subscriptions .topicFilter |
The |
UTF-8 string | topic names |