用户管理接口

个人开发者通过本文档开发用户相关接口。

#接口预览

用户列表查询
获取用户详细信息
获取用户订阅的设备列表
获取设备的订阅用户列表
设置用户扩展属性
获取用户扩展属性
修改用户扩展属性
获取用户单个扩展属性
删除用户扩展属性
启用或停用用户
用户上下线日志查询
向用户发送透传指令
获取用户状态
添加用户
查询已删除用户的列表
删除用户
附录

#接口详情

1.用户列表查询

企业管理员获取该企业下注册的用户列表,可设置过滤条件进行分页查询。

Request

URL

POST /v2/users

Header

Content-Type : "application/json"
Access-Token : "调用凭证"

Content

{
    "offset": "请求列表的偏移量",
    "limit": "请求数量",
    "filter": [
        "字段A",
        "字段B"
    ],
    "query": {
        "filed1": {
            "$in": [
                "字段值",
                "字段值"
            ]
        },
        "filed3": {
            "$lt": "字段值"
        },
		"is_active":[true]
    },
    "order": {
        "filed1": "desc",
        "filed2": "asc"
    }
}

字段	是否必须	描述
offset	否	从某个偏移量开始请求，默认为0
limit	否	请求的条目数量，默认为10
filter	否	字段过滤，可以指定返回结果列表的字段，包含用户扩展属性,可以添加tags
order	否	可以指定通过用户默认字段排序，desc降序，asc升序
query	否	查询条件，可以根据不同字段加上不同的比较指令来查询，查询条件字段包含用户默认属性，不包含用户扩展属性，支持比较指令包含如下： $in：包含于该列表任意一个值 $lt：小于该字段值 $lte：小于或等于字段值 $gt：大于该字段值 $gte：大于或等于该字段值 $all:用于tags数组查询

Response

Header

HTTP/1.1 200 OK

Content

{
    "count": "总数量",
    "list": [
        {
            "id": "用户ID",
            "phone/email": "手机号/邮箱",
            "nickname": "用户昵称",
            "create_date": "创建时间",
            "status": "用户状态",
            "source": "用户来源"
			"tags":"用户标签",
			"account":"用户帐号",
			"phone_valid":"手机是否验证",
			"email_valid":"邮箱是否验证",
			"country":"国家",
			"province":"省份",
			"city":"城市",
			"gender":"性别，-1:未知，1：男，2：女",
			"age":"年龄"
        }
    ]
}

字段	是否必须	描述
id	是	用户ID
account	是	用户账号
nickname	是	用户昵称
create_date	是	创建时间，例：2015-10-09T08 : 15 : 40.843Z
status	是	用户状态，见附录
source	是	用户来源，见附录
account	否	用户帐号
phone_valid	否	手机是否验证
email_valid	否	邮箱是否验证
country	否	国家
province	否	省份
city	否	城市
gender	否	性别，-1:未知，1：男，2：女
age	否	年龄
phone/email	是	手机或邮箱，二者选其一

2.获取用户详细信息

企业管理员根据用户标识userid获取某个用户的详细信息。

Request

URL

GET /v2/user/{user_id}

字段	是否必须	描述
user_id	是	用户ID

Header

Content-Type : "application/json"
Access-Token : "调用凭证"

Content

无

Response

Header

HTTP/1.1 200 OK

Content

{
    "id": "用户ID",
    "corp_id": "企业ID",
    "phone/email": "手机号/邮箱",
	"account":"用户帐号",
    "nickname": "用户昵称",
    "create_date": "创建时间",
    "status": "用户状态",
    "source": "用户来源",
    "region_id": "所在区域ID",
    "is_vaild": "用户账号是否已认证",
	"avatar":"头像URL",
	"country":"国家",
	"province":"省份",
	"city":"城市",
	"gender":"性别，-1:未知，1：男，2：女",
	"age":"年龄"
}

字段	是否必须	描述
id	是	用户ID
phone/email	是	手机或邮箱，二者选其一
account	是	用户帐号
nickname	是	用户昵称
create_date	是	创建时间，例：2015-10-09T08 : 15 : 40.843Z
status	是	用户状态，见附录
source	是	用户来源，见附录
region_id	是	所在区域ID
is_vaild	是	用户账号是否已认证
avatar	否	用户头像
qq_open_id	否	绑定的QQ第三方OpenId
wx_open_id	否	绑定的微信第三方OpenId
wb_open_id	否	绑定的微博第三方OpenId
other_open_id	否	绑定的其他第三方OpenId
country	否	国家
province	否	省份
city	否	城市
gender	否	性别，-1:未知，1：男，2：女
age	否	年龄

3.获取用户订阅的设备列表

企业管理员根据用户标识userid和设备版本versionid获取某个用户绑定的设备列表。

Request

URL

GET /v2/user/{user_id}/subscribe/devices?version={version_id}

字段	是否必须	描述
user_id	是	用户ID
version_id	是	当前设备列表的版本号，起始版本默认为0。

Header

Content-Type : "application/json"
Access-Token : "调用凭证"

Content

无

Response

Header

HTTP/1.1 200 OK

Content

{
    "version": "版本号",
    "list": [
        {
            "id": "设备ID",
            "mac": "设备MAC地址",
            "is_active": "是否激活",
            "active_date": "激活时间",
            "is_online": "是否在线",
            "last_login": "最近登录时间",
            "active_code": "激活码",
            "authorize_code": "认证码",
            "mcu_mod": "MCU型号",
            "mcu_version": "MCU版本号",
            "firmware_mod": "固件型号",
            "firmware_version": "固件版本号",
            "product_id": "所属的产品ID",
            "access_key": "设备访问码",
			"sn":"设备序列号",
			"role":"0为管理员,1为用户",
			"authority":"分享权限"
        }
    ]
}

字段	是否必须	描述
id	是	设备ID
mac	是	设备MAC地址
is_active	是	是否激活，布尔值，true或false
active_date	是	激活时间，例：2015-10-09T08 : 15 : 40.843Z
is_online	是	是否在线，布尔值，true或false
last_login	是	最近登录时间，例：2015-10-09T08 : 15 : 40.843Z
active_code	是	激活码
authorize_code	是	认证码
mcu_mod	是	MCU型号
mcu_version	是	MCU版本号
firmware_mod	是	固件型号
firmware_version	是	固件版本号
product_id	是	所属的产品ID
access_key	是	设备内网访问key
version	否	当前列表的版本号，当返回的版本号于请求的版本不一致时，表示列表已发生更改。
sn	是	设备序列号
role	是	0为管理员,1为用户
authority	是	分析权限

4.获取设备的订阅用户列表

根据设备标识deviceid获取某个设备订阅用户的列表，该设备需要是调用这个接口的用户已经订阅过的设备。

Request

URL

GET /v2/user/{user_id}/subscribe_users?device_id={device_id}

字段	是否必须	描述
user_id	是	用户ID
device_id	是	需要查询的设备ID

Header

Content-Type : "application/json"
Access-Token : "调用凭证"

Content

无

Response

Header

HTTP/1.1 200 OK

Content

{
    "count": "条目数",
    "list": [
        {
            "user_id": "用户ID",
            "role": "用户和设备的订阅关系",
            "nickname": "用户昵称",
            "from_id": "设备被谁分享的"
        }
    ]
}

字段	是否必须	描述
user_id	是	用户ID
nickname	是	用户昵称
from_id	是	设备分享者ID
role	是	用户和设备的订阅关系： 0：管理员 1：普通用户

5.设置用户扩展属性

用户可以设置自定义扩展属性，扩展属性为Key-Value结构，用户扩展属性限制最多为10个。

Request

URL

POST /v2/user/{user_id}/property

字段	是否必须	描述
user_id	是	用户ID

Header

Content-Type : "application/json"
Access-Token : "调用凭证"

Content

{
    "{key}":"{value}",
    "{key}":"{value}"
}

字段	是否必须	描述
{key}	是	扩展属性key值
{value}	是	扩展属性value值

Response

Header

HTTP/1.1 200 OK

Content

无

6.获取用户扩展属性

根据用户标识userid url中获取用户的扩展属性。

Request

URL

GET /v2/user/{user_id}/property

字段	是否必须	描述
user_id	是	用户ID

Header

Content-Type : "application/json"
Access-Token : "调用凭证"

Content

无

Response

Header

HTTP/1.1 200 OK

Content

{
    "{key}":"{value}",
    "{key}":"{value}"
}

字段	是否必须	描述
{key}	是	扩展属性key值
{value}	是	扩展属性value值

7.修改用户扩展属性

根据用户标识userid url中修改用户的扩展属性。

Request

URL

PUT /v2/user/{user_id}/property

字段	是否必须	描述
user_id	是	用户ID

Header

Content-Type : "application/json"
Access-Token : "调用凭证"

Content

{
    "{key}":"{value}",
    "{key}":"{value}"
}

Response

Header

HTTP/1.1 200 OK

Content

无

8.获取用户单个扩展属性

根据用户标识userid以及用户属性中的key url中获取用户单个扩展属性。

Request

URL

GET /v2/user/{user_id}/property/{key}

字段	是否必须	描述
user_id	是	用户ID
key	是	用户属性的key

Header

Content-Type : "application/json"
Access-Token : "调用凭证"

Content

无

Response

Header

HTTP/1.1 200 OK

Content

{
    "{key}":"{value}"
}

字段	是否必须	描述
key	是	扩展属性key值
value	是	扩展属性value值

9.删除用户扩展属性

根据用户标识userid以及用户属性中的key  url中删除用户单个扩展属性。

Request

URL

DELETE /v2/user/{user_id}/property/{key}

字段	是否必须	描述
user_id	是	用户ID
key	是	用户属性的key

Header

Content-Type : "application/json"
Access-Token : "调用凭证"

Content

无

Response

Header

HTTP/1.1 200 OK

Content

无

10.启用或停用用户

根据用户标识userid url中启用或停用一个用户。

Request

URL

PUT /v2/user/{user_id}/status/{status}

字段	是否必须	描述
{user_id}	是	用户ID
{status}	是	用户状态，枚举值，见附录

Header

Content-Type : "application/json"
Access-Token : "调用凭证"

Content

无

Response

Header

HTTP/1.1 200 OK

Content

无

11. 用户上下线日志查询

用户查询用户在云端上下线日志记录，默认情况下按创建时间倒序返回。

Requeset

URL

POST /v2/user_session_log

Header

Content-Type : "application/json"
Access-Token : "调用凭证"

Content

{
    "offset": "请求的列表偏移量",
    "limit": " 请求的列表数量",
    "query": {
        "id": "标识ID",
        "user_id": "用户ID",
        "ip": "ip地址",
        "cm_id": "CM服务器ID",
        "status": "在线状态",
        "code": "引起状态变化的原因"
    }
}

字段	是否必须	描述
offset	否	请求列表的偏移量，默认为0
limit	否	请求列表的数量，默认为10
query	否	查询条件，可以通过字段查询结果，不指定这返回所有结果

Response

Header

HTTP/1.1 200 OK

Content

{
    "count": "总数量",
    "list": [
        {
            "id": "标识ID",
            "user_id": "用户ID",
            "ip": "ip地址",
            "cm_id": "CM服务器ID",
            "status": "在线状态",
            "create_time": "创建时间",
            "code": "引起状态变化的原因"
        }
    ]
}

字段	是否必须	描述
id	是	日志的标识ID
user_id	是	用户ID
ip	是	ip地址
cm_id	是	设备所在服务器ID
status	是	在线状态，0:离线，1:在线
create_time	是	日志创建时间,例：2014-10-09T08:15:40.843Z
code	是	引起状态变化的原因，见附录

12. 向用户发送透传指令

向连接了云端的用户发送透传指令，用户必须连接上云端才可发送成功。

Request

URL

POST /v2/user/{user_id}/pipe

Header

Content-Type : "application/json"
Access-Token : "调用凭证"

Content

{
    "data": {
        "type": "base64",
        "value": "xxxxx"
    }
}

Response

Header

HTTP/1.1 200 OK

Content

无

获取用户状态

获取用户会话状态

获取用户当前的状态，在线或离线。

Request

URL

GET /v2/user/{user_id}/user_session

Header

Content-Type : "application/json"
Access-Token : "调用凭证"

Content

无

Response

Header

HTTP/1.1 200 OK

Content

{
    "user_id": "用户ID",
    "online": "是否在线，1：在线，0：离线",
	"online_time":"上线时间"
}

字段	是否必须	描述
user_id	是	用户ID
online	是	是否在线，1：在线，0：离线
online_time	否	上线时间，在线时提供该字段。

14.添加用户

企业管理员添加用户。

Request

URL

POST /v2/user_add

Header

Content-Type : "application/json"
Access-Token : "调用凭证"

Content

{
    "account": "邮箱/手机号",
    "nickname":"昵称",
    "password":"登录密码",
    "source":"用户来源",
    "local_lang":"本地语言代码",
    "plugin_id":"应用插件ID"
}

字段	是否必须	描述
account	是	使用邮箱或者手机号注册
password	是	认证密码，长度9-16字符，同时包含大小写字母，数字
nickname	否	用户昵称，长度2-32个字符
source	是	用户来源，见附录
local_lang	否	本地语言代码，默认：zh-ch，见附录
plugin_id	否	用户所属的应用插件ID

Response

Header

HTTP/1.1 200 OK

Content

{
    "id" : "用户ID",
    "corp_id":"企业ID",
    "account" : "手机号/邮箱",
	"phone_zone":"手机区号，当account是手机号时可以指定，默认为中国:+86",
    "nickname" : "用户昵称",
    "create_date" : "创建时间",
    "status":"用户状态",
    "source" : "用户来源",
    "region_id":"所在区域ID",
    "is_vaild":"用户账号是否已认证",
	"tags":[标签1,标签2],
	"avatar":"头像资源地址url"
	"qq_open_id":"绑定的QQ帐号信息",
	"wx_open_id":"绑定的微信帐号信息",
	"wb_open_id":"绑定的微博帐号信息",
	"other_open_id":"绑定的其他平台帐号信息",
	"country":"用户所在国家",
	"province":"用户所在省份",
	"city":"用户所在城市",
	"gender":"用户性别, 1为男, 2为女, -1为未知"
}

字段	是否必须	描述
id	是	用户ID
corp_id	是	企业ID
account	是	手机号/邮箱
phone_zone	否	手机区号，当account是手机号时可以指定，默认为中国:+86
nickname	否	用户昵称
create_date	是	用户注册时间，如:2015-10-09T08:15:40.843Z
status	是	用户状态，见附录
source	是	用户来源，见附录
region_id	否	所在区域ID
is_vaild	是	账号是否已激活
tags	否	用户标签,如果用户没有标签则不返回,有则返回数组
avatar	否	头像资源地址url
qq_open_id	否	绑定的QQ帐号信息，为空则无绑定
wx_open_id	否	绑定的微信帐号信息，为空则无绑定
wb_open_id	否	绑定的微博帐号信息，为空则无绑定
other_open_id	否	绑定的其他平台帐号信息，为空则无绑定
country	否	用户所在国家
province	否	用户所在省份
city	否	用户所在城市
gender	否	用户性别, 1为男, 2为女, -1为未知

15.查询已删除用户的列表

Request

URL

POST /v2/corp/user_recycle_list

Header

Content-Type : "application/json"
Access-Token : "调用凭证"

Content

{
    "offset": "请求列表的偏移量",
    "limit": "请求数量",
    "filter": [
        "字段A",
        "字段B"
    ],
    "query": {
        "filed1": {
            "$in": [
                "字段值",
                "字段值"
            ]
        },
        "filed3": {
            "$lt": "字段值"
        },
		"is_active":[true]
    },
    "order": {
        "filed1": "desc",
        "filed2": "asc"
    }
}

字段	是否必须	描述
offset	否	从某个偏移量开始请求，默认为0
limit	否	请求的条目数量，默认为10
filter	否	字段过滤，可以指定返回结果列表的字段，包含用户扩展属性,可以添加tags
order	否	可以指定通过用户默认字段排序，desc降序，asc升序
query	否	查询条件，可以根据不同字段加上不同的比较指令来查询，查询条件字段包含用户默认属性，不包含用户扩展属性，支持比较指令包含如下： $in：包含于该列表任意一个值 $lt：小于该字段值 $lte：小于或等于字段值 $gt：大于该字段值 $gte：大于或等于该字段值 $all:用于tags数组查询

Response

Header

HTTP/1.1 200 OK

Content

{
    "count": "总数量",
    "list": [
        {
            "id": "用户ID",
            "phone/email": "手机号/邮箱",
            "nickname": "用户昵称",
            "create_date": "创建时间",
            "status": "用户状态",
            "source": "用户来源"
			"tags":"用户标签",
			"account":"用户帐号",
			"phone_valid":"手机是否验证",
			"email_valid":"邮箱是否验证",
			"country":"国家",
			"province":"省份",
			"city":"城市",
			"gender":"性别，-1:未知，1：男，2：女",
			"age":"年龄"
        }
    ]
}

字段	是否必须	描述
id	是	用户ID
account	是	用户账号
nickname	是	用户昵称
create_date	是	创建时间，例：2015-10-09T08 : 15 : 40.843Z
status	是	用户状态，见附录
source	是	用户来源，见附录
account	否	用户帐号
phone_valid	否	手机是否验证
email_valid	否	邮箱是否验证
country	否	国家
province	否	省份
city	否	城市
gender	否	性别，-1:未知，1：男，2：女
age	否	年龄
phone/email	是	手机或邮箱，二者选其一

16.删除用户

管理员删除用户。

Request

URL

DELETE /v2/user/{user_id}

字段	是否必须	描述
user_id	是	用户ID

Header

Content-Type : "application/json"
Access-Token : "调用凭证"

Content

无

Response

Header

HTTP/1.1 200 OK

Content

无

附录

1.用户来源

枚举值	说明
1	Web
2	Android客户端
3	IOS客户端
4	微信用户
5	QQ用户
6	微博用户
10	其它遵循xlink统一身份认证规范的用户来源

2.用户状态

枚举值	说明
1	正常
2	停用

3.用户设备权限

枚举值	说明
0	管理员
1	普通用户

4.本地语言代码

枚举值	说明
zh-cn	中文（简体）
en-us	英语（美国）

5.用户在线状态变化原因

枚举值	说明
0	正常
1	网络异常

6. 用户来源

枚举值	说明
1	Web
2	Android客户端
3	IOS客户端
4	微信用户
5	QQ用户
6	微博用户
10	其它遵循xlink统一身份认证规范的用户来源

7. 本地语言代码

枚举值	说明
zh-cn	中文（简体）
en-us	英语（美国）

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

用户管理接口.md

用户管理接口.md

用户管理接口

1.用户列表查询

2.获取用户详细信息

3.获取用户订阅的设备列表

4.获取设备的订阅用户列表

5.设置用户扩展属性

6.获取用户扩展属性

7.修改用户扩展属性

8.获取用户单个扩展属性

9.删除用户扩展属性

10.启用或停用用户

11. 用户上下线日志查询

12. 向用户发送透传指令

获取用户会话状态

14.添加用户

15.查询已删除用户的列表

16.删除用户

附录

Files

用户管理接口.md

Latest commit

History

用户管理接口.md

File metadata and controls

用户管理接口