异步任务接口

来自企业号开发者接口文档
跳转至: 导航搜索

异步任务接口说明

异步任务接口用于大批量数据的处理,提交后接口即返回,企业号会在后台继续执行任务。执行完成后,通过任务事件通知企业获取结果。事件的内容会加密,加密过程请参考 (接收消息时的加解密处理);任务事件请参考(异步任务完成事件推送)。

目前,异步任务接口提供“通讯录更新”接口。

通讯录更新

通讯录更新接口提供三种更新方法:1) 增量更新成员 2)全量覆盖成员 3) 全量覆盖部门。如果企业要做到与企业号通讯录完全一致,可先调用全量覆盖部门接口,再调用全量覆盖成员接口,即可保持通讯录完全一致。

使用步骤为:

1.下载接口对应的csv模板,如果有扩展字段,请自行添加

2.按模板的格式,生成接口所需的数据文件

3.通过上传媒体文件接口上传数据文件,获取media_id

4.调用通讯录更新接口,传入media_id参数

5.接收任务完成事件,并获取任务执行结果

增量更新成员

  • 接口说明

本接口以userid为主键,增量更新企业号通讯录成员。请先下载CSV模板(下载增量更新成员模版),根据需求填写文件内容。

注意事项:

1.模板中的部门需填写部门ID,多个部门用分号分隔,部门ID必须为数字
2.文件中存在、通讯录中也存在的成员,更新成员在文件中指定的字段值
3.文件中存在、通讯录中不存在的成员,执行添加操作
4.通讯录中存在、文件中不存在的成员,保持不变
5.成员字段更新规则:文件中有指定的字段,以指定的字段值为准;文件中没指定的字段,不更新

  • 请求说明

Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/batch/syncuser?access_token=ACCESS_TOKEN

请求包结构体为:

{
	"media_id":"xxxxxx",
	"callback":
	{
	 	"url": "xxx",
	 	"token": "xxx",
	 	"encodingaeskey": "xxx"
	}
}
  • 参数说明
参数 是否必须 描述
media_id 上传的csv文件的media_id
callback 回调信息。如填写该项则任务完成后,通过callback推送事件给企业。具体请参考应用回调模式中的相应选项
url 企业应用接收企业号推送请求的访问协议和地址,支持http或https协议
token 用于生成签名
encodingaeskey 用于消息体的加密,是AES密钥的Base64编码
  • 权限说明

管理组须拥有指定成员的管理权限。

  • 返回结果
{
	"errcode": 0,
	"errmsg": "ok",
	"jobid": "xxxxx"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
jobid 异步任务id,最大长度为64字节


全量覆盖成员

  • 接口说明

本接口以userid为主键,全量覆盖企业号通讯录成员,任务完成后企业号通讯录成员与提交的文件完全保持一致。请先下载CSV文件(下载全量覆盖成员模版),根据需求填写文件内容。
注意事项:
1.模板中的部门需填写部门ID,多个部门用分号分隔,部门ID必须为数字
2.文件中存在、通讯录中也存在的成员,完全以文件为准
3.文件中存在、通讯录中不存在的成员,执行添加操作
4.通讯录中存在、文件中不存在的成员,执行删除操作。出于安全考虑,如果:
a) 需要删除的成员多于50人,且多于现有人数的20%以上
b) 需要删除的成员少于50人,且多于现有人数的80%以上
系统将拒绝导入请求并返回相应的错误码
5.成员字段更新规则:文件中有指定的字段,以指定的字段值为准;文件中没指定的字段,不更新

  • 请求说明

Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/batch/replaceuser?access_token=ACCESS_TOKEN

请求包结构体为:

{
	"media_id":"xxxxxx",
	"callback":
	{
	 	"url": "xxx",
	 	"token": "xxx",
	 	"encodingaeskey": "xxx"
	}
}
  • 参数说明
参数 是否必须 描述
media_id 上传的csv文件的media_id
callback 回调信息。如填写该项则任务完成后,通过callback推送事件给企业。具体请参考应用回调模式中的相应选项
url 企业应用接收企业号推送请求的访问协议和地址,支持http或https协议
token 用于生成签名
encodingaeskey 用于消息体的加密,是AES密钥的Base64编码
  • 权限说明

管理组须拥有根部门的管理权限。

  • 返回结果
{
	"errcode": 0,
	"errmsg": "ok",
	"jobid": "xxxxx"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
jobid 异步任务id,最大长度为64字节


全量覆盖部门

  • 接口说明

本接口以partyid为键,全量覆盖企业号通讯录组织架构,任务完成后企业号通讯录组织架构与提交的文件完全保持一致。请先下载CSV文件(下载全量覆盖部门模版),根据需求填写文件内容。
注意事项:
1.文件中存在、通讯录中也存在的部门,执行修改操作
2.文件中存在、通讯录中不存在的部门,执行添加操作
3.文件中不存在、通讯录中存在的部门,当部门下没有任何成员时,执行删除操作
4.CSV文件中,部门名称、部门ID、父部门ID为必填字段,部门ID必须为数字;排序为可选字段,置空或填0不修改排序

  • 请求说明

Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/batch/replaceparty?access_token=ACCESS_TOKEN

请求包结构体为:

{
	"media_id":"xxxxxx",
	"callback":
	{
	 	"url": "xxx",
	 	"token": "xxx",
	 	"encodingaeskey": "xxx"
	}
}
  • 参数说明
参数 是否必须 描述
media_id 上传的csv文件的media_id
callback 回调信息。如填写该项则任务完成后,通过callback推送事件给企业。具体请参考应用回调模式中的相应选项
url 企业应用接收企业号推送请求的访问协议和地址,支持http或https协议
token 用于生成签名
encodingaeskey 用于消息体的加密,是AES密钥的Base64编码
  • 权限说明

管理组须拥有根部门的管理权限。

  • 返回结果
{
	"errcode": 0,
	"errmsg": "ok",
	"jobid": "xxxxx"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
jobid 异步任务id,最大长度为64字节


获取异步任务结果

  • 请求说明

Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/batch/getresult?access_token=ACCESS_TOKEN&jobid=JOBID

  • 参数说明
参数 是否必须 描述
access_token 调用接口凭证
jobid 异步任务id,最大长度为64字节
  • 权限说明

管理组曾经提交相应的任务。

  • 返回结果
{
	"errcode": 0,
 	"errmsg": "ok",
	"status": 1,
	"type": "replace_user",
	"total": 3,
	"percentage": 33,
	"remaintime": 1,
	"result": [{},{}]
}
参数 说明
errcode 请求错误码,0表示成功
errmsg 请求错误信息
status 任务状态,整型,1表示任务开始,2表示任务进行中,3表示任务已完成
type 操作类型,字节串,目前分别有:
1. sync_user(增量更新成员)
2. replace_user(全量覆盖成员)
3. replace_party(全量覆盖部门)
total 任务运行总条数
percentage 目前运行百分比,当任务完成时为100
remaintime 预估剩余时间(单位:分钟),当任务完成时为0
result 详细的处理结果,具体格式参考下面说明。当任务完成后此字段有效


result结构:type为sync_user、replace_user时

	"result": [
	{
	 	"action":1,
	 	"userid":"lisi",
	 	"errcode":0,
	 	"errmsg":"ok"
	},
	{
	 	"action":1,
	 	"userid":"zhangsan",
	 	"errcode":0,
	 	"errmsg":"ok"
	}
	]
参数 说明
action 操作类型(按位或):1 表示修改,2 表示新增
userid 成员UserID。对应管理端的帐号
errcode 该成员对应操作的结果错误码
errmsg 错误信息,例如无权限错误,键值冲突,格式错误等


result结构:type为replace_party时

	"result": [
	{
	 	"action":1,
	 	"partyid":1,
	 	"errcode":0,
	 	"errmsg":"ok"
	},
	{
	 	"action":4,
	 	"partyid":2,
	 	"errcode":0,
	 	"errmsg":"ok"
	}
	]
参数 说明
action 操作类型(按位或):1 新建部门 ,2 更改部门名称, 4 移动部门, 8 修改部门排序
partyid 部门ID
errcode 该部门对应操作的结果错误码
errmsg 错误信息,例如无权限错误,键值冲突,格式错误等