文档中心

上云无忧 > 文档中心 > 环信MQTT消息云服务使用教程 - 服务器端 REST API
环信
MQTT消息云服务
简介/价格/文档
环信MQTT消息云服务使用教程 - 服务器端 REST API

文档简介：
环信MQTT消息云提供云端API接口，遵循REST体系结构，服务端应用可以直接调用，与环信MQTT消息云进行消息交互。 获取应用Token：当不通过SDK，直接调用openAPI接口时，需要在头部'Authorization'参数设置， 应用Token，本接口即可获取应用Token。
*此产品及展示信息均由环信官方提供。免费试用 咨询热线：400-826-7010，为您提供专业的售前咨询，让您快速了解云产品，助您轻松上云！ 微信咨询
  免费试用、价格特惠

环信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获取当前在线客户端列表。

获取应用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” 开发者密钥，从下图中获取

返回参数

参数名称 类型 示例 说明
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

示例

请求示例 

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*AAAxGnQ2AnjaFHoJNNtSPGZctY
AgMAAAF7jBD3yQBPGgDfuTFLefbMq-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 错误信息 描述
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。 

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格式
参数名称 类型 是否必选 示例 说明
username String 是 “test1” 用户名，从console中创建，从下图中获取
password String 是 “123456” 密码，从console中创建，从下图中获取

返回参数

参数名称 类型 示例 说明
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。 

curl --location --request POST 'https://{api}/openapi/rm/user/token' \ --header 'Authorization:
 YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF7TR3OGgBPGgA_9THIQ1jPM2
V_QOnTifJjaYo3RSTrGdJWTbSYuXs8ng' \ --header 'Content-Type: application/json' \ --data-raw '
{ "username":"test1", "password":"123456" }'

返回示例

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

{
    "code": 200,
    "msg": "success",
    "body": {
        "access_token": "YWMtUZGwvgflEeyyUy3dfJj94pQyzTkCwEDFvGStdtTJYghjRxwA-n4R66DLu1
M1Pt52AwMAAAF7jCqMgQBPGgBS4rWmSUM2lroXf5Zm6qq5y0pSiGAUdzcfP-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 错误信息 描述
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】。 

curl --location --request POST '{api}/v1/rm/chat/publish' \ --header 'Authorization: 
YWMtPagaGPM-Eeu5Mzk9hiiWfgAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF7BNEn6ABPGgBVf-sfXG
MI4tdN624julbYH2g5lGv-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 错误信息 描述
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】。 

curl --location --request GET '{api}/openapi/rm/device/record?clientid=abc@a0cta0&be
ginTime=2021-08-20 15:00:00&endTime=2021-08-28 19:00:00' \
--header 'Authorization: YWMtIK2PluhKEeuXN8fXrcb52AAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3
RNAQMAAAF6vQgeoABPGgCEPLoPV9_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 错误信息 描述
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】。 

curl --location --request GET '{api}/openapi/rm/broker/clientInfo?clientid=abc@a0cta0' \
--header 'Authorization: YWMtIK2PluhKEeuXN8fXrcb52AAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET
2O3RNAQMAAAF6vQgeoABPGgCEPLoPV9_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 错误信息 描述
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】。 

curl --location --request GET '{api}/openapi/rm/message/record?clientid=test@a0cta0&beg
inTime=2021-08-28 01:01:01&endTime=2021-08-28 19:01:01&order=desc' \
--header 'Authorization: YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQ
MAAAF7TR3OGgBPGgA_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 错误信息 描述
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】。 

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: YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3
RNAQMAAAF7TR3OGgBPGgA_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 错误信息 描述
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】。 

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: YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF
7TR3OGgBPGgA_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 错误信息 描述
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】。 

curl --location --request GET '{api}/openapi/rm/message/message?messageId=06D993BBC700A000' \
--header 'Authorization: YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3
RNAQMAAAF7TR3OGgBPGgA_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 错误信息 描述
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】。 

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: YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RN
AQMAAAF7TR3OGgBPGgA_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 错误信息 描述
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": 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 错误信息 描述
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】。 

curl --location --request GET '{api}/openapi/rm/users/userid?userid=vimin1&pageSize=10&currentPage=1' \
--header 'Authorization: YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O3RNAQMAAAF
7TR3OGgBPGgA_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 错误信息 描述
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】。 

curl --location --request GET '{api}/openapi/rm/users/appid?pageSize=10&currentPage=1' \
--header 'Authorization: YWMtb8QoWP5GEeu4MWUY9wqpAQAAAAAAAAAAAAAAAAAAAAFDtjwasNNKD6W3CET2O
3RNAQMAAAF7TR3OGgBPGgA_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 错误信息 描述
403 access deny 鉴权失败
404 page not found 接口未找到
500 fail MQTT后端服务异常，请重试。
相似文档
  • 环信MQTT消息云服务最佳实践 - 场景Demo源码
    们在 Github 和Gitee已经提供了完整的 Demo源码，大家可以根据需要自行下载。 话题聊天室：大型在线聊天室，通过环信MQTT实现统计在线人数、发送弹幕、触发点赞、实时更新排行等功能。Android、iOS、Web。 实时图表：实时数据图表，通过环信MQTT实现数据实时传输、多终端数据同步（增长值、在线人数）。Android、iOS、Web。
  • 环信MQTT消息云服务常见问题QA
    概述： 本文主要列举使用服务时遇到的常见问题，列举如下： 业务开通： 注册后无法开通MQTT业务？ 客户端集成： 哪些开发语言支持集成MQTT客户端？ 小程序是否支持集成MQTT客户端？ 安卓端如何集成MQTT客户端？ iOS端如何集成MQTT客户端？ Java端如何集成MQTT客户端？ Web端如何集成MQTT客户端？
  • 环信MQTT消息云服务客服电话
    客服电话：400-826-7010。如果您准备使用或正在使用MQTT服务，有任何疑问和建议，欢迎您加入企业微信群或提交工单与我们交流。 1. 加入交流群： 微信or企业微信 扫一扫，加入企业微信交流群： 2. 提交工单： 登陆环信通讯云管理后台、 点击“服务支持-工单支持”、 点击“进入工单系统”。
  • 什么是天翼云短信服务？
    短信服务（Short Message Service），简称SMS。支持向国内手机用户发送验证码、短信通知和推广短信等内容。国内短信支持三网合一专属通道，与工信部携号转网平台实时互联。产品具备电信级运维保障，支持实时监控自动切换，到达率高达99%。
  • 天翼云短信服务产品动态
    2023/04/15， 控制台设计体验提升， 优化云通信控制台图表，发送量统计，部分图标展示。
官方微信
联系客服
400-826-7010
7x24小时客服热线
分享
  • QQ好友
  • QQ空间
  • 微信
  • 微博
返回顶部