====== REST API ======
环信MQTT消息云提供云端API接口，遵循REST体系结构，服务端应用可以直接调用，与环信MQTT消息云进行消息交互。\\

===== 概览 =====
|接口名称|使用场景|
|[[mqtt:restapisum#获取应用Token|获取应用Token]]|当不通过SDK，直接调用openAPI接口时，需要在头部'Authorization'参数设置 \\ 应用Token，本接口即可获取应用Token。|
| [[mqtt:restapisum#申请用户访问Token|申请用户Token]]|直接调用接口获取用户访问Token，用于MQTT 客户端登录时使用。|
| [[mqtt:restapisum#发送消息|发送消息]]|直接调用接口向主题发消息，支持向一个或多个主题发送消息。|
| [[mqtt:restapisum#获取客户端连接记录|获取客户端连接记录]]|直接调用接口获取MQTT 客户端的连接记录。|
| [[mqtt:restapisum#获取客户端session信息|获取客户端session信息]]|直接调用接口根据Client ID获取客户端的连接信息时，包括在线状态、最新 \\ 上线时间、登录用户ID、使用版本、订阅关系等|
| [[mqtt:restapisum#获取客户端消息发送_投递记录|获取客户端消息发送&投递记录]]|直接调用接口获取指定客户端消息发送与投递记录时。|
| [[mqtt:restapisum#获取指定消息的发送记录|获取指定消息的发送记录]]|直接调用接口获取指定消息的发送记录时。|
| [[mqtt:restapisum#获取指定消息的投递记录|获取指定消息的投递记录]]|直接调用接口获取指定消息的投递记录时。|
| [[mqtt:restapisum#获取指定消息内容|获取指定消息内容]]|直接调用接口获取指定消息ID的具体内容。|
| [[mqtt:restapisum#获取指定topic的上行历史消息记录|获取指定topic的上行历史消息记录]]|直接调用接口获取指定topic某个时间段内的上行历史消息记录。|
| [[mqtt:restapisum#获取指定主题的在线客户端列表|获取指定主题的在线客户端列表]]|根据channel/topic获取当前在线客户端列表。|
| [[mqtt:restapisum#获取指定用户ID的在线客户端列表|获取指定用户ID的在线客户端列表]]|根据用户ID/用户名获取当前在线客户端列表。|
| [[mqtt:restapisum#获取应用ID下的在线客户端列表|获取应用ID下的在线客户端列表]]|根据应用ID/appid获取当前在线客户端列表。|
===== 获取应用Token =====
==== 使用场景 ====
当不通过SDK，直接调用openAPI接口时，需要在头部'Authorization'参数设置应用Token，本接口即可获取应用Token。
==== 请求说明 ====
=== 请求方法：POST ===
=== URL ：{api}/openapi/rm/app/token ===
''其中{api}通过console后台【服务概览】->【服务配置】->【REST API地址】获取''
=== 请求参数：JSON格式 ===
^参数名称^类型^是否必选^示例^说明^
| appClientId|String|是|"YXA6ypREjkbBRTCXNsDYhFpKVw"|开发者Client ID，系统生成，从下图中获取|
| appClientSecret|String|是|"YXA6brhCN65pz*y86X9uL63mgeV*90k"|开发者密钥，从下图中获取|
{{:playground:message:restapi1.jpg|}}
==== 返回参数 ====
|参数名称|类型|示例|说明|
|code|Integer|200|200：获取成功；400：获取失败|
|msg|String|“success”或“fail”|success：获取成功；fail：获取失败|
| body |Object|{"access_token":"YWMtalB8VgfhEeyOSLcWiNHg2gAAAAAAA*AAAAAAA*AAAxGnQ2\\ AnjaFHoJNNtSPGZctYAgMAAAF7jBD3yQBPGgDfuTFLefbMq-zYo_n0bU2vGkBNr\\ OFCZGUD-VwNsuv0hw", \\ "application": "a7436027-8da1-47a0-934d-b523c665cb58",\\ "expires_in": 5183999}|access_token：获取到的token;\\ expires_in：token过期时间，单位：秒;\\ application：当前APP的UUID|
==== 示例 ====
=== 请求示例 ===
<code>
curl --location --request POST '{api}/openapi/rm/app/token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appClientId":"YXA6p0NgJ42hR6CTTbUjxmXLWA",
    "appClientSecret":"YXA6j5Ie*Td3Nmgf8Y4IvkJ*9L_epPY"
}'
</code>
=== 返回示例 ===
发送成功，access_token参数值即为应用Token，用于后文OpenAPI调用时，添加在头部'Authorization'参数处。
<code>
{
    "code": 200,
    "msg": "success",
    "body": {
        "access_token": "YWMtalB8VgfhEeyOSLcWiNHg2gAAAAAAA*AAAAAAA*AAAxGnQ2AnjaFHoJNNtSPGZctYAgMAAAF7jBD3yQBPGgDfuTFLefbMq-zYo_n0bU2vGkBNrOFCZGUD-VwNsuv0hw",
        "application": "a7436027-8da1-47a0-934d-b523c665cb58",
        "expires_in": 5183999
    }
}
</code>
发送失败
<code>
{
    "code": 400,
    "msg": "app_client_id can not be empty",
    "body": null
}
</code>
==== 错误码 ====
|HTTP Code|错误信息|描述|
|400|app_client_id can not be empty|appClientId不能为空|
|400|app_client_secret can not be empty|appClientSecret不能为空|
|400|app_client_id does not match|appid与参数不匹配|
|404|page not found|接口未找到|
|500|fail|MQTT后端服务异常，请重试|

===== 申请用户访问Token =====
==== 使用场景 ====
当客户端登录环信MQTT消息云时，服务器会根据客户端设置的用户名及Token参数进行鉴权，鉴权成功后方可登录收发消息。但由于客户端产品形态及业务需求不同，选择Token的类型不同，MQTT消息云支持以下两种Token类型，可根据实际场景进行获取。
^方式^长度^使用场景^不同点^相同点^
| MQTT Token \\ （推荐）|27位|适用所有场景使用，推荐使用MQTT Token|1、无100个用户账号限制，可由用户自行创建\\ 及管理用户账号； \\ 2、Token有效期默认3天，且最大值默认3天，\\ 如需提高最大有效期，可提工单联系我们进行扩展；|为方便用户调用，调用接口及\\ 调用流程相同，仅传入参数不同|
| IM Token|130位|仅适用使用 环信IM + MQTT服务 场景|1、IM免费版有100个用户账号限制，如需增加注册\\ 用户数，需要开通IM专业版； \\ 2、Token有效期可调，支持在环信console后台配置；|:::|


==== MQTT Token（推荐）====
=== 请求说明  ===
== 请求方法：POST ==
== URL ：{api}/openapi/rm/user/token ==
''其中{api}通过console后台【服务概览】->【服务配置】->【REST API地址】获取''
== 请求参数：JSON格式 ==
^参数名称^类型^是否必选^示例^说明^
| username|String|是|"test1"|用户名，支持用户自定义|
| expires_in |Long|否|1000|token过期时间，单位：秒，设置后只对MQTT Token有效，对IM Token无效 \\ 默认值为3天，且最大有效期为3天，如需调整最大有效期，可提工单联系我们进行调整|
| cid| String|否|“aaa@PUDDJL”|客户端唯一标识（clientID），若不传此参数，则任意client ID可使用返回的Token值进行登录；\\ 若传入此参数，则仅当前clientID使用返回的Token值进行登录，推荐传入clientID（提高安全性）|

=== 返回参数 ===
|参数名称|类型|示例|说明|
|code|Integer|200|200：获取成功；400：获取失败|
|msg|String|“success”或“fail”|success：获取成功；fail：获取失败|
| body |Object|{"access_token": "A9fFmJnF21KKt7NzCacLrS5fVE9","expires_in": 86400,\\ "user": {"type": "user","created": 1642661174438,\\ "username": "test1","activated": true}|access_token：获取到的token;\\ expires_in：token过期时间，单位：秒;\\ user：token用户信息|
=== 示例 ===
== 请求示例 ==
在头部'Authorization'参数处填写应用Token。
<code>
curl --location --request POST 'https://{api}/openapi/rm/user/token' \
--header 'Authorization: YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF7TR3OGgBPGgA_9THIQ1jPM2V_QOnTifJjaYo3RSTrGdJWTbSYuXs8ng' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username":"test1",
    "cid":"test1@ff6sc0"
}'
</code>
=== 返回示例 ===
发送成功，access_token参数值即为临时访问Token，用于MQTT 客户端登录时使用。
<code>
{
    "code": 200,
    "msg": "success",
    "body": {
        "access_token": "A9fFmJnF21KKt7NzCacLrS5fVE9",
        "expires_in": 86400,
        "user": {
            "type": "user",
            "created": 1642661174438,
            "username": "test1",
            "activated": true
        }
    }
}
</code>
发送失败
<code>
{
    "code": 403,
    "msg": "access deny"
}
</code>
==== IM Token====
=== 请求说明  ===
== 请求方法：POST ==
== URL ：{api}/openapi/rm/user/token ==
''其中{api}通过console后台【服务概览】->【服务配置】->【REST API地址】获取''
== 请求参数：JSON格式 ==
^参数名称^类型^是否必选^示例^说明^
| username|String|是|"test1"|用户名，从console中创建，从下图中获取|
| password|String|是|"123456"|密码，从console中创建，从下图中获取|
{{:playground:message:restapi2.jpg|}}

=== 返回参数 ===
|参数名称|类型|示例|说明|
|code|Integer|200|200：获取成功；400：获取失败|
|msg|String|“success”或“fail”|success：获取成功；fail：获取失败|
| body |Object|{ "access_token": "YWMtUZGwvgflEeyyUy3dfJj94pQyzTkCwEDFvGStdtTJYgh\\ jRxwA-n4R66DLu1M1Pt52AwMAAAF7jCqMgQBPGgBS4rWm\\ SUM2lroXf5Zm6qq5y0pSiGAUdzcfP-uKt4J4VQ", \\  "expires_in": 5183999,  \\ "user": { "created": 1628670630341, \\ "modified": 1628670630341,\\  "type": "user",\\  "uuid": "63471c00-fa7e-11eb-a0cb-bb53353ede76", \\ "username": "test1", \\ "activated": true } }|access_token：获取到的token;\\ expires_in：token过期时间，单位：秒;\\ user：token用户信息|
=== 示例 ===
== 请求示例 ==
在头部'Authorization'参数处填写应用Token。
<code>
curl --location --request POST 'https://{api}/openapi/rm/user/token' \
--header 'Authorization: YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF7TR3OGgBPGgA_9THIQ1jPM2V_QOnTifJjaYo3RSTrGdJWTbSYuXs8ng' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username":"test1",
    "password":"123456"
}'
</code>
=== 返回示例 ===
发送成功，access_token参数值即为临时访问Token，用于MQTT 客户端登录时使用。
<code>
{
    "code": 200,
    "msg": "success",
    "body": {
        "access_token": "YWMtUZGwvgflEeyyUy3dfJj94pQyzTkCwEDFvGStdtTJYghjRxwA-n4R66DLu1M1Pt52AwMAAAF7jCqMgQBPGgBS4rWmSUM2lroXf5Zm6qq5y0pSiGAUdzcfP-uKt4J4VQ",
        "expires_in": 5183999,
        "user": {
            "created": 1628670630341,
            "modified": 1628670630341,
            "type": "user",
            "uuid": "63471c00-fa7e-11eb-a0cb-bb53353ede76",
            "username": "test1",
            "activated": true
        }
    }
}
</code>
发送失败
<code>
{
    "code": 400,
    "msg": "username and password don't match",
    "body": null
}
</code>
==== 错误码 ====
|HTTP Code|错误信息|描述|
|403|access deny|鉴权失败|
|404|page not found|接口未找到|
|400|username can not be empty|当获取IM token时，用户名不能为空|
|400|password can not be empty|当获取IM token时，密码不能为空|
|400|username and password don't match|用户名密码不匹配|
|400|expires_in should be greater than 60 seconds|过期时间必须大于60秒|
|500|fail|MQTT后端服务异常，请重试。|

===== 发送消息 =====
==== 使用场景 ====
当不通过SDK，需要直接调用REST接口发消息。
==== 请求说明 ====
=== 请求方法：POST ===
=== URL ：{api}/openapi/v1/rm/chat/publish ===
''其中{api}通过console后台【服务概览】->【服务配置】->【REST API地址】获取''
=== 请求参数：JSON格式 ===
^参数名称^类型^是否必选^示例^说明^
| topics|String|是|{"topic1","topic2"}|要发消息的主题数组|
| clientid|String|是|"123456"|发送者的clientId，由“{deviceID}@{AppID}”组成，其中{deviceID}\\ 由用户自定义，{AppID}从console获取，长度不能超过64个字符|
| payload|String|是|“{'msg':'123'}”|消息内容，支持json、xml、raw类型|
| encoding|String|否|"base64"|消息体编码方式，支持 plain 与 base64 两种，默认为 plain|
| qos|Integer|否|0|QoS等级，默认为0|
| retain|Integer|否|1|是否保留消息，0：不保留，1：保留，默认为0|
| expire|Integer|否|86400|消息最大保留时间，单位：秒，取值范围：[86400,259200]|
==== 返回参数 ====
|参数名称|类型|示例|说明|
|code|Integer|200|200：获取成功；400：获取失败|
|msg|String|“success”或“fail”|success：发送成功；fail：发送失败|
| body |Object|{ "mids": [ "04D2B21648002000", "04D2B21648002001" ] }|mids：发送的消息ID|
==== 示例 ====
=== 请求示例 ===
在头部'Authorization'参数处填写【应用Token】。
<code>
curl --location --request POST '{api}/v1/rm/chat/publish' \
--header 'Authorization: YWMtPagaGPM-Eeu5Mzk9hiiWfgAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF7BNEn6ABPGgBVf-sfXGMI4tdN624julbYH2g5lGv-vc79hOGX7T64xQ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "clientid": "clientid0@wyq7c0",
    "payload": "",
    "retain": 0,
    "topics": ["msg", "ll"],
    "expire": 28000,
    "encoding":"base64",
    "qos":0
}
'
</code>
=== 返回示例 ===
发送成功
<code>
{
    "code": 200,
    "msg": "success",
    "body": {
        "mids": [
            "04D2B21648002000",
            "04D2B21648002001"
        ]
    }
}
</code>
发送失败
<code>
{
    "code": 400,
    "msg": "clientid and appid doesn't match",
    "body": {}
}
</code>
==== 错误码 ====
|HTTP Code|错误信息|描述|
|403|access deny|鉴权失败|
|404|page not found|接口未找到|
|400|the appid cannnot use the service|当前appid未开通MQTT服务|
|400|clientid can not be empty|clientid不能为空|
|400|invalid clientid|clientid不合法|
|400|clientid and appid doesn't match|clientid和appid不匹配|
|400|topics array can not be empty|topics不能为空|
|400|topics must be an array|topics必须是数组|
|400|topics array's size can not exceed 32|topics数量不能超过32个|
|400|payload can not be empty|payload不能为空|
|400|bad base64 payload type|planeload不是base64格式|
|400|invalid qos|qos不合法|
|500|fail|MQTT后端服务异常，请重试。|
|400|bad_json|json格式错误|
|400|error_topics_format|主题名称不合法|
|400|payload_too_larger|payload太大|
|400|Missing required parameters +“缺少信息”|提示缺少必要参数|
===== 获取客户端连接记录 =====
==== 使用场景 ====
当不通过SDK，需要获取MQTT 客户端的连接记录。
==== 请求说明 ====
=== 请求方法：GET ===
=== URL ：{api}/openapi/rm/device/record ===
''其中{api}通过console后台【服务概览】->【服务配置】->【REST API地址】获取''
=== 请求参数：URL参数 ===
^参数名称^类型^是否必选^示例^说明^
|clientid|String|是|"clientid0@wyq7c0"|待查询的Clientid，由“{deviceID}@{AppID}”组成，其中{deviceID}由用户自定义，{AppID}在console后台的【MQTT】→ \\ 【服务概览】→【服务配置】下的‘AppID’获取|
|beginTime|String|是|2021-08-20 15:00:00|查询起始时间|
|endTime|String|是|2021-08-28 15:00:00|查询结束时间|
|currentPage|Integer|否|1|当前页码，默认1|
|pageSize|Integer|否|10|分页大小，默认10|
==== 返回参数 ====
|参数名称|类型|示例|说明|
|code|Integer|200|200：获取成功；400：获取失败|
|msg|String|“success”或“fail”|success：发送成功；fail：发送失败|
| body |Object|{"data": [{"connid": "04D2C1DD8B002000",\\  "ts": "2021-08-28 18:23:09.718",\\  "status": "connect", \\ "reason": "normal",\\  "detail": "{'will_properties':{},\\ 'will':null,\\ 'version':4,\\ 'ts':1630146189718,\\ 'properties':{},\\ 'network':'mod_mqtt_ws',\\ 'keep_alive':60,\\ 'ip':'::ffff:172.18.1.24:21258',\\ 'clean_start':true}"}], \\ "totalCount": 1}|totalCount：记录总数；\\ ts：记录发生时间；\\ status：记录状态；\\ reason：记录发生原因；\\ detail：记录详情|
==== 示例 ====
=== 请求示例 ===
在头部'Authorization'参数处填写【应用Token】。
<code>
curl --location --request GET '{api}/openapi/rm/device/record?clientid=abc@a0cta0&beginTime=2021-08-20 15:00:00&endTime=2021-08-28 19:00:00' \
--header 'Authorization: YWMtIK2PluhKEeuXN8fXrcb52AAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF6vQgeoABPGgCEPLoPV9_8vVYrVCVYvy7Jfd-2O6sBEDI4FdLjXVzLCw'
</code>
=== 返回示例 ===
查询成功
<code>
{
    "code": 200,
    "msg": "success",
    "body": {
        "data": [
            {
                "connid": "04D2C1DD8B002000",
                "ts": "2021-08-28 18:23:09.718",
                "status": "connect",
                "reason": "normal",
                "detail": "{\"will_properties\":{},\"will\":null,\"version\":4,\"ts\":1630146189718,\"properties\":{},\"network\":\"mod_mqtt_ws\",\"keep_alive\":60,\"ip\":\"::ffff:172.18.1.24:21258\",\"clean_start\":true}"
            }
        ],
        "totalCount": 1
    }
}
</code>
查询失败
<code>
{
    "code": 400,
    "msg": "clientid and appid doesn't match",
    "body": null
}
</code>
==== 错误码 ====
|HTTP Code|错误信息|描述|
|403|access deny|鉴权失败|
|404|page not found|接口未找到|
|400|clientid can not be empty|clientid不能为空|
|400|invalid clientid|clientid不合法|
|400|clientid and appid doesn't match|clientid和appid不匹配|
|400|beginTime and endTime can not be empty|beginTime和endTime不能为空|
|400|end time must be greater than the start time|endTime必须大于beginTime|
|500|fail|MQTT后端服务异常，请重试。|

===== 获取客户端session信息 =====
==== 使用场景 ====
当不通过SDK，需要根据Client ID获取指定客户端的连接信息时。
==== 请求说明 ====
=== 请求方法：GET ===
=== URL ：{api}/openapi/rm/broker/clientInfo ===
''其中{api}通过console后台【服务概览】->【服务配置】->【REST API地址】获取''
=== 请求参数：URL参数 ===
^参数名称^类型^是否必选^示例^说明^
|clientid|String|是|"deviceId1@vwp0b0"|待查询的Clientid，由“{deviceID}@{AppID}”组成，其中{deviceID}由用户自定义，{AppID}在console后台的【MQTT】→ 【服务概览】→【服务配置】下的‘AppID’获取|
|currentPage|Integer|否|1|当前页码，默认1|
|pageSize|Integer|否|10|分页大小，默认10|
==== 返回参数 ====
|参数名称|类型|示例|说明|
|code|Integer|200|200：获取成功；400：获取失败|
|msg|String|“success”或“fail”|success：发送成功；fail：发送失败|
| body |Object|{"status": "online", \\ "time": "1630147122103", \\ "user": "test1",\\  "keepalive": 60, "cleansession": true,\\  "will": null,\\  "version": 4, \\ "dataobject": [ { "topic": "testtopic/a", \\ "qos": 0 }  ], \\ "pageSize": 10,\\  "currentPage": 1,\\  "total": 1  }|status：在线状态，online为在线，offline为离线；\\ time：最新连接时间；\\ user：当前登录使用的用户ID；\\ keepalive：心跳间隔；\\ cleansession：是否清除会话，true：清除，false：不清除；\\ will：是否遗嘱消息，true：是，false：否；\\ version：MQTT版本；\\ pageSize：订阅主题页面大小；\\ currentPage：订阅主题当前页；\\ total：总条数；\\ topic：订阅的主题名称；\\ qos：设置的QoS等级|
==== 示例 ====
=== 请求示例 ===
在头部'Authorization'参数处填写【应用Token】。
<code>
curl --location --request GET '{api}/openapi/rm/broker/clientInfo?clientid=abc@a0cta0' \
--header 'Authorization: YWMtIK2PluhKEeuXN8fXrcb52AAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF6vQgeoABPGgCEPLoPV9_8vVYrVCVYvy7Jfd-2O6sBEDI4FdLjXVzLCw'
</code>
=== 返回示例 ===
 查询成功
<code>
{
    "code": 200,
    "msg": "success",
    "body": {
        "clientID": null,
        "status": "online",
        "time": "1630147122103",
        "user": "test1",
        "keepalive": 60,
        "cleansession": true,
        "will": null,
        "version": 4,
        "dataobject": [
            {
                "topic": "testtopic/a",
                "qos": 0
            }
        ],
        "pageSize": 10,
        "currentPage": 1,
        "total": 1
    }
}
</code>
查询失败
<code>
{
    "code": 400,
    "msg": "clientId doesn't exist",
    "body": null
}
</code>
==== 错误码 ====
|HTTP Code|错误信息|描述|
|403|access deny|鉴权失败|
|404|page not found|接口未找到|
|400|clientid can not be empty|clientid不能为空|
|400|invalid clientid|clientid不合法|
|400|clientid and appid doesn't match|clientid和appid不匹配|
|500|fail|MQTT后端服务异常，请重试。|
===== 获取客户端消息发送&投递记录 =====
==== 使用场景 ====
当不通过SDK，需要获取指定客户端消息发送与投递记录时。
==== 请求说明 ====
=== 请求方法：GET ===
=== URL ：{api}/openapi/rm/message/record ===
''其中{api}通过console后台【服务概览】->【服务配置】->【REST API地址】获取''
=== 请求参数：URL参数 ===
^参数名称^类型^是否必选^示例^说明^
|clientid|String|是|"deviceId1@vwp0b0"|待查询的Clientid，由“{deviceID}@{AppID}”组成，其中{deviceID}由用户自定义，{AppID}在console后台的【MQTT】→ 【服务概览】→【服务配置】下的‘AppID’获取|
|beginTime|String|是|2021-08-26 10:00:00|查询起始时间|
|endTime|String|是|2021-08-26 15:00:00|查询结束时间|
|currentPage|Integer|否|1|当前页码，默认1|
|pageSize|Integer|否|10|分页大小，默认10|
|order|String|否|ASC|取值：“ASC”升序，“DESC”降序|
==== 返回参数 ====
|参数名称|类型|示例|说明|
|code|Integer|200|200：获取成功；400：获取失败|
|msg|String|“success”或“fail”|success：发送成功；fail：发送失败|
| body |Object|{ "data": [ { "ts": "2021-08-28 18:56:18.957",\\  "mid": "04D2E037FA002000", \\ "cid": "test@a0cta0", \\ "direction": "downlink" }, \\ { "ts": "2021-08-28 18:56:18.938", \\ "mid": "04D2E037FA002000", \\ "cid": "test@a0cta0", \\ "direction": "uplink" } ],\\  "totalCount": 3 }|ts：消息发送/接收时间；\\ mid：消息ID；\\ cid：客户端ID；\\ direction：消息上行/下行，上行：uplink，下行：downlink|
==== 示例 ====
=== 请求示例 ===
在头部'Authorization'参数处填写【应用Token】。
<code>
curl --location --request GET '{api}/openapi/rm/message/record?clientid=test@a0cta0&beginTime=2021-08-28 01:01:01&endTime=2021-08-28 19:01:01&order=desc' \
--header 'Authorization: YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF7TR3OGgBPGgA_9THIQ1jPM2V_QOnTifJjaYo3RSTrGdJWTbSYuXs8ng'
</code>
=== 返回示例 ===
查询成功
<code>
{
    "code": 200,
    "msg": "success",
    "body": {
        "data": [
            {
                "ts": "2021-08-28 18:56:18.957",
                "mid": "04D2E037FA002000",
                "cid": "test@a0cta0",
                "direction": "downlink"
            },
            {
                "ts": "2021-08-28 18:56:18.938",
                "mid": "04D2E037FA002000",
                "cid": "test@a0cta0",
                "direction": "uplink"
            },
            {
                "ts": "2021-08-28 18:56:10.918",
                "mid": "04D2E018A6002000",
                "cid": "test@a0cta0",
                "direction": "uplink"
            }
        ],
        "totalCount": 3
    }
}
</code>
查询失败
<code>
{
    "code": 400,
    "msg": "clientid and appid doesn't match",
    "body": null
}
</code>
==== 错误码 ====
|HTTP Code|错误信息|描述|
|403|access deny|鉴权失败|
|404|page not found|接口未找到|
|400|clientid can not be empty|clientid不能为空|
|400|invalid clientid|clientid不合法|
|400|clientid and appid doesn't match|clientid和appid不匹配|
|400|beginTime and endTime can not be empty|beginTime和endTime不能为空|
|400|end time must be greater than the start time|endTime必须大于beginTime|
|500|fail|MQTT后端服务异常，请重试。|
===== 获取指定消息的发送记录 =====
==== 使用场景 ====
当不通过SDK，需要获取指定消息的发送记录时。
==== 请求说明 ====
=== 请求方法：GET ===
=== URL ：{api}/openapi/rm/message/publish ===
''其中{api}通过console后台【服务概览】->【服务配置】->【REST API地址】获取''
=== 请求参数：URL参数 ===
^参数名称^类型^是否必选^示例^说明^
|clientid|String|是|"test@a0cta0"|待查询的Clientid，由“{deviceID}@{AppID}”组成，其中{deviceID}由用户自定义，{AppID}在console后台的【MQTT】→ 【服务概览】→【服务配置】下的‘AppID’获取|
|messageid|String|是|"04D2E037FA002000"|指定的消息ID|
|order|String|否|DESC|取值：“ASC”升序，“DESC”降序|

==== 返回参数 ====
|参数名称|类型|示例|说明|
|code|Integer|200|200：获取成功；400：获取失败|
|msg|String|“success”或“fail”|success：发送成功；fail：发送失败|
| body |Object|{ "data": [ { "connid": "04D2E010D6002000", \\ "ts": "2021-08-28 18:56:18.938", \\ "mid": "04D2E037FA002000",\\  "cid": "test@a0cta0",\\  "status": "normal",\\  "topic": "testtopic/a",\\  "qos": 0 } ], \\ "totalCount": 1 }|ts：消息发送时间；\\ mid：消息ID；\\ cid：发送客户端ID；\\ status：状态；\\ topic：消息发送主题；\\ qos：消息qos等级|

==== 示例 ====
=== 请求示例 ===
在头部'Authorization'参数处填写【应用Token】。
<code>
curl --location --request GET '{api}/openapi/rm/message/publish?clientid=test@a0cta0&messageid=04D2E037FA002000&beginTime=2021-08-28 01:01:01&endTime=2021-08-28 19:01:01' \
--header 'Authorization: YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF7TR3OGgBPGgA_9THIQ1jPM2V_QOnTifJjaYo3RSTrGdJWTbSYuXs8ng'
</code>
=== 返回示例 ===
查询成功
<code>
{
    "code": 200,
    "msg": "success",
    "body": {
        "data": [
            {
                "connid": "04D2E010D6002000",
                "ts": "2021-08-28 18:56:18.938",
                "mid": "04D2E037FA002000",
                "cid": "test@a0cta0",
                "status": "normal",
                "topic": "testtopic/a",
                "qos": 0
            }
        ],
        "totalCount": 1
    }
}
</code>
查询失败
<code>
{
    "code": 400,
    "msg": "clientid and appid doesn't match",
    "body": null
}
</code>

==== 错误码 ====
|HTTP Code|错误信息|描述|
|403|access deny|鉴权失败|
|404|page not found|接口未找到|
|400|clientid can not be empty|clientid不能为空|
|400|invalid clientid|clientid不合法|
|400|clientid and appid doesn't match|clientid和appid不匹配|
|400|messageid can not be empty|messageid不能为空|
|500|fail|MQTT后端服务异常，请重试。|
===== 获取指定消息的投递记录 =====
==== 使用场景 ====
当不通过SDK，需要获取指定消息的投递记录时。
==== 请求说明 ====
=== 请求方法：GET ===
=== URL ：{api}/openapi/rm/message/subscribe ===
''其中{api}通过console后台【服务概览】->【服务配置】->【REST API地址】获取''
=== 请求参数：URL参数 ===
^参数名称^类型^是否必选^示例^说明^
|clientid|String|是|"test@a0cta0"|待查询的Clientid，由“{deviceID}@{AppID}”组成，其中{deviceID}由用户自定义，{AppID}在console后台的【MQTT】→ 【服务概览】→【服务配置】下的‘AppID’获取|
|messageid|String|是|"04D2E037FA002000"|指定的消息ID|
|beginTime|String|是|2021-08-26 15:00:00|查询起始时间|
|endTime|String|是|2021-08-28 13:00:00|查询结束时间|
|currentPage|Integer|否|1|当前页码，默认1|
|pageSize|Integer|否|10|分页大小，默认10|
|order|String|否|DESC|取值：“ASC”升序，“DESC”降序|
==== 返回参数 ====
|参数名称|类型|示例|说明|
|code|Integer|200|200：获取成功；400：获取失败|
|msg|String|“success”或“fail”|success：发送成功；fail：发送失败|
| body |Object|{ "data": [ { "ts": "2021-08-28 18:56:18.957", \\ "cid": "test@a0cta0",\\  "status": "normal", \\ "qos": 0 } ], \\ "totalCount": 1 }|ts：消息发送时间；\\ cid：发送客户端ID；\\ status：状态；\\  qos：消息qos等级|
==== 示例 ====
=== 请求示例 ===
在头部'Authorization'参数处填写【应用Token】。
<code>
curl --location --request GET '{api}/openapi/rm/message/subscribe?clientid=test@a0cta0&beginTime=2021-08-27 01:01:01&endTime=2021-08-28 20:01:01&messageid=04D2E037FA002000&order=asc' \
--header 'Authorization: YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF7TR3OGgBPGgA_9THIQ1jPM2V_QOnTifJjaYo3RSTrGdJWTbSYuXs8ng'
</code>
=== 返回示例 ===
查询成功
<code>
{
    "code": 200,
    "msg": "success",
    "body": {
        "data": [
            {
                "ts": "2021-08-28 18:56:18.957",
                "cid": "test@a0cta0",
                "status": "normal",
                "qos": 0
            }
        ],
        "totalCount": 1
    }
}
</code>
查询失败
<code>
{
    "code": 400,
    "msg": "clientid and appid doesn't match",
    "body": null
}
</code>
==== 错误码 ====
|HTTP Code|错误信息|描述|
|403|access deny|鉴权失败|
|404|page not found|接口未找到|
|400|clientid can not be empty|clientid不能为空|
|400|invalid clientid|clientid不合法|
|400|clientid and appid doesn't match|clientid和appid不匹配|
|400|messageid can not be empty|messageid不能为空|
|400|beginTime and endTime can not be empty|beginTime和endTime不能为空|
|400|end time must be greater than the start time|endTime必须大于beginTime|
|500|fail|MQTT后端服务异常，请重试。|

===== 获取指定消息内容 =====
==== 使用场景 ====
通过REST API接口，可以传入指定消息ID获取该消息的具体内容。

==== 请求说明 ====
=== 请求方法：GET ===
=== URL ：{api}/openapi/rm/message/message ===
''其中{api}通过console后台【服务概览】->【服务配置】->【REST API地址】获取''
=== 请求参数：URL参数 ===
^参数名称^类型^是否必选^示例^说明^
|messageId|String|是|"04D2E037FA002000"|指定的消息ID|
|encode|String|否|"base64"|消息内容的编码，取值："base64"、"utf-8"，默认"base64"|
==== 返回参数 ====
|参数名称|类型|示例|说明|
|code|Integer|200|200：获取成功；400：获取失败|
|msg|String|“success”或“fail”|success：发送成功；fail：发送失败|
| body |Object|"body": {"messageId": "06D993BBC700A000", \\ "clientId": "acb@vwp0b0", \\ "connectionId": "0000000000000000", \\ "qos": 0, "topic": "ddd", \\ "publishTimeText": "2021-12-07 12:15:41",\\  "message": "ZHNmc2Zk" } }|messageId：消息id；\\ clientId：发送客户端ID；\\ connectionId：连接ID；\\  qos：消息qos等级；\\ topic：订阅主题；\\ publishTimeText：发布时间（格式化）；\\  message：编码后的消息内容|
==== 示例 ====
=== 请求示例 ===
在头部'Authorization'参数处填写【应用Token】。
<code>
curl --location --request GET '{api}/openapi/rm/message/message?messageId=06D993BBC700A000' \
--header 'Authorization: YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF7TR3OGgBPGgA_9THIQ1jPM2V_QOnTifJjaYo3RSTrGdJWTbSYuXs8ng'
</code>
=== 返回示例 ===
查询成功
<code>
{
    "code": 200,
    "msg": "success",
    "body": {
        "messageId": "06D993BBC700A000",
        "clientId": "acb@vwp0b0",
        "connectionId": "0000000000000000",
        "qos": 0,
        "topic": "ddd",
        "publishTimeText": "2021-12-07 12:15:41",
        "message": "ZHNmc2Zk"
    }
}
</code>
查询失败
<code>
{
    "code": 403,
    "msg": "access deny"
}
</code>
==== 错误码 ====
|HTTP Code|错误信息|描述|
|403|access deny|鉴权失败|
|404|page not found|接口未找到|
|400|messageId cannot be empty|messageId不能为空|
|400|encode can only be utf-8 or base64|编码只能为utf-8或base64|
|500|fail|MQTT后端服务异常，请重试。|


===== 获取指定topic的上行历史消息记录 =====
==== 使用场景 ====
通过REST API接口，可以获取指定topic某个时间段内的上行历史消息记录。

==== 请求说明 ====
=== 请求方法：GET ===
=== URL ：{api}/openapi/rm/message/messages ===
''其中{api}通过console后台【服务概览】->【服务配置】->【REST API地址】获取''
=== 请求参数：URL参数 ===
^参数名称^类型^是否必选^示例^说明^
| beginTime |String|是|"2021-12-07 00:00:00"|查询起始时间|
| endTime |String|是|"2021-12-07 23:00:00"|查询截止时间|
| topic | String|是|"ddd"|消息主题|
| pageSize | Integer |否|10|分页大小，默认10|
| currentPage | Integer |否|1|当前页码，默认1|
|encode|String|否|"base64"|消息内容的编码，取值："base64"、"utf-8"，默认"base64"|
==== 返回参数 ====
|参数名称|类型|示例|说明|
|code|Integer|200|200：获取成功；400：获取失败|
|msg|String|“success”或“fail”|success：发送成功；fail：发送失败|
| body |Object|"body": {"total": 1, "messages":\\  [{ "messageId": "06D9A2AAF8006000", \\ "clientId": "acb@vwp0b0",  \\ "connectionId": "0000000000000000", \\ "qos": 0, "topic": "ddd", \\ "publishTimeText": "2021-12-07 12:32:00",\\  "message": "ZHNmc2Zk" } ] } }|messageId：消息id；\\ clientId：发送客户端ID；\\ connectionId：连接ID；\\  qos：消息qos等级；\\ topic：订阅主题；\\ publishTimeText：发布时间（格式化）；\\  message：编码后的消息内容；\\ total：消息总数；|
==== 示例 ====
=== 请求示例 ===
在头部'Authorization'参数处填写【应用Token】。
<code>
curl --location --request GET '{api}/openapi/rm/message/messages?beginTime=2021-12-07 00:00:00&endTime=2021-12-07 23:00:00&topic=ddd&pageSize=10&currentPage=1' \
--header 'Authorization: YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF7TR3OGgBPGgA_9THIQ1jPM2V_QOnTifJjaYo3RSTrGdJWTbSYuXs8ng'
</code>
=== 返回示例 ===
查询成功
<code>
{
    "code": 200,
    "msg": "success",
    "body": {
        "total": 2,
        "messages": [
            {
                "messageId": "06D9A2AAF8006000",
                "clientId": "acb@vwp0b0",
                "connectionId": "0000000000000000",
                "qos": 0,
                "topic": "ddd",
                "publishTimeText": "2021-12-07 12:32:00",
                "message": "ZHNmc2Zk"
            },
            {
                "messageId": "06D993BBC700A000",
                "clientId": "acb@vwp0b0",
                "connectionId": "0000000000000000",
                "qos": 0,
                "topic": "ddd",
                "publishTimeText": "2021-12-07 12:15:41",
                "message": "ZHNmc2Zk"
            }
        ]
    }
}
</code>
查询失败
<code>
{
    "code": 403,
    "msg": "access deny"
}
</code>
==== 错误码 ====
|HTTP Code|错误信息|描述|
|403|access deny|鉴权失败|
|404|page not found|接口未找到|
|400|messageId cannot be empty|messageId不能为空|
|400|encode can only be utf-8 or base64|编码只能为utf-8或base64|
|500|fail|MQTT后端服务异常，请重试。|

===== 获取指定主题的在线客户端列表 =====
==== 使用场景 ====
根据channel/topic获取当前在线客户端列表。
==== 请求说明 ====
=== 请求方法：GET ===
=== URL ：{api}/openapi/rm/users/topic ===
''其中{api}通过console后台【服务概览】->【服务配置】->【REST API地址】获取''
=== 请求参数：URL参数 ===
^参数名称^类型^是否必选^示例^说明^
| topic | String|是|"a,b"|主题，支持获取多个主题，多个主题之间用','分隔|
| pageSize | Integer |否|10|分页大小，默认10|
| currentPage | Integer |否|1|当前页码，默认1|

==== 返回参数 ====
|参数名称|类型|示例|说明|
|code|Integer|200|200：获取成功；400：获取失败|
|msg|String|“success”或“fail”|success：发送成功；fail：发送失败|
| body |Object|"body": {"total": 1, "data": \\ [ { "clientId": "deviceId1@vwp0b0",\\  "userid": "vimin1", \\ "keepalive": 60, \\ "protocol": "ws", \\ "conntime": "2021-12-07 12:45:37",\\  "topic": "b", "version": 4, \\ "connid": "06D9AEA3CB007001" } ] }|clientId：发送客户端ID；\\ userid：用户ID；\\ keepalive：心跳时间；\\ protocol：协议； \\ conntime：连接时间；\\ topic：主题名称；\\ version：版本号；\\ connid：连接ID；\\ total：当前在线客户端总数；|


==== 示例 ====
=== 请求示例 ===
在头部'Authorization'参数处填写【应用Token】。

=== 返回示例 ===
查询成功
<code>
{
    "code": 200,
    "msg": "success",
    "body": {
        "total": 2,
        "data": [
            {
                "clientId": "deviceId1@vwp0b0",
                "userid": "vimin1",
                "keepalive": 60,
                "protocol": "ws",
                "conntime": "2021-12-07 12:45:37",
                "topic": "b",
                "version": 4,
                "connid": "06D9AEA3CB007001"
            },
            {
                "clientId": "deviceId1@vwp0b0",
                "userid": "vimin1",
                "keepalive": 60,
                "protocol": "ws",
                "conntime": "2021-12-07 12:45:34",
                "topic": "a",
                "version": 4,
                "connid": "06D9AEA3CB007001"
            }
        ]
    }
}
</code>
查询失败
<code>
{
    "code": 200,
    "msg": "success",
    "body": {
        "total": 0,
        "data": []
    }
}
</code>
==== 错误码 ====
|HTTP Code|错误信息|描述|
|403|access deny|鉴权失败|
|404|page not found|接口未找到|
|400|topic cannot be empty|topic不能为空|
|500|fail|MQTT后端服务异常，请重试。|




===== 获取指定用户ID的在线客户端列表 =====
==== 使用场景 ====
根据用户ID/用户名获取当前在线客户端列表。
==== 请求说明 ====
=== 请求方法：GET ===
=== URL ：{api}/openapi/rm/users/userid ===
''其中{api}通过console后台【服务概览】->【服务配置】->【REST API地址】获取''
=== 请求参数：URL参数 ===
^参数名称^类型^是否必选^示例^说明^
| userid | String|是|"vimin1,vimin2"|用户ID，支持获取多个用户ID，多个用户ID之间用','分隔|
| pageSize | Integer |否|10|分页大小，默认10|
| currentPage | Integer |否|1|当前页码，默认1|

==== 返回参数 ====
|参数名称|类型|示例|说明|
|code|Integer|200|200：获取成功；400：获取失败|
|msg|String|“success”或“fail”|success：发送成功；fail：发送失败|
| body |Object|"body": { "total": 1, "data": \\ [ { "clientId": "deviceId1@vwp0b0", \\ "userid": "vimin1",  \\ "conntime": "2021-12-07 12:55:01",\\  "keepalive": 60, \\ "version": 4, \\ "protocol": "ws",\\  "connid": "06D9B7BEB5006001" } ] }|clientId：发送客户端ID；\\ userid：用户ID；\\ conntime：连接时间；\\ keepalive：心跳时间；\\  version：版本号；\\ protocol：协议；\\ connid：连接ID；\\ total：当前在线客户端总数；|

==== 示例 ====
=== 请求示例 ===
在头部'Authorization'参数处填写【应用Token】。
<code>
curl --location --request GET '{api}/openapi/rm/users/userid?userid=vimin1&pageSize=10&currentPage=1' \
--header 'Authorization: YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF7TR3OGgBPGgA_9THIQ1jPM2V_QOnTifJjaYo3RSTrGdJWTbSYuXs8ng'
</code>
=== 返回示例 ===
查询成功
<code>
{
    "code": 200,
    "msg": "success",
    "body": {
        "total": 1,
        "data": [
            {
                "clientId": "deviceId1@vwp0b0",
                "userid": "vimin1",
                "conntime": "2021-12-07 12:55:01",
                "keepalive": 60,
                "version": 4,
                "protocol": "ws",
                "connid": "06D9B7BEB5006001"
            }
        ]
    }
}
</code>
查询失败
<code>
{
    "code": 200,
    "msg": "success",
    "body": {
        "total": 0,
        "data": []
    }
}
</code>
==== 错误码 ====
|HTTP Code|错误信息|描述|
|403|access deny|鉴权失败|
|404|page not found|接口未找到|
|400|userid cannot be empty|userid不能为空|
|500|fail|MQTT后端服务异常，请重试。|


===== 获取应用ID下的在线客户端列表 =====
==== 使用场景 ====
根据应用ID/appid获取当前在线客户端列表。
==== 请求说明 ====
=== 请求方法：GET ===
=== URL ：{api}/openapi/rm/users/appid ===
''其中{api}通过console后台【服务概览】->【服务配置】->【REST API地址】获取''
=== 请求参数：URL参数 ===
^参数名称^类型^是否必选^示例^说明^
| pageSize | Integer |否|10|分页大小，默认10|
| currentPage | Integer |否|1|当前页码，默认1|

==== 返回参数 ====
|参数名称|类型|示例|说明|
|code|Integer|200|200：获取成功；400：获取失败|
|msg|String|“success”或“fail”|success：发送成功；fail：发送失败|
| body |Object|"body": { "total": 1, "data":\\  [ { "clientId": "deviceId1@vwp0b0", \\ "userid": "vimin1", \\ "conntime": "2021-12-07 13:02:12", \\ "keepalive": 60, \\ "cleansession": false,\\  "version": 4, \\ "protocol": "ws",\\  "connid": "06D9BE503D006001" } ] }|clientId：发送客户端ID；\\ userid：用户ID；\\ conntime：连接时间；\\ keepalive：心跳时间；\\  cleansession：是否清除session；\\ version：版本号；\\ protocol：协议；\\ connid：连接ID；\\ total：当前在线客户端总数|

==== 示例 ====
=== 请求示例 ===
在头部'Authorization'参数处填写【应用Token】。
<code>
curl --location --request GET '{api}/openapi/rm/users/appid?pageSize=10&currentPage=1' \
--header 'Authorization: YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF7TR3OGgBPGgA_9THIQ1jPM2V_QOnTifJjaYo3RSTrGdJWTbSYuXs8ng'
</code>
=== 返回示例 ===
查询成功
<code>
{
    "code": 200,
    "msg": "success",
    "body": {
        "total": 1,
        "data": [
            {
                "clientId": "deviceId1@vwp0b0",
                "userid": "vimin1",
                "conntime": "2021-12-07 13:02:12",
                "keepalive": 60,
                "cleansession": false,
                "version": 4,
                "protocol": "ws",
                "connid": "06D9BE503D006001"
            }
        ]
    }
}
</code>
查询失败
<code>
{
    "code": 200,
    "msg": "success",
    "body": {
        "total": 0,
        "data": []
    }
}
</code>
==== 错误码 ====
==== 错误码 ====
|HTTP Code|错误信息|描述|
|403|access deny|鉴权失败|
|404|page not found|接口未找到|
|500|fail|MQTT后端服务异常，请重试。|