设备管理 - 接口文档 - 企业微信开发者中心

开发者中心

首页

教程

接口

社区

工具

企业内部开发

快速入门服务端API 客户端API 附录更新日志联系我们

企业内部开发服务端API 安全管理设备管理

设备管理

最后更新：2023/12/01

启用了 “设备管理”的企业可以通过相关接口导入可信企业设备，获取/删除可信企业设备、可信个人设备、未知设备，并对未知设备的归属申请进行确认或驳回。

权限说明

调用设备管理相关接口的应用需要满足如下的权限：

应用类型	权限要求
自建应用	配置到「安全与管理 - 设备管理 - 可调用接口的应用」中
代开发应用	暂不支持
第三方应用	暂不支持

注：从2023年12月1日0点起，不再支持通过系统应用secret调用接口，存量企业暂不受影响查看详情

导入可信企业设备

请求方式：POST（HTTPS）
请求地址: https://qyapi.weixin.qq.com/cgi-bin/security/trustdevice/import?access_token=ACCESS_TOKEN

请求包体

{
	"device_list":
	[
		{
			"system":"Windows",
			"mac_addr":
			[
				"50:81:40:29:33:CA",
				"36:27:51:DF:6E:80"
			],
			"motherboard_uuid":"MB_UUID",
			"harddisk_uuid":
			[
				"HD_UUID1",
				"HD_UUID2"
			],
			"domain":"WINDOWS_DOMAIN",
			"pc_name":"PC_001",
		},
		{
			"system":"Mac",
			"seq_no":"SEQ_NO",
			"mac_addr":
			[
				"81:40:50:29:33:DB"
			]
		}
	]
}

参数说明

参数	类型	是否必须	说明
access_token	string	是	应用调用凭证
device_list.system	string	是	设备的类型，`Windows`或`Mac`
device_list.mac_addr	string	是	设备MAC地址，当system为`Windows`时必填，`Mac`选填，每个设备最多100个
device_list.motherboard_uuid	string	否	主板UUID，当system为`Windows`可选填此参数
device_list.harddisk_uuid	string	否	硬盘序列号，当system为`Windows`时可选填此参数，每个设备最多100个
device_list.domain	string	否	Windows域名，当system为`Windows`时可选填此参数
device_list.pc_name	string	否	Windows计算机名，当system为`Windows`时可选填此参数
device_list.seq_no	string	是	Mac序列号，当system为`Mac`时必填

调用说明

每次调用最多导入100条可信企业设备记录

返回示例

{
	"errcode": 0,
	"errmsg": "ok",
	"result":
	[
		{
		   "device_index":1,
		   "device_code":"49nNtYq",
			"status":1
		},
		{
			"device_index":2,
			"status":2
		},
		{
			"device_index":3,
			"status":3
		}
	]
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
result.device_index	int32	导入设备记录的标识，对应请求中设备的顺序，从1开始
result.device_code	string	设备的唯一标识，仅导入成功的记录返回
result.status	int32	导入结果，1-成功 2-重复导入 3-不支持的设备 4-数据格式错误

获取设备信息

请求方式：POST（HTTPS）
请求地址: https://qyapi.weixin.qq.com/cgi-bin/security/trustdevice/list?access_token=ACCESS_TOKEN

请求包体

{
	"cursor":"CURSOR",
	"limit":100,
	"type":1
}

参数说明

参数	类型	是否必须	说明
access_token	string	是	应用调用凭证
cursor	string	否	分页cursor,用于获取分页数据
type	int32	是	查询设备类型，1-可信企业设备 2-未知设备 3-可信个人设备
limit	int32	否	查询返回的最大记录数，最高不超过100，默认为100

返回示例

{
	"errcode": 0,
	"errmsg": "ok",
	"device_list":
	[
		{
			"device_code":"49nNtYq",
			"system":"Windows",
			"mac_addr":
			[
				"50:81:40:29:33:CA"
			],
			"motherboard_uuid":"MB_UUID",
			"harddisk_uuid":
			[
				"HD_UUID1"
			],
			"domain":"WINDOWS_DOMAIN",
			"pc_name":"PC_001",
			"last_login_time":1681722163,
			"last_login_userid":"lisi",
			"confirm_timestamp":1681722163,
			"confirm_userid":"lisi",
			"approved_userid":"zhangsan",
			"source":3,
			"status":5
		},
		{
			"device_code":"rjDTnOh",
			"system":"Mac",
			"seq_no":"SEQ_NO1",
			"mac_addr":
			[
				"50:81:40:29:33:CA"
			],
			"source":1,
			"status":5
		}
	],
	"next_cursor":"CURSOR"
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
device.device_code	string	设备编码
device_list.system	string	设备的类型，`Windows`或`Mac`
device_list.mac_addr	string	设备MAC地址
device_list.motherboard_uuid	string	主板UUID
device_list.harddisk_uuid	string	硬盘UUID
device_list.domain	string	Windows域
device_list.pc_name	string	计算机名
device_list.seq_no	string	Mac序列号
device_list.last_login_time	int32	设备最后登录时间戳
device_list.last_login_userid	string	设备最后登录成员userid
device_list.confirm_timestamp	int32	设备归属/确认时间戳
device_list.confirm_userid	string	设备归属/确认成员userid
device_list.approved_userid	string	通过申报的管理员userid
device_list.source	int32	设备来源 0-未知 1-成员确认 2-管理员导入 3-成员自主申报
device_list.status	int32	设备状态 1-已导入未登录 2-待邀请 3-待管理员确认为企业设备 4-待管理员确认为个人设备 5-已确认为可信企业设备 6-已确认为可信个人设备
next_cursor	string	分页游标，再下次请求时填写以获取之后分页的记录，如果已经没有更多的数据则返回空

注意，当获取未确认为可信企业设备的记录时，即获取status为2、4、6时，mac地址，序列号，主板UUID等将会返回脱敏数据。

获取成员使用设备

请求方式：POST（HTTPS）
请求地址: https://qyapi.weixin.qq.com/cgi-bin/security/trustdevice/get_by_user?access_token=ACCESS_TOKEN

请求包体

{
	"last_login_userid":"zhangsan",
	"type":1
}

参数说明

参数	类型	是否必须	说明
access_token	string	是	应用调用凭证
last_login_userid	string	是	最后登录的成员userid
type	int32	是	查询设备类型，1-可信企业设备 2-未知设备 3-可信个人设备

返回示例

{
	"errcode": 0,
	"errmsg": "ok",
	"device_list":
	[
		{
			"device_code":"49nNtYq",
			"system":"Windows",
			"mac_addr":
			[
				"50:81:40:29:33:CA"
			],
			"motherboard_uuid":"MB_UUID",
			"harddisk_uuid":
			[
				"HD_UUID1"
			],
			"domain":"WINDOWS_DOMAIN",
			"pc_name":"PC_001",
			"last_login_time":1681722163,
			"last_login_userid":"lisi",
			"confirm_timestamp":1681722163,
			"confirm_userid":"lisi",
			"approved_userid":"zhangsan",
			"source":3,
			"status":5
		},
		{
			"device_code":"rjDTnOh",
			"system":"Mac",
			"seq_no":"SEQ_NO1",
			"mac_addr":
			[
				"50:81:40:29:33:CA"
			],
			"source":1,
			"status":5
		}
	]
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
device_list.device_code	string	设备编码
device_list.system	string	设备的类型，`Windows`或`Mac`
device_list.mac_addr	string	设备MAC地址
device_list.motherboard_uuid	string	主板UUID
device_list.harddisk_uuid	string	硬盘UUID
device_list.domain	string	windows域
device_list.pc_name	string	计算机名
device_list.seq_no	string	Mac序列号
device_list.last_login_time	int32	设备最后登录时间戳
device_list.last_login_userid	string	设备最后登录成员userid
device_list.confirm_timestamp	int32	设备归属/确认时间戳
device_list.confirm_userid	string	设备归属/确认成员userid
device_list.approved_userid	string	通过申报的管理员userid
device_list.source	int32	设备来源 0-未知 1-成员确认 2-管理员导入 3-成员自主申报
device_list.status	int32	设备状态 1-已导入未登录 2-待邀请 3-待管理员确认为企业设备 4-待管理员确认未个人设备 5-已确认为可信企业设备 6-已确认为可信个人设备

注意，当获取未确认为可信企业设备的记录时，即获取status为2、4、6时，mac地址，序列号，主板UUID等将会返回脱敏数据。

删除设备信息

请求方式：POST（HTTPS）
请求地址: https://qyapi.weixin.qq.com/cgi-bin/security/trustdevice/delete?access_token=ACCESS_TOKEN

请求包体

{
	"type":1,
	"device_code_list":
	[
		"49nNtYq",
		"rjDTnOh"
	]
}

参数说明

参数	类型	是否必须	说明
access_token	string	是	应用调用凭证
type	int32	是	删除设备类型，1-可信企业设备 2-未知设备 3-可信个人设备
device_code_list	string	是	设备编码列表

调用说明

每次调用可删除100个设备

返回示例

{
	"errcode": 0,
	"errmsg": "ok"
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明

确认为可信设备

请求方式：POST（HTTPS）
请求地址: https://qyapi.weixin.qq.com/cgi-bin/security/trustdevice/approve?access_token=ACCESS_TOKEN

请求包体

{
	"device_code_list":
	[
		"49nNtYq",
		"rjDTnOh"
	]
}

参数说明

参数	类型	是否必须	说明
access_token	string	是	应用调用凭证
device_code_list	string	是	设备编码列表, 仅可确认待管理员通过状态，即status为3或4的设备

调用说明

每次调用最多可以确认100个设备

返回示例

{
	"errcode": 0,
	"errmsg": "ok",
	"success_list":["49nNtYq"],
	"fail_list":["rjDTnOh"]
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
success_list	string	确认成功设备code列表
fail_list	string	确认失败设备code列表

驳回可信设备申请

请求方式：POST（HTTPS）
请求地址: https://qyapi.weixin.qq.com/cgi-bin/security/trustdevice/reject?access_token=ACCESS_TOKEN

请求包体

{
	"device_code_list":
	[
		"49nNtYq",
		"rjDTnOh"
	]
}

参数说明

参数	类型	是否必须	说明
access_token	string	是	应用调用凭证
device_code_list	string	是	设备编码列表，仅可驳回待管理员通过状态，即status为3或4的设备

调用说明

每次调用最多可以拒绝100个设备

返回示例

{
	"errcode": 0,
	"errmsg": "ok",
	"success_list":["49nNtYq"],
	"fail_list":["rjDTnOh"]
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
success_list	string	驳回成功设备code列表
fail_list	string	驳回失败设备code列表

文件防泄漏

分配高级功能账号

本节内容

权限说明
导入可信企业设备
获取设备信息
获取成员使用设备
删除设备信息
确认为可信设备
驳回可信设备申请