FogCloud应用端接口文档（V3）

V3应用端

服务地址

• https://api.fogcloud.io

token说明

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

Authorization: jwt eyJhbGciOiJ...

ErrorCode说明

• 所有接口里，成功的code为0，其他code请参考接口说明。
• token认证失败相关的ErrorCode：

参数说明

• GET/DELETE参数：请封装在请求的URL中
• POST/PUT参数：请封装在请求的body里

获取用户注册验证码

POST /v3/enduser/getVerCode/

• 应用端通过手机号码或者邮箱注册APP账户时，调用该接口获取注册验证码。

请求参数

返回值

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

错误码

验证码检查

POST /v3/enduser/checkVerCode/

• 检查验证码合法性，确认注册的是否本人；接口调用成功后将注册一个App用户，并返回token和clientid。

请求参数

返回值

{
    "meta": {
        "message": "signup ok",
        "code": 0
    },
    "data": {
        "token": "eyJhbGciOiJIUzI1N...",
        "clientid": "b6d21b047bed11e78d170016..."
    }
}

字段说明

错误码

注意事项

• 该接口调用结束并不会设置用户密码，仅仅更新mqtt的登录密码为验证码；若要设置用户密码，需要调用/v3/enduser/resetPassword/接口设置。

登录

POST /v3/enduser/login/

• 用户登录用接口，登录成功后会返回授权token。

请求参数

返回值

{
    "meta": {
        "message": "ok",
        "code": 0
    },
    "data": {
        "token": "eyJhbGciOiJIUzI1N...",
        "clientid": "b6d21b047bed11e78d170016..."
    }
}

返回值字段说明

错误码

登出（jwt认证）

PUT /v3/enduser/logout/

• 用户登出用接口。

请求参数
无

返回值

{
    "meta": {
        "message": "log out ok",
        "code": 0
    },
    "data": {
    }
}

错误码
无

获取MQTT登录信息（jwt认证）

POST /v3/enduser/mqttInfo/

• 应用端通过该接口获取登录MqttServer所需的信息。

请求参数
无

返回值

{
    "meta": {
        "message": "mqtt info",
        "code": 0
    },
    "data": {
        "endpoint": "8d69e5821..."
        "loginname": "8d69e58212cd11e7a...",
        "clientid": "d53azsf..."
        "mqttport": 1883,
        "password": "iLBZ48jfB6tUBIoS8MS...",
        "mqtthost": "8d69e58212cd11e7...e.com",
        "sslport": 1884
    }
}

返回值字段说明

错误码
无

刷新应用端授权

POST /v3/enduser/refreshToken/

• 刷新应用端的授权。

请求参数

返回值

{
    "meta": {
        "message": "ok",
        "code": 0
    },
    "data": {
        "token": "eyJhbGciOiJIUzI1N...",
        "clientid": "b6d21b047bed11e78d170016..."
    }
}

返回值字段说明

错误码

验证应用端授权

POST /v3/enduser/verifyToken/

• 验证应用端授权token是否有效。

请求参数

返回值

{
    "meta": {
        "message": "ok",
        "code": 0
    },
    "data": {
        "token": "eyJhbGciOiJIU...",
        "clientid": "2faf79d67cb111e7b..."
    }
}

返回值字段说明

错误码

密码重置（jwt认证）

POST /v3/enduser/resetPassword/

• 用于注册结束后设置密码，或者终端用户密码遗忘时，重置密码

请求参数

返回值

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

错误码

绑定设备（jwt认证）

POST /v3/enduser/bindDevice/

• 接口调用成功后，当前用户被绑定为设备的超级用户，一个设备只允许一个超级用户，拥有设备的最高权限。在绑定之前需要先在Web控制台让APP和产品建立绑定关系；操作流程：应用管理 → 应用详情 → 绑定产品 → 添加产品 → 选择产品 → 确认 → 确认。

请求参数

返回值

{
    "meta": {
        "message": "Bind superuser to device successfully.",
        "code": 0
    },
    "data": {
        "deviceid": "7d0d843...",
        "devicename": "test"
    }
}

或者

{
    "meta": {
        "message": "Rebind device to this User",
        "code": 0
    },
    "data": {
        "deviceid": "7d0d84...",
        "devicename": "test"
    }
}

返回值字段说明

错误码

获取设备授权码（jwt认证）

POST /v3/enduser/shareCode/

• 管理员/超级用户授权设备时，需要使用该验证码。

请求参数

返回值

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

错误码

设备授权（jwt认证）

POST /v3/enduser/grantDevice/

• 管理员/超级用户对用户进行设备授权；只能授权管理员或者普通用户。该接口为被授权人调用。

请求参数

返回值

{
    "meta": {
        "message": "Grant successfully.",
        "code": 0
    },
    "data": {
        "bindingtype": "home",
        "role": 2,
        "bindingtime": "2016-10-28T15:41:35.817000",
        "status": 1,
        "deleteflag": false,
        "alias": "test",
        "extra": {},
        "enduser": "afgxrty...",
        "app": "c57a6240-4e...",
        "device": "tywww..."
    }
}

返回值字段说明

错误码

更新用户信息（jwt认证）

PUT /v3/enduser/userInfo/

• 更新用户信息。

请求参数

返回值

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

错误码

用户详情（jwt认证）

GET /v3/enduser/userInfo/

• 获取用户的信息详情。

请求参数
无

返回值

{
    "meta":{
        "message":"get user info ok",
        "code":0
    },
    "data":{
        "enduserid":"b6d21b047bed11e...",
        "last_login":"2017-08-09T15:39:32.742454",
        "phone":"",
        "phonearea":"+86",
        "phoneverified":false,
        "email":"test1231@126.com",
        "emailverified":true,
        "nickname":"",
        "realname":"",
        "gender":"",
        "city":"",
        "avatar":"",
        "note":"",
        "is_active":true,
        "date_joined":"2017-08-08T11:57:36.258161",
        "is_virtual":false,
        "isonline":false,
        "onlinetimes":0,
        "open_id":"",
        "app":"2c357408-7730-11e7-8d17-00163e03b4d6"
    }
}

返回值字段说明

错误码

无

解绑设备（jwt认证）

PUT /v3/enduser/unbindDevice/

• 用户解绑设备；普通用户、管理员自解绑，对其他绑定人无影响
  超级管理员解除，将解除与设备绑定的所有用户。

请求参数

返回值

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

错误码

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

PUT /v3/enduser/removeBindRole/

• 管理员、超级用户解除指定人；管理员不能移除管理员。

请求参数

返回值

{
    "meta":{
        "message":"Remove successfully.",
        "code":0
    },
    "data":{
        "enduserid":"782127..."
    }
}

错误码

超级用户权限转移（jwt认证）

POST /v3/enduser/transferAdmin/

• 超级用户将自身的权限转移给其他用户。

请求参数

返回值

{
    "meta":{
        "message":"Transfer superuser successfully.",
        "code":0
    },
    "data":{
        "enduserid":"7821272..."
    }
}

错误码

更新授权级别（jwt认证）

PUT /v3/enduser/updateBindRole/

• 超级用户/管理员更新用户的授权级别：管理员只能更新普通用户为管理员，不能将管理员降级为普通用户。

请求参数

返回值

{
    "meta":{
        "message":"update ok",
        "code":0
    },
    "data":{
        "enduserid":"78212..."
    }
}

错误码

用户的设备列表（jwt认证）

GET /v3/enduser/deviceList/

• 获取用户的设备列表。

请求参数

无

返回值

{
    "meta":{
        "message":"device list by user",
        "code":0
    },
    "data":[
        {
            "device_pw":"123456",
            "product_icon":"",
            "gatewaytype":1,
            "device_name":"test",
            "mac":"123qwe",
            "role":1,
            "online":false,
            "product_name":"test",
            "device_id":"7d0d843..."
        },
        {
            "device_pw":"123456",
            "product_icon":"",
            "gatewaytype":1,
            "device_name":"test",
            "mac":"faagaaffabbb",
            "role":2,
            "online":true,
            "product_name":"test",
            "device_id":"471c670..."
        }
    ]
}

返回值字段说明

错误码

无

指定设备的用户列表（jwt认证）

GET /v3/enduser/enduserList/

• 管理员或者超级用户获取某个设备的所有用户。

请求参数

返回值

{
    "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"
        }
    ]
}

返回值字段说明

错误码

设备详情（jwt认证）

GET /v3/enduser/deviceInfo/

• 获取设备的信息详情。

请求参数

返回值

{
    "meta":{
        "message":"Device info",
        "code":0
    },
    "data":{
        "productid":"f14125..."
        "gatewaytype":1,
        "alias":"test",
        "online":false
    }
}

返回值字段说明

错误码

更新设备名称（jwt认证）

PUT /v3/enduser/updateDeviceAlias/

• 每个用户都可以更新自己绑定的设备的名字，但用户之间不会有影响；该名字在重新绑定后会重置为产品的名字。

请求参数

返回值

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

错误码

彩云天气接口（jwt认证）

GET /v3/enduser/weather/caiyun/

• 应用端通过彩云接口获取天气数据，需要在Fogcloud控制台中，配置App的彩云天气组件。

请求参数

错误码

创建定时任务（jwt认证）

POST /v3/schedule/task/

• 创建云端定时任务。

请求参数

说明

• "*"表示循环执行，比如day_of_week值为"*"，表示每天，hour值为"*"，表示每小时
• group_id：如果需要使用任务分组的功能，请传递此参数，自行生成group_id；虽然有分组概念，但组内的指令是分条创建的；只是在FogCloud中将这组指令组合在一起，便于管理和查看；例如：设置设备启动的起止时间start和stop；需要先创建start的任务到云端，再创建stop的任务到云端，创建时使用的group_id需要一致；这样，在调用get接口获取任务时，指令使用need_group参数为true，取到的任务列表将是分好组的start和stop一一对应的任务列表：

[
    [
        {
            "groupid":"abc",
            "task_id":"001",
            "command":"start",
            "day_of_week":"0, 1"
            "hour":"7",
            "minute":"30"
        },
        {
            "groupid":"abc",
            "task_id":"002",
            "command":"stop",
            "day_of_week":"0, 1"
            "hour":"18",
            "minute":"30"
        }
    ],
    [
        {
            "groupid":"def",
            "task_id":"003",
            "command":"start",
            "day_of_week":"2"
            "hour":"9",
            "minute":"30"
        },
        {
            "groupid":"def",
            "task_id":"004",
            "command":"stop",
            "day_of_week":"2"
            "hour":"17",
            "minute":"30"
        }
    ]
]

day_of_week取值

说明：如果day_of_week为空字符串[""]，或者调用接口时没有传入该参数，则认为该任务是单次任务，执行完就变为disable状态

定时任务示例

• 每周一、周三、周五19点整发布开灯指令

{
    "device_id":"acdeb64e137811...",
    "task_type":1,
    "commands":"{\"open_light\": true}",
    "enable":true,
    "day_of_week":"1,3,5",
    "hour":"19",
    "minute":"0"
}

延时任务示例

• 延时60s执行关灯任务

{
    "device_id":"acdeb64e137811...",
    "task_type":1,
    "commands":"{\"close_light\": true}",
    "enable":true,
    "second":60
}

返回值

{
    "meta":{
        "message":"create task ok.",
        "code":0
    },
    "data":{
        "name":"a1b40530-91...",
        "createtime":"2017-09-04T15:49:51.385"
    }
}

字段说明

错误码

获取定时任务（jwt认证）

GET /v3/schedule/task/

• 获取云端定时任务。

请求参数

返回值

{
    "meta":{
        "message":"task list",
        "code":0
    },
    "data":[
        {
            "commands":"{\"open_light\":true}",
            "enable":true,
            "name":"a1b40530-914...",
            "hour":"19",
            "day_of_week":"*",
            "createtime":"2017-09-04T16:28:30.170",
            "minute":"0"
        }
    ]
}

错误码

更新定时任务（jwt认证）

PUT /v3/schedule/task/

• 更新云端定时任务。

请求参数

说明

• "*"表示循环执行，比如month值为"*"，表示每月，hour值为"*"，表示每小时

day_of_week取值

定时任务示例

• 晚上19点整发布开灯指令

{
    "name":"5de0dbde-afb...",
    "commands":"{\"open_light\": true}",
    "enable":true,
    "month":"*",
    "day_of_month":"*",
    "day_of_week":"2,4,6",
    "hour":"18",
    "minute":"0"
}

延时任务示例

• 延时100s执行关灯任务

{
    "device_id":"acdeb64e137811...",
    "task_type":1,
    "commands":"{\"close_light\": true}",
    "enable":true,
    "second":100
}

返回值

{
    "meta":{
        "message":"update task ok.",
        "code":0
    },
    "data":{
        "name":"a1b40530-91..."
    }
}

字段说明

错误码

删除定时任务（jwt认证）

DELETE /v3/schedule/task/

• 删除云端定时任务。

请求参数

返回值

{
    "meta":{
        "message":"delete task： a1b40530-9... ok.",
        "code":0
    },
    "data":{}
}

错误码

获取设备的时间序列数据（jwt认证）

POST /v3/enduser/device/tsd/

• 获取设备的时间序列数据，需要在FogCloud后台配置规则引擎，且将数据导向到时序数据库中。

请求参数

aggregator说明
aggregator为json string，且需要对应start使用，以下是对应的key和value取值。

aggregator示例

{
    "name":"Avg"
    "sampling":"1 hour"
}

fill说明
fill是当取值为空值时，将该样本的聚合结果填充的值；比如fill设置为：

{
    "type": "Fixed",
    "interval": "1 hour",
    "value": -1
}

三点的数据为空，则三点的数据被填充为-1。

请求的data示例

{
    "deviceid": "3rfxz...",
    "start":"3 hour ago"
    "aggregator": '{"name":"Avg","sampling":"1 hour"}',
    "fill":'{"type": "Fixed","interval": "1 hour","value": -1}'
}

返回值

{
    "meta":{
        "message":"tsd data",
        "code":0
    },
    "data":{
        "count":2,
        "next":null,
        "previous":null,
        "results":[
            [
                1526346000,
                -1
            ],
            [
                1526350200,
                14.666666666666666
            ],
            [
                1526353200,
                5.578418230563003
            ]
        ]
    }
}

错误码