REST API
环信MQTT消息云提供云端API接口，遵循REST体系结构，服务端应用可以直接调用，与环信MQTT消息云进行消息交互。
API 概览
获取应用Token
使用场景
当不通过SDK，直接调用openAPI接口时，需要在头部'Authorization'参数设置应用Token。
请求说明
请求方法：POST
URL ：{api}/openapi/rm/app/token
其中{api}通过console后台【服务概览】→【服务配置】→【REST API地址】获取
请求参数：JSON格式
| 参数名称 | 类型 | 是否必选 | 示例 | 说明 |
|---|---|---|---|---|
| grant_type | String | 是 | “client_credentials” | 固定值 |
| client_id | String | 是 | “YXA6ypREjkbBRTCXNsDYhFpKVw” | 开发者Client ID，系统生成，从下图中获取 |
| client_secret | String | 是 | “YXA6brhCN65pz*y86X9uL63mgeV*90k” | 开发者密钥，从下图中获取 |
返回参数
| 参数名称 | 类型 | 示例 | 说明 |
| access_token | String | “YW*tmK0n9vEhEeu7IQ_xpymXyQAAA*AAAAAA*AAAAAAAAAFvwr 4tLqlNGJgKTR4k*OePAg*AAAF69vn9BwBPGgDB5djV5vHD36*QVb kGX*ExKPIIzTMgx63c5FFKdd*APQ” | 要获取的token |
| expires_in | Integer | 518400 | token过期时间，单位：秒 |
| application | String | “6fc2be2d-2ea9-4d18-980a-4d1e24ace78f” | 当前APP的UUID |
示例
请求示例
curl --location --request POST 'https://a1.easemob.com/1106210317065500/test/token' \
--header 'Content-Type: application/json' \
--data-raw '{
"grant_type":"client_credentials",
"client_id":"YXA6ypREjkbBRTCXNsDYhFpKVw",
"client_secret":"YXA6brhCN65pz*y86X9uL63mgeV*90k"
}'
返回示例
发送成功，access_token参数值即为认证token
{
"application": "6fc2be2d-2ea9-4d18-980a-4d1e24ace78f",
"access_token": "YW*tmK0n9vEhEeu7IQ_xpymXyQAAA*AAAAAA*AAAAAAAAAFvwr4tLqlNGJgKTR4k*OePAg*AAAF69vn9BwBPGgDB5djV5vHD36*QVbkGX*ExKPIIzTMgx63c5FFKdd*APQ",
"expires_in": 5184000
}
发送失败
{
"code": 400,
"msg": "fail",
"body": "app_client_id can not be empty"
}
错误码
| 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后端服务异常，请重试 |
API说明
获取应用Token
使用场景
当不通过SDK，直接调用openAPI接口时，需要在头部'Authorization'参数设置应用Token。
1.2 请求参数
请求类型：JSON
| 参数名称 | 类型 | 是否必选 | 示例 | 说明 |
|---|---|---|---|---|
| grant_type | String | 是 | “client_credentials” | 固定值 |
| client_id | String | 是 | “YXA6ypREjkbBRTCXNsDYhFpKVw” | 开发者Client ID，系统生成，从下图中获取 |
| client_secret | String | 是 | “YXA6brhCN65pz*y86X9uL63mgeV*90k” | 开发者密钥，从下图中获取 |
1.3 响应参数
| 参数名称 | 类型 | 示例 | 说明 |
| access_token | String | “YW*tmK0n9vEhEeu7IQ_xpymXyQAAA*AAAAAA*AAAAAAAAAFvwr 4tLqlNGJgKTR4k*OePAg*AAAF69vn9BwBPGgDB5djV5vHD36*QVb kGX*ExKPIIzTMgx63c5FFKdd*APQ” | 要获取的token |
| expires_in | Integer | 518400 | token过期时间，单位：秒 |
| application | String | “6fc2be2d-2ea9-4d18-980a-4d1e24ace78f” | 当前APP的UUID |
1.4 示例
本次选取APPKEY为“1106210317065500#test”
1.4.1 请求
curl --location --request POST 'http://a1.easemob.com/1106210317065500/test/token' \
--header 'Content-Type: application/json' \
--data-raw '{
"grant_type":"client_credentials",
"client_id":"YXA6ypREjkbBRTCXNsDYhFpKVw",
"client_secret":"YXA6brhCN65pz*y86X9uL63mgeV*90k"
}'
1.4.2 响应
{
"application": "6fc2be2d-2ea9-4d18-980a-4d1e24ace78f",
"access_token": "YW*tmK0n9vEhEeu7IQ_xpymXyQAAA*AAAAAA*AAAAAAAAAFvwr4tLqlNGJgKTR4k*OePAg*AAAF69vn9BwBPGgDB5djV5vHD36*QVbkGX*ExKPIIzTMgx63c5FFKdd*APQ",
"expires_in": 5184000
}
access_token参数值即为认证token
2. 请求URL
POST {api}/v1/rm/chat/publish
其中{api}通过console后台【服务概览】→【服务配置】→【REST API地址】获取
3. 请求消息
请求类型：JSON
| 参数名称 | 类型 | 是否必选 | 示例 | 说明 |
| topics | String[] | 是 | [“a/b/c”, “b/c/d”] | 主题名称数组，最多32个主题 |
| clientid | String | 是 | “clientid0@gtsne0” | 发送者的clientId，由“{deviceID}@{AppID}”组成，其中{deviceID}由用户自定 义，{AppID}从console获取，长度不能超过64个字符 |
| payload | String | 是 | “{'msg':'123'}” | 消息内容，支持json、xml、raw类型 |
| encoding | String | 否 | “plain” | 消息体编码方式，支持 plain 与 base64 两种，默认为 plain |
| qos | Integer | 否 | 0 | QoS等级，默认为0 |
| retain | Integer | 否 | 0 | 是否保留消息，0：不保留，1：保留，默认为0 |
| expire | String | 否 | 86400 | 消息最大保留时间，单位：秒，取值范围：[86400,259200] |
| appid | String | 是 | “gtsne0” | appID从console获取 |
4. 响应消息
| 参数名称 | 类型 | 示例 | 说明 |
| code | Integer | 200 | 200：发送成功；400：发送失败 |
| msg | String | “success”或“fail” | success：发送成功；fail：发送失败 |
| body | Object | {“msgIds”:[“0437FA4325003000”, “0437FA4325003001”]} | 返回messageID列表，顺序与请求的topics对应 |
5. 示例
5.1 请求
/**************************************************************
{api}:从console后台【服务概览】->【服务配置】->【REST API地址】获取
{token}:在报文头Authorization参数添加token信息，token可通过1.3方式获取
**************************************************************/
curl --location --request POST '{api}/v1/rm/chat/publish' \
--header 'Authorization: {token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"clientid": "clientid0@gtsne0",
"payload": "{\"msg\": \"123\"}",
"retain": 0,
"topics": ["a/b/c", "b/c/d"],
"qos": 0,
"expire": 86400,
"appid":"gtsne0"
}'
5.2 响应
发送成功
{
"code": 200,
"msg": "success",
"body": {
"mids": [
"0437FA4325003000",
"0437FA4325003001"
]
}
}
发送失败
{
"code": 400,
"msg": "fail",
"body": "error_topics_format"
}