REST API

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

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

使用场景

当不通过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后端服务异常,请重试

使用场景

当不通过SDK,直接获取临时访问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用户名不能为空
400password can not be empty密码不能为空
400appClientId can not be emptyappClientId不能为空
400username and password don't match用户名密码不匹配
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接口未找到
400clientid can not be emptyclientid不能为空
400invalid clientidclientid不合法
400clientid and appid doesn't matchclientid和appid不匹配
400topics array can not be emptytopics不能为空
400topics array's size can not exceed 32topics数量不能超过32个
400payload can not be emptypayload不能为空
400invalid qosqos不合法
500failMQTT后端服务异常,请重试。
400bad_jsonjson格式错误
400error_topics_format主题名称不合法
400payload_too_largerpayload太大
400error_bad_api_packet缺少必要参数

使用场景

当不通过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后端服务异常,请重试。