REST API

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

接口名称使用场景
获取应用Token当不通过SDK,直接调用openAPI接口时,需要在头部'Authorization'参数设置
应用Token,本接口即可获取应用Token。
申请用户Token直接调用接口获取用户访问Token,用于MQTT 客户端登录时使用。
发送消息直接调用接口向主题发消息,支持向一个或多个主题发送消息。
获取客户端连接记录直接调用接口获取MQTT 客户端的连接记录。
获取客户端session信息直接调用接口根据Client ID获取客户端的连接信息时,包括在线状态、最新
上线时间、登录用户ID、使用版本、订阅关系等
获取客户端消息发送&投递记录直接调用接口获取指定客户端消息发送与投递记录时。
获取指定消息的发送记录直接调用接口获取指定消息的发送记录时。
获取指定消息的投递记录直接调用接口获取指定消息的投递记录时。
获取指定消息内容直接调用接口获取指定消息ID的具体内容。
获取指定topic的上行历史消息记录直接调用接口获取指定topic某个时间段内的上行历史消息记录。
获取指定主题的在线客户端列表根据channel/topic获取当前在线客户端列表。
获取指定用户ID的在线客户端列表根据用户ID/用户名获取当前在线客户端列表。
获取应用ID下的在线客户端列表根据应用ID/appid获取当前在线客户端列表。

使用场景

当不通过SDK,直接调用openAPI接口时,需要在头部'Authorization'参数设置应用Token,本接口即可获取应用Token。

请求说明

请求方法:POST

URL :{api}/openapi/rm/app/token

其中{api}通过console后台【服务概览】→【服务配置】→【REST API地址】获取

请求参数:JSON格式

参数名称类型是否必选示例说明
appClientIdString“YXA6ypREjkbBRTCXNsDYhFpKVw”开发者Client ID,系统生成,从下图中获取
appClientSecretString“YXA6brhCN65pz*y86X9uL63mgeV*90k”开发者密钥,从下图中获取

返回参数

参数名称类型示例说明
codeInteger200200:获取成功;400:获取失败
msgString“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

示例

请求示例

curl --location --request POST '{api}/openapi/rm/app/token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appClientId":"YXA6p0NgJ42hR6CTTbUjxmXLWA",
    "appClientSecret":"YXA6j5Ie*Td3Nmgf8Y4IvkJ*9L_epPY"
}'

返回示例

发送成功,access_token参数值即为应用Token,用于后文OpenAPI调用时,添加在头部'Authorization'参数处。

{
    "code": 200,
    "msg": "success",
    "body": {
        "access_token": "YWMtalB8VgfhEeyOSLcWiNHg2gAAAAAAA*AAAAAAA*AAAxGnQ2AnjaFHoJNNtSPGZctYAgMAAAF7jBD3yQBPGgDfuTFLefbMq-zYo_n0bU2vGkBNrOFCZGUD-VwNsuv0hw",
        "application": "a7436027-8da1-47a0-934d-b523c665cb58",
        "expires_in": 5183999
    }
}

发送失败

{
    "code": 400,
    "msg": "app_client_id can not be empty",
    "body": null
}

错误码

HTTP Code错误信息描述
400app_client_id can not be emptyappClientId不能为空
400app_client_secret can not be emptyappClientSecret不能为空
400app_client_id does not matchappid与参数不匹配
404page not found接口未找到
500failMQTT后端服务异常,请重试

使用场景

当客户端登录环信MQTT消息云时,服务器会根据客户端设置的用户名及Token参数进行鉴权,鉴权成功后方可登录收发消息。但由于客户端产品形态及业务需求不同,选择Token的类型不同,MQTT消息云支持以下两种Token类型,可根据实际场景进行获取。

方式长度使用场景不同点相同点
MQTT Token
(推荐)
27位适用所有场景使用,推荐使用MQTT Token1、无100个用户账号限制,可由用户自行创建
及管理用户账号;
2、Token有效期默认3天,且最大值默认3天,
如需提高最大有效期,可提工单联系我们进行扩展;
为方便用户调用,调用接口及
调用流程相同,仅传入参数不同
IM Token130位仅适用使用 环信IM + MQTT服务 场景1、IM免费版有100个用户账号限制,如需增加注册
用户数,需要开通IM专业版;
2、Token有效期可调,支持在环信console后台配置;

MQTT Token(推荐)

请求说明

请求方法:POST
URL :{api}/openapi/rm/user/token

其中{api}通过console后台【服务概览】→【服务配置】→【REST API地址】获取

请求参数:JSON格式
参数名称类型是否必选示例说明
usernameString“test1”用户名,支持用户自定义
expires_in Long1000token过期时间,单位:秒,设置后只对MQTT Token有效,对IM Token无效
默认值为3天,且最大有效期为3天,如需调整最大有效期,可提工单联系我们进行调整
cid String“aaa@PUDDJL”客户端唯一标识(clientID),若不传此参数,则任意client ID可使用返回的Token值进行登录;
若传入此参数,则仅当前clientID使用返回的Token值进行登录,推荐传入clientID(提高安全性)

返回参数

参数名称类型示例说明
codeInteger200200:获取成功;400:获取失败
msgString“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。

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"
}'

返回示例

发送成功,access_token参数值即为临时访问Token,用于MQTT 客户端登录时使用。

{
    "code": 200,
    "msg": "success",
    "body": {
        "access_token": "A9fFmJnF21KKt7NzCacLrS5fVE9",
        "expires_in": 86400,
        "user": {
            "type": "user",
            "created": 1642661174438,
            "username": "test1",
            "activated": true
        }
    }
}

发送失败

{
    "code": 403,
    "msg": "access deny"
}

IM Token

请求说明

请求方法:POST
URL :{api}/openapi/rm/user/token

其中{api}通过console后台【服务概览】→【服务配置】→【REST API地址】获取

请求参数:JSON格式
参数名称类型是否必选示例说明
usernameString“test1”用户名,从console中创建,从下图中获取
passwordString“123456”密码,从console中创建,从下图中获取

返回参数

参数名称类型示例说明
codeInteger200200:获取成功;400:获取失败
msgString“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。

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"
}'

返回示例

发送成功,access_token参数值即为临时访问Token,用于MQTT 客户端登录时使用。

{
    "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": 400,
    "msg": "username and password don't match",
    "body": null
}

错误码

HTTP Code错误信息描述
403access deny鉴权失败
404page not found接口未找到
400username can not be empty当获取IM token时,用户名不能为空
400password can not be empty当获取IM token时,密码不能为空
400username and password don't match用户名密码不匹配
400expires_in should be greater than 60 seconds过期时间必须大于60秒
500failMQTT后端服务异常,请重试。

使用场景

当不通过SDK,需要直接调用REST接口发消息。

请求说明

请求方法:POST

URL :{api}/openapi/v1/rm/chat/publish

其中{api}通过console后台【服务概览】→【服务配置】→【REST API地址】获取

请求参数:JSON格式

参数名称类型是否必选示例说明
topicsString{“topic1”,“topic2”}要发消息的主题数组
clientidString“123456”发送者的clientId,由“{deviceID}@{AppID}”组成,其中{deviceID}
由用户自定义,{AppID}从console获取,长度不能超过64个字符
payloadString“{'msg':'123'}”消息内容,支持json、xml、raw类型
encodingString“base64”消息体编码方式,支持 plain 与 base64 两种,默认为 plain
qosInteger0QoS等级,默认为0
retainInteger1是否保留消息,0:不保留,1:保留,默认为0
expireInteger86400消息最大保留时间,单位:秒,取值范围:[86400,259200]

返回参数

参数名称类型示例说明
codeInteger200200:获取成功;400:获取失败
msgString“success”或“fail”success:发送成功;fail:发送失败
body Object{ “mids”: [ “04D2B21648002000”, “04D2B21648002001” ] }mids:发送的消息ID

示例

请求示例

在头部'Authorization'参数处填写【应用Token】。

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": 200,
    "msg": "success",
    "body": {
        "mids": [
            "04D2B21648002000",
            "04D2B21648002001"
        ]
    }
}

发送失败

{
    "code": 400,
    "msg": "clientid and appid doesn't match",
    "body": {}
}

错误码

HTTP Code错误信息描述
403access deny鉴权失败
404page not found接口未找到
400the appid cannnot use the service当前appid未开通MQTT服务
400clientid can not be emptyclientid不能为空
400invalid clientidclientid不合法
400clientid and appid doesn't matchclientid和appid不匹配
400topics array can not be emptytopics不能为空
400topics must be an arraytopics必须是数组
400topics array's size can not exceed 32topics数量不能超过32个
400payload can not be emptypayload不能为空
400bad base64 payload typeplaneload不是base64格式
400invalid qosqos不合法
500failMQTT后端服务异常,请重试。
400bad_jsonjson格式错误
400error_topics_format主题名称不合法
400payload_too_largerpayload太大
400Missing required parameters +“缺少信息”提示缺少必要参数

使用场景

当不通过SDK,需要获取MQTT 客户端的连接记录。

请求说明

请求方法:GET

URL :{api}/openapi/rm/device/record

其中{api}通过console后台【服务概览】→【服务配置】→【REST API地址】获取

请求参数:URL参数

参数名称类型是否必选示例说明
clientidString“clientid0@wyq7c0”待查询的Clientid,由“{deviceID}@{AppID}”组成,其中{deviceID}由用户自定义,{AppID}在console后台的【MQTT】→
【服务概览】→【服务配置】下的‘AppID’获取
beginTimeString2021-08-20 15:00:00查询起始时间
endTimeString2021-08-28 15:00:00查询结束时间
currentPageInteger1当前页码,默认1
pageSizeInteger10分页大小,默认10

返回参数

参数名称类型示例说明
codeInteger200200:获取成功;400:获取失败
msgString“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】。

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": 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": 400,
    "msg": "clientid and appid doesn't match",
    "body": null
}

错误码

HTTP Code错误信息描述
403access deny鉴权失败
404page not found接口未找到
400clientid can not be emptyclientid不能为空
400invalid clientidclientid不合法
400clientid and appid doesn't matchclientid和appid不匹配
400beginTime and endTime can not be emptybeginTime和endTime不能为空
400end time must be greater than the start timeendTime必须大于beginTime
500failMQTT后端服务异常,请重试。

使用场景

当不通过SDK,需要根据Client ID获取指定客户端的连接信息时。

请求说明

请求方法:GET

URL :{api}/openapi/rm/broker/clientInfo

其中{api}通过console后台【服务概览】→【服务配置】→【REST API地址】获取

请求参数:URL参数

参数名称类型是否必选示例说明
clientidString“deviceId1@vwp0b0”待查询的Clientid,由“{deviceID}@{AppID}”组成,其中{deviceID}由用户自定义,{AppID}在console后台的【MQTT】→ 【服务概览】→【服务配置】下的‘AppID’获取
currentPageInteger1当前页码,默认1
pageSizeInteger10分页大小,默认10

返回参数

参数名称类型示例说明
codeInteger200200:获取成功;400:获取失败
msgString“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】。

curl --location --request GET '{api}/openapi/rm/broker/clientInfo?clientid=abc@a0cta0' \
--header 'Authorization: YWMtIK2PluhKEeuXN8fXrcb52AAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF6vQgeoABPGgCEPLoPV9_8vVYrVCVYvy7Jfd-2O6sBEDI4FdLjXVzLCw'

返回示例

查询成功

{
    "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": 400,
    "msg": "clientId doesn't exist",
    "body": null
}

错误码

HTTP Code错误信息描述
403access deny鉴权失败
404page not found接口未找到
400clientid can not be emptyclientid不能为空
400invalid clientidclientid不合法
400clientid and appid doesn't matchclientid和appid不匹配
500failMQTT后端服务异常,请重试。

使用场景

当不通过SDK,需要获取指定客户端消息发送与投递记录时。

请求说明

请求方法:GET

URL :{api}/openapi/rm/message/record

其中{api}通过console后台【服务概览】→【服务配置】→【REST API地址】获取

请求参数:URL参数

参数名称类型是否必选示例说明
clientidString“deviceId1@vwp0b0”待查询的Clientid,由“{deviceID}@{AppID}”组成,其中{deviceID}由用户自定义,{AppID}在console后台的【MQTT】→ 【服务概览】→【服务配置】下的‘AppID’获取
beginTimeString2021-08-26 10:00:00查询起始时间
endTimeString2021-08-26 15:00:00查询结束时间
currentPageInteger1当前页码,默认1
pageSizeInteger10分页大小,默认10
orderStringASC取值:“ASC”升序,“DESC”降序

返回参数

参数名称类型示例说明
codeInteger200200:获取成功;400:获取失败
msgString“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】。

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": 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": 400,
    "msg": "clientid and appid doesn't match",
    "body": null
}

错误码

HTTP Code错误信息描述
403access deny鉴权失败
404page not found接口未找到
400clientid can not be emptyclientid不能为空
400invalid clientidclientid不合法
400clientid and appid doesn't matchclientid和appid不匹配
400beginTime and endTime can not be emptybeginTime和endTime不能为空
400end time must be greater than the start timeendTime必须大于beginTime
500failMQTT后端服务异常,请重试。

使用场景

当不通过SDK,需要获取指定消息的发送记录时。

请求说明

请求方法:GET

URL :{api}/openapi/rm/message/publish

其中{api}通过console后台【服务概览】→【服务配置】→【REST API地址】获取

请求参数:URL参数

参数名称类型是否必选示例说明
clientidString“test@a0cta0”待查询的Clientid,由“{deviceID}@{AppID}”组成,其中{deviceID}由用户自定义,{AppID}在console后台的【MQTT】→ 【服务概览】→【服务配置】下的‘AppID’获取
messageidString“04D2E037FA002000”指定的消息ID
orderStringDESC取值:“ASC”升序,“DESC”降序

返回参数

参数名称类型示例说明
codeInteger200200:获取成功;400:获取失败
msgString“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】。

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": 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": 400,
    "msg": "clientid and appid doesn't match",
    "body": null
}

错误码

HTTP Code错误信息描述
403access deny鉴权失败
404page not found接口未找到
400clientid can not be emptyclientid不能为空
400invalid clientidclientid不合法
400clientid and appid doesn't matchclientid和appid不匹配
400messageid can not be emptymessageid不能为空
500failMQTT后端服务异常,请重试。

使用场景

当不通过SDK,需要获取指定消息的投递记录时。

请求说明

请求方法:GET

URL :{api}/openapi/rm/message/subscribe

其中{api}通过console后台【服务概览】→【服务配置】→【REST API地址】获取

请求参数:URL参数

参数名称类型是否必选示例说明
clientidString“test@a0cta0”待查询的Clientid,由“{deviceID}@{AppID}”组成,其中{deviceID}由用户自定义,{AppID}在console后台的【MQTT】→ 【服务概览】→【服务配置】下的‘AppID’获取
messageidString“04D2E037FA002000”指定的消息ID
beginTimeString2021-08-26 15:00:00查询起始时间
endTimeString2021-08-28 13:00:00查询结束时间
currentPageInteger1当前页码,默认1
pageSizeInteger10分页大小,默认10
orderStringDESC取值:“ASC”升序,“DESC”降序

返回参数

参数名称类型示例说明
codeInteger200200:获取成功;400:获取失败
msgString“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】。

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": 200,
    "msg": "success",
    "body": {
        "data": [
            {
                "ts": "2021-08-28 18:56:18.957",
                "cid": "test@a0cta0",
                "status": "normal",
                "qos": 0
            }
        ],
        "totalCount": 1
    }
}

查询失败

{
    "code": 400,
    "msg": "clientid and appid doesn't match",
    "body": null
}

错误码

HTTP Code错误信息描述
403access deny鉴权失败
404page not found接口未找到
400clientid can not be emptyclientid不能为空
400invalid clientidclientid不合法
400clientid and appid doesn't matchclientid和appid不匹配
400messageid can not be emptymessageid不能为空
400beginTime and endTime can not be emptybeginTime和endTime不能为空
400end time must be greater than the start timeendTime必须大于beginTime
500failMQTT后端服务异常,请重试。

使用场景

通过REST API接口,可以传入指定消息ID获取该消息的具体内容。

请求说明

请求方法:GET

URL :{api}/openapi/rm/message/message

其中{api}通过console后台【服务概览】→【服务配置】→【REST API地址】获取

请求参数:URL参数

参数名称类型是否必选示例说明
messageIdString“04D2E037FA002000”指定的消息ID
encodeString“base64”消息内容的编码,取值:“base64”、“utf-8”,默认“base64”

返回参数

参数名称类型示例说明
codeInteger200200:获取成功;400:获取失败
msgString“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】。

curl --location --request GET '{api}/openapi/rm/message/message?messageId=06D993BBC700A000' \
--header 'Authorization: YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF7TR3OGgBPGgA_9THIQ1jPM2V_QOnTifJjaYo3RSTrGdJWTbSYuXs8ng'

返回示例

查询成功

{
    "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": 403,
    "msg": "access deny"
}

错误码

HTTP Code错误信息描述
403access deny鉴权失败
404page not found接口未找到
400messageId cannot be emptymessageId不能为空
400encode can only be utf-8 or base64编码只能为utf-8或base64
500failMQTT后端服务异常,请重试。

使用场景

通过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
encodeString“base64”消息内容的编码,取值:“base64”、“utf-8”,默认“base64”

返回参数

参数名称类型示例说明
codeInteger200200:获取成功;400:获取失败
msgString“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】。

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": 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": 403,
    "msg": "access deny"
}

错误码

HTTP Code错误信息描述
403access deny鉴权失败
404page not found接口未找到
400messageId cannot be emptymessageId不能为空
400encode can only be utf-8 or base64编码只能为utf-8或base64
500failMQTT后端服务异常,请重试。

使用场景

根据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

返回参数

参数名称类型示例说明
codeInteger200200:获取成功;400:获取失败
msgString“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": 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": 200,
    "msg": "success",
    "body": {
        "total": 0,
        "data": []
    }
}

错误码

HTTP Code错误信息描述
403access deny鉴权失败
404page not found接口未找到
400topic cannot be emptytopic不能为空
500failMQTT后端服务异常,请重试。

使用场景

根据用户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

返回参数

参数名称类型示例说明
codeInteger200200:获取成功;400:获取失败
msgString“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】。

curl --location --request GET '{api}/openapi/rm/users/userid?userid=vimin1&pageSize=10&currentPage=1' \
--header 'Authorization: YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF7TR3OGgBPGgA_9THIQ1jPM2V_QOnTifJjaYo3RSTrGdJWTbSYuXs8ng'

返回示例

查询成功

{
    "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": 200,
    "msg": "success",
    "body": {
        "total": 0,
        "data": []
    }
}

错误码

HTTP Code错误信息描述
403access deny鉴权失败
404page not found接口未找到
400userid cannot be emptyuserid不能为空
500failMQTT后端服务异常,请重试。

使用场景

根据应用ID/appid获取当前在线客户端列表。

请求说明

请求方法:GET

URL :{api}/openapi/rm/users/appid

其中{api}通过console后台【服务概览】→【服务配置】→【REST API地址】获取

请求参数:URL参数

参数名称类型是否必选示例说明
pageSize Integer 10分页大小,默认10
currentPage Integer 1当前页码,默认1

返回参数

参数名称类型示例说明
codeInteger200200:获取成功;400:获取失败
msgString“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】。

curl --location --request GET '{api}/openapi/rm/users/appid?pageSize=10&currentPage=1' \
--header 'Authorization: YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF7TR3OGgBPGgA_9THIQ1jPM2V_QOnTifJjaYo3RSTrGdJWTbSYuXs8ng'

返回示例

查询成功

{
    "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": 200,
    "msg": "success",
    "body": {
        "total": 0,
        "data": []
    }
}

错误码

错误码

HTTP Code错误信息描述
403access deny鉴权失败
404page not found接口未找到
500failMQTT后端服务异常,请重试。