FogCloud应用端接口文档

token说明

所有标明jwt认证的接口,需要在请求header中添加Authorization头域,值为:jwt token,如下示例:

Authorization: jwt eyJhbGciOiJ...

ErrorCode说明

参数说明

获取用户注册验证码

POST /enduser/getVerCode/

请求参数

参数名 类型 必须 说明
appid string FogCloud后台注册app时生成的id
loginname string 注册用的手机号码或者邮箱

返回值

{
    "meta": {
        "message": "Send message to phone successfully.",
        "code": 0
    },
    "data": {}
}

错误码

错误代码 错误说明
23010 参数错误:缺少参数或者参数类型错误等
23013 参数错误:使用的手机号或者邮箱格式错误
23070 app id无效,在服务器找不到对应app

验证码检查

POST /enduser/checkVerCode/

请求参数

参数名 类型 必须 说明
appid string FogCloud后台注册app时生成的id
loginname string 注册用的手机号码或者邮箱
vercode string 验证码

返回值

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "clientid": "466f491a-9753-11e6-9baf-00163e120d98"
}

字段说明

返回值字段 字段类型 字段说明
token string jwt token
clientid string 用户在服务器的唯一标识

错误码

错误代码 错误说明
23010 参数错误:缺少参数或者参数类型错误等
23013 参数错误:使用的手机号或者邮箱格式错误
23041 用户被禁用
23070 app id无效,在服务器找不到对应app
23080 验证码错误
23081 验证码过期
23090 服务器内部错误:缺少或者有多个MqttClient

注意事项 - 该接口调用结束并不会设置用户密码,仅仅更新mqtt的登录密码为验证码;若要设置用户密码,需要调用/enduser/resetPassword/接口设置。 - clientid用于登录mqtt,登录密码同用户密码,如果使用验证码登录,则mqtt的登录密码为验证码。


登录

POST /enduser/login/

请求参数

参数名 类型 必须 说明
loginname string 注册用的手机号码或者邮箱
password string 用户登录密码
appid string FogCloud后台注册app时生成的id

返回值

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "clientid": "466f491a-9753-11e6-9baf-00163e120d98"
}

返回值字段说明

字段 类型 说明
token string JWT token
clientid string 终端用户ID,同enduserid,可用于登录mqtt的用户名

注意 目前请根据返回值中的错误信息,自行判断错误类型,后期会拆分到不同ErrorCode。

错误码

错误代码 错误说明
23010 参数错误:缺少参数或者参数类型错误等
- - -
### 刷新应用端授权
>POST /enduser/refreshToken/

请求参数

参数名 类型 必须 说明
token string jwt token

返回值

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "clientid": "466f491a-9753-11e6-9baf-00163e120d98"
}

返回值字段说明

字段 类型 说明
token string JWT token
clientid string 终端用户ID,同enduserid,可用于登录mqtt的用户名

注意

目前请根据返回值中的错误信息,自行判断错误类型,后期会拆分到不同ErrorCode。

错误码

错误代码 错误说明
23010 参数错误:缺少参数或者参数类型错误等

验证应用端授权

POST /enduser/verifyToken/

请求参数

参数名 类型 必须 说明
token string jwt token

返回值

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "clientid": "466f491a-9753-11e6-9baf-00163e120d98"
}

返回值字段说明

字段 类型 说明
token string JWT token
clientid string 终端用户ID,同enduserid,可用于登录mqtt的用户名

注意

目前请根据返回值中的错误信息,自行判断错误类型,后期会拆分到不同ErrorCode。

错误码

错误代码 错误说明
23010 参数错误:缺少参数或者参数类型错误等

密码重置(jwt认证)

POST /enduser/resetPassword/

请求参数

参数名 类型 必须 说明
password1 string 密码,至少4个字符,最多20个字符
password2 string 确认密码,至少4个字符,最多20个字符

返回值

{
    "meta": {
        "message": "Update password successfully.",
        "code": 0
    },
    "data": {}
}

错误码

错误代码 错误说明
23010 参数错误:缺少参数或者参数类型错误等
23014 参数错误:两次密码不一致
23090 内部错误:缺少或者有多个MqttClient

绑定设备(jwt认证)

POST /enduser/bindDevice/

请求参数

参数名 类型 必须 说明
deviceid string 设备ID
devicepw string 设备密码
vercode string 绑定验证码,由设备调用云端接口生成

返回值

{
    "meta": {
        "message": "Bind superuser to device successfully.",
        "code": 0
    },
    "data": {
        "devicepw": "123456",
        "deviceid": "7d0d8430-759a-11e6-a169-f8cab81d2727",
        "devicename": "test"
    }
}

或者

{
    "meta": {
        "message": "Rebind device to this User",
        "code": 0
    },
    "data": {
        "devicepw": "123456",
        "deviceid": "7d0d8430-759a-11e6-a169-f8cab81d2727",
        "devicename": "test"
    }
}

返回值字段说明

字段 类型 说明
devicepw string 设备密码
deviceid string 设备ID
devicename string 设备名字,默认为产品名字

错误码

错误代码 错误说明
23010 参数错误:缺少参数或者参数类型错误等
23011 参数错误:extra格式错误
23032 设备密码错误
23031 设备ID错误,找不到对应时间
23080 验证码错误
23081 验证码过期
23090 内部错误:缺少或者有多个MqttClient
23101 设备已经绑定超级用户

获取设备授权码(jwt认证)

POST /enduser/getShareVerCode/

请求参数

参数名 类型 必须 说明
deviceid string 设备ID

返回值

{
    "meta": {
        "message": "Generate captcha successfully.",
        "code": 0
    },
    "data": {
        "vercode": "ac137a1e-9cda-11e6-993c-dc536017523b"
    }
}

错误码

错误代码 错误说明
23010 参数错误:缺少参数或者参数类型错误等
23031 设备ID错误,找不到对应设备
23043 权限错误:需要管理员或者超级管理员权限

设备授权(jwt认证)

POST /enduser/grantDevice/

请求参数

参数名 类型 必须 说明
vercode string 授权码
deviceid string 设备ID
role int 授权等级(2:管理员,3:普通用户)
bindingtype string 用户分组,可选值home,guest和other
deviceid string 设备ID
devicepw string 设备密码
extra json string或者json object 扩展参数
iscallback Boolean 是否需要发送mqtt消息通知设备
granttimes int 验证码是否有效一次,0为一次有效,非0为十分钟有效

返回值

{
    "meta": {
        "message": "Grant successfully.",
        "code": 0
    },
    "data": {
        "id": 32,
        "devicepw": "123456",
        "bindingtype": "home",
        "role": 2,
        "remark": "",
        "bindingtime": "2016-10-28T15:41:35.817000",
        "validitytime": null,
        "status": 1,
        "deleteflag": false,
        "alias": "test",
        "extra": {},
        "enduser": 11,
        "app": "c57a6240-4e6e-11e6-96c8-dc536017523b",
        "device": 12
    }
}

返回值字段说明

字段 类型 说明
devicepw string 设备密码
bindingtype string 用户属组:home,sa,other,guest四种
role int 授权级别
remark string 备注
bindingtime string 绑定时间
validitytime string 有效时间,目前不可用
status bool 是否有效
deleteflag bool 是否删除
alias string 设备名字,默认为产品名字
extra json string 扩展属性
app string App ID

错误码

错误代码 错误说明
23010 参数错误:缺少参数或者参数类型错误等
23011 extra格式错误
23012 role或bindingtype错误
23030 设备ID错误,找不到对应设备
23032 设备密码错误
23043 权限错误:需要管理员或者超级管理员权限
23081 授权码过期
23080 授权码错误
23102 被授权的用户是超级用户,无法授权

应用端发送指令(jwt认证)

POST /enduser/sendCommandAdv/

请求参数

参数名 类型 必须 说明
deviceid string 设备ID
devicepw string 设备密码
payload string 要发送的mqtt消息
format string payload格式,目前固定值为“json”
flag int 功能启用标识

参数备注

flag采用各bit位是否为1标识是否启用对应的功能,对应关系如下: 0位→是否发送mqtt消息到设备topic(c2d/deviceid/commands) 1位→是否将payload数据存入数据库 默认情况下会发送mqtt消息和存储payload到数据库

返回值

{
    "meta": {
        "message": "Send command successfully",
        "code": 0
    },
    "data": {}
}

错误码

错误代码 错误说明
23010 参数错误:缺少参数或者参数类型错误等
23100 用户与设备之间没有绑定关系

更新用户信息(jwt认证)

PUT /enduser/updateUserInfo/

请求参数

参数名 类型 必须 说明
nickname string 昵称
realname string 实名
gender string 性别
city string 所在城市
avatar string 头像,只能是图片的存储链接
note string 备注

返回值

{
    "meta":{
        "message":"success",
        "code":0
    },
    "data":{
        "nickname":"nickname",
        "realname":"realname",
        "gender":"f",
        "city":"shanghai",
        "avatar":"https://storecloud.com/1.jpg",
        "note":"App User"
    }
}

错误码

错误代码 错误说明
23010 参数错误:缺少参数或者参数类型错误等

用户详情(jwt认证)

GET /enduser/getUserInfo/

请求参数

返回值

{
    "meta":{
        "message":"success to user info",
        "code":0
    },
    "data":{
        "last_login":"2016-10-31T15:47:02.600000",
        "enduserid":"330f9fc0-57c3-11e6-a624-f8cab81d2727",
        "phone":"",
        "phonearea":"+86",
        "phoneverified":false,
        "email":"zrg1231@126.com",
        "emailverified":true,
        "nickname":"nickname",
        "realname":"realname",
        "gender":"f",
        "city":"shanghai",
        "avatar":"https://storecloud.com/1.jpg",
        "note":"App User",
        "is_active":true,
        "date_joined":"2016-08-01T16:37:36.828000",
        "is_virtual":false,
        "app":"c57a6240-4e6e-11e6-96c8-dc536017523b"
    }
}

返回值字段说明

字段 类型 说明
last_login string 最后登录时间
enduserid string 终端用户ID
phone string 注册手机号
phonearea string 手机号归属地,如“+86”:中国
phoneverified bool 手机号认证标识
email string 注册邮箱
emailverified bool 邮箱认证标识
nickname string 昵称
realname string 实名
gender string 性别
city string 城市
avatar string 头像链接
note string 备注
is_active bool 是否激活
date_joined string 注册时间
is_virtual string 是否为虚拟用户:true为虚拟用户,false非虚拟用户
app string App ID

错误码


解绑设备(jwt认证)

PUT /enduser/unbindDevice/

请求参数

参数名 类型 必须 说明
deviceid string 设备ID

返回值

{
    "meta":{
        "message":"Unbind superuser successfully.",
        "code":0
    },
    "data":{

    }
}

错误码

错误代码 错误说明
23010 参数错误:缺少参数或者参数类型错误等
23030 设备ID错误
23100 用户与设备之间没有绑定关系

管理员、超级用户解除指定人(jwt认证)

PUT /enduser/removeBindRole/

请求参数

参数名 类型 必须 说明
deviceid string 设备ID
enduserid string 用户ID

返回值

{
    "meta":{
        "message":"Remove successfully.",
        "code":0
    },
    "data":{
        "enduserid":"78212721-759e-11e6-b860-f8cab81d2727"
    }
}

错误码

错误代码 错误说明
23010 参数错误:缺少参数或者参数类型错误等
23030 设备ID错误
23200 管理员不能操作同级管理员(授权除外)或者超级用户
23201 需要管理员或者超级用户权限
23100 用户与设备之间没有绑定关系

超级用户权限转移(jwt认证)

PUT /enduser/transferAdmin/

请求参数

参数名 类型 必须 说明
deviceid string 设备ID
enduserid string 用户ID

返回值

{
    "meta":{
        "message":"Transfer superuser successfully.",
        "code":0
    },
    "data":{
        "enduserid":"78212721-759e-11e6-b860-f8cab81d2727"
    }
}

错误码

错误代码 错误说明
23010 参数错误:缺少参数或者参数类型错误等
23011 extra参数错误
23030 设备ID错误
23040 指定转移到的用户不存在,或者App不是同一个
23100 用户与设备之间没有绑定关系
23201 需要管理员或者超级用户权限

更新授权级别(jwt认证)

PUT /enduser/updateBindRole/

请求参数

参数名 类型 必须 说明
deviceid string 设备ID
enduserid string 用户ID
role int 授权级别,值只能为2或者3

返回值

{
    "meta":{
        "message":"Update role successfully.",
        "code":0
    },
    "data":{
        "enduserid":"78212721-759e-11e6-b860-f8cab81d2727"
    }
}

错误码

错误代码 错误说明
23010 参数错误:缺少参数或者参数类型错误等
23012 role值错误,只能为2或者3
23030 设备ID错误
23100 用户与设备之间没有绑定关系
23102 要更新授权的用户跟设备没有绑定关系
23200 管理员不能操作同级管理员(授权除外)或者超级用户
23201 需要管理员或者超级用户权限

用户的设备列表(jwt认证)

GET /enduser/devicelistbyenduser/

请求参数

返回值

{
    "meta":{
        "message":"device list by user",
        "code":0
    },
    "data":[
        {
            "device_pw":"123456",
            "product_icon":"",
            "gatewaytype":1,
            "parentid":null,
            "device_name":"test",
            "is_sub":false,
            "mac":"123qwe",
            "role":1,
            "online":false,
            "product_name":"test",
            "device_id":"7d0d8430-759a-11e6-a169-f8cab81d2727"
        },
        {
            "device_pw":"123456",
            "product_icon":"",
            "gatewaytype":1,
            "parentid":null,
            "device_name":"test",
            "is_sub":false,
            "mac":"faagaaffabbb",
            "role":2,
            "online":true,
            "product_name":"test",
            "device_id":"471c6700-73d9-11e6-a28a-f8cab81d2727"
        }
    ]
}

返回值字段说明

字段 类型 说明
device_pw string 设备密码
product_icon string 产品图标链接
gatewaytype int 产品类别标识:0为普通设备,1为网关设备,2为子设备
device_name string 设备名字
is_sub bool 子设备标识:false为非子设备,true为子设备
mac string mac地址
role int 授权级别:1为超级用户;2为管理员;3为普通用户
online bool 在离线状态:false为离线,true为在线
product_name string 产品名字
parentid string 子设备的父设备ID
device_id string 设备ID

错误码


指定设备的用户列表(jwt认证)

GET /enduser/enduserlistbydevice/

请求参数

参数名 类型 必须 说明
deviceid string 设备ID

返回值

{
    "meta":{
        "message":"Get user list successfully.",
        "code":0
    },
    "data":[
        {
            "realname":"",
            "enduserid":"78212721-759e-11e6-b860-f8cab81d2727",
            "app":"c57a6240-4e6e-11e6-96c8-dc536017523b",
            "is_active":true,
            "phone":"13026532187",
            "role":2,
            "nickname":"",
            "email":""
        },
        {
            "realname":"",
            "enduserid":"f2e836cf-57c4-11e6-96bb-f8cab81d2727",
            "app":"c57a6240-4e6e-11e6-96c8-dc536017523b",
            "is_active":true,
            "phone":"",
            "role":3,
            "nickname":"",
            "email":"zhangrg@mxchip.com"
        }
    ]
}

返回值字段说明

字段 类型 说明
enduserid string 用户ID
app string App ID
role int 授权级别:1为超级用户;2为管理员;3为普通用户
is_active bool 用户状态:true为可用,false为禁用
phone string 用户注册手机号
email string 用户注册邮箱
nickname string 用户昵称
realname string 用户实名

错误码

错误码 说明
23010 参数错误:设备id错误
23201 用户不是管理员或者超级用户

设备详情(jwt认证)

GET /enduser/deviceInfo/

请求参数

参数名 类型 必须 说明
deviceid string 设备ID

返回值

{
    "meta":{
        "message":"Device info",
        "code":0
    },
    "data":{
        "devicepw":"123456",
        "is_sub":false,
        "gatewaytype":1,
        "parentid":null,
        "alias":"test",
        "online":false
    }
}

返回值字段说明

字段 类型 说明
devicepw string 设备密码
is_sub bool 子设备标识:false为非子设备,true为子设备
gatewaytype int 产品类别标识:0为普通设备,1为网关设备,2为子设备
parentid string 子设备的父设备ID
alias string 设备别名,默认为产品名字
online bool 在离线状态:false为离线,true为在线

错误码

错误码 说明
23010 参数错误:设备id错误
23201 用户不是管理员或者超级用户

更新设备名称(jwt认证)

PUT /enduser/updateDeviceAlias/

请求参数

参数名 类型 必须 说明
deviceid string 设备ID
alias string 设备别名,长度限制为100个字符

返回值

{
    "meta":{
        "message":"Update alias successfully.",
        "code":0
    },
    "data":{

    }
}

错误码

错误码 说明
23010 参数错误:设备id错误
23100 用户与设备间没有绑定关系

获取设备上报的所有数据(jwt认证)

GET /enduser/eventHistory/

请求参数

参数名 类型 必须 说明
deviceid string 设备ID
pagenum int 分页的页码
pagesize int 每页的数据条数

返回值

{
    "meta":{
        "message":"Get history data successfully.",
        "code":0
    },
    "data":{
        "content":[
            {
                "payload":"{"a":1}",
                "time":"2016-10-26 16:22:31"
            },
            {
                "payload":"{"a":1}",
                "time":"2016-10-26 16:22:30"
            },
            {
                "payload":"{"a":1}",
                "time":"2016-10-26 16:22:23"
            }
        ],
        "totalnum":18925
    }
}

返回值字段说明

字段 类型 说明
content json list 历史数据
payload json string 数据内容
time string 数据上报时间
totalnum int 总页数
错误码
错误码 说明
23010 参数错误:设备id错误
23100 用户与设备间没有绑定关系

设备上下线数据(jwt认证)

GET /enduser/onlineStatus/

请求参数

参数名 类型 必须 说明
deviceid string 设备ID
startdate string 开始日期,格式:YY-MM-DD,例:2016-8-8
stopdate string 结束日期,格式:YY-MM-DD,例:2016-8-8

返回值

{
    "meta":{
        "message":"Get online data successfully.",
        "code":0
    },
    "data":{
        "onlines":"[
        ["2016-10-26T10:43:40.978", false],
        ["2016-10-26T08:20:45.529", true],
        ["2016-10-26T03:22:04.914", false],
        ["2016-10-26T02:47:09.820", true],
        ["2016-10-26T02:47:07.836", false],
        ["2016-10-26T01:29:35.020", true],
        ["2016-10-25T01:02:19.278", true],
        ["2016-10-25T01:00:34.221", false]
    }
}

返回值字段说明

字段 类型 说明
onlines json list 历史上下线数据

备注

每一条记录的第一项为上/下线时间,第二项为状态:true为上线,false为下线

错误码

错误码 说明
23010 参数错误:设备id错误
23015 日期格式错误
23100 用户与设备间没有绑定关系

添加子设备(jwt认证)

POST /enduser/addSubDevice/

请求参数

参数名 类型 必须 说明
deviceid string 父设备ID(网关设备)
productid string 子设备产品ID,可为空
timeout int 父设备等待的超时间
extend json string 扩展字段

返回值

{
    "meta":{
        "message":"notice gateway to add sub device successfully.",
        "code":0
    },
    "data":{

    }
}

错误码

错误码 说明
23010 参数错误:设备id错误
23020 产品ID错误,找不到对应的产品
23021 产品类型错误,该产品不是一个子设备类型
23022 父设备不是网关设备
23043 需要超级管理员权限
23100 用户与设备间没有绑定关系

应用端发送命令至子设备(jwt认证)

POST /enduser/sendCommandSub/

请求参数

参数名 类型 必须 说明
subdeviceid string 子设备ID
devicepw string 子设备密码
payload json string 下发的指令
format string payload格式,目前固定值为“json”
flag int 功能启用标识

参数备注

flag采用各bit位是否为1标识是否启用对应的功能,对应关系如下: 0位→是否发送mqtt消息到设备topic(c2d/deviceid/commands) 1位→是否将payload数据存入数据库 默认情况下会发送mqtt消息和存储payload到数据库

返回值

{
    "meta":{
        "message":"Send command successfully",
        "code":0
    },
    "data":{

    }
}

错误码

错误码 说明
23010 参数错误,注意:flag为整型
23100 用户与设备间没有绑定关系