用户管理 v1
API 概述
功能说明
用户管理 API 用于在服务器端对用户信息进行增加、删除、修改
调用地址
批量添加、更新用户信息:POST https://api.ums.jiguang.cn/v1/user/opt
批量删除用户信息:POST https://api.ums.jiguang.cn/v1/user/delete
调用验证
HTTP Header(头)里加一个字段( Key/Value 对):
Authorization: Basic base64_auth_string
其中 base64_auth_string 的生成算法为:base64(ChannelKey:MasterSecret)
即,对 ChannelKey 加上冒号,加上 MasterSecret 拼装起来的字符串,再做 base64 转换。
鉴权秘钥
用户管理 API 有两种鉴权秘钥:
渠道 ChannelKey 和秘钥鉴权
- 仅支持上传/修改绑定标识为:该渠道的 ChannelKey、 all 、已授权通道的编码的信息。
全局 AccessKey 和秘钥鉴权,该信息在用户管理页面可以取得。
- 支持上传所有通道、渠道的用户信息
- 支持删除用户
批量添加与更新 API
POST https://api.ums.jiguang.cn/v1/user/opt
支持批量添加与更新用户信息,如果 userid 已存在,则为更新操作,如不存在,则为添加操作
在导入 userID 与各个通道注册 ID 的对应关系时,有一个重要的关键字段是 bind_id(绑定标识),它可以取值 all、通道编码、渠道 Key
- all 即全局设置,所有渠道、通道通用,对标签、手机号码、邮箱地址、钉钉 ID、企业微信 ID、企业微信互联企业 ID 有效,注意:钉钉 ID 的关联标识仅允许传 all
- 具体的 ChannelKey,在渠道信息中可获取到该值,对标签、手机号码、邮箱地址有效,如果需要设置某一渠道的专属信息,则可以用 Channel Key 做标识,如不需要,则传 all
- 具体的通道编码,在通道详情中可获取到该值(在创建通道时由运营人员自行设定),在为 userID 绑定 App 注册 ID、微信公众号 ID、微信小程序 ID、支付宝生活号 ID 时必须指定通道编码
请求参数
本 API 的数据格式为 Array Object,参数说明如下:
参数 | 类型 | 选项 | 说明 |
---|---|---|---|
userid | String | 必填 | 用户的唯一标识 |
add | JSON Object | 可选 | 对标签、App 注册 ID 、企业微信互联企业 ID 进行增加操作 |
set | JSON Object | 可选 | 对标签、各通道注册 ID 、企业微信互联企业 ID 进行设置或覆盖更新 |
del | JSON Object | 可选 | 对标签、各通道注册 ID 进行删除操作 |
tag | JSON Object | 可选 | 标签,在同一个关联标识下可以设置多个 |
phone | JSON Object | 可选 | 手机号码,在同一个关联标识下仅允许设置 1 个 |
JSON Object | 可选 | 邮箱,在同一个关联标识下仅允许设置 1 个 | |
app | JSON Object | 可选 | App 通道的注册 ID,在同一个关联标识下可以设置多个 |
wechatoa | JSON Object | 可选 | 微信公众号通道的注册 ID,在同一个关联标识下仅允许设置 1 个 |
wechatmp | JSON Object | 可选 | 微信小程序通道的注册 ID,在同一个关联标识下仅允许设置 1 个 |
alipaylife | JSON Object | 可选 | 支付宝生活号通道的注册 ID,在同一个关联标识下仅允许设置 1 个 |
dingtalkcc | String | 可选 | 钉钉通道的注册 ID,仅允许设置 1 个 |
wechatwk | String | 可选 | 企业微信通道的注册 ID,仅允许设置 1 个 |
wechatwk_linkedcorp | List | 可选 | 企业微信互联企业的用户 ID,可以设置多个值。请注意,如果该用户是互联企业名下的,用户 ID 需要拼接企业 ID 后上传,格式为 CorpId1/userid1 |
请求示例
[{
"userid": "具体userid",
"add": {
"tag": {
"具体channel_key": ["具体tag_value"]
}
"app": {
"具体sender_code": ["具体app_regid"]
},
"wechatwk_linkedcorp": ["具体wechatwk_linkedcorp_userid1","具体wechatwk_linkedcorp_userid2"]
},
"set":{
"tag": {
"具体channel_key": ["具体tag_value"]
}
"phone": {
"具体channel_key": "具体phone_number"
},
"email": {
"具体channel_key": "具体email_value"
},
"app": {
"具体sender_code": ["具体app_regid"]
},
"wechatoa": {
"具体sender_code":"具体wechatoa_openid"
},
"wechatmp": {
"具体sender_code":"具体wechatmp_openid"
},
"alipaylife": {
"具体sender_code":"具体alipaylife_userid"
},
"dingtalkcc":"具体dingtalk_userid",
"wechatwk": "具体wechatwk_userid",
"wechatwk_linkedcorp": ["具体wechatwk_linkedcorp_userid1","具体wechatwk_linkedcorp_userid2"]
},
"del":{
"tag": {
"具体channel_key": ["具体tag_value"]
}
"phone": {
"具体channel_key": "具体phone_number"
},
"email": {
"具体channel_key": "具体email_value"
},
"app": {
"具体sender_code": ["具体app_regid"]
},
"wechatoa": {
"具体sender_code":"具体wechatoa_openid"
},
"wechatmp": {
"具体sender_code":"具体wechatmp_openid"
},
"alipaylife": {
"具体sender_code":"具体alipaylife_userid"
},
"dingtalkcc":"具体dingtalk_userid",
"wechatwk": "具体wechatwk_userid",
"wechatwk_linkedcorp": ["具体wechatwk_linkedcorp_userid1","具体wechatwk_linkedcorp_userid2"]
}
}]
返回参数
参数 | 类型 | 选项 | 说明 |
---|---|---|---|
code | int | 必填 | 业务返回码,成功时为 0 |
data | String/JSON Object | 必填 | 操作成功/失败的详细数据,当请求失败时,数据为空 |
message | string | 必填 | 业务返回详情,当成功时为 success,失败时将返回具体的失败原因 |
data 数据
当请求失败时,data 为空。
当上传成功或部分成功时,将返回成功/失败的详细数据,此时详细的参数如下:
参数 | 类型 | 选项 | 说明 |
---|---|---|---|
success | Object Array | 必填 | 操作成功的数据 |
fail | Object Array | 必填 | 操作失败的数据 |
userid | string | 可选 | 用户的唯一标识 |
errcode | string | 可选 | 当有失败数据时,返回具体的失败错误码 |
errmsg | string | 可选 | 当有失败数据时,返回具体的失败错误原因 |
返回示例
成功返回
{
"code":0,
"data":{
"success": ["具体userid"],
"fail": [{"userid": "具体userid", "errcode":"","errmsg":""}]
},
"message":"success"
}
失败返回
{
"code":5000,
"data":"",
"message":"错误信息"
}
批量删除 API
POST https://api.ums.jiguang.cn/v1/user/delete
本 API 将删除用户的唯一 ID 及其所绑定的所有信息,请谨慎操作。该操作必须使用 AccessKey 进行鉴权。
本 API 的数据格式为 Array String
请求参数
参数 | 类型 | 选项 | 说明 |
---|---|---|---|
userid | String | 必填 | 用户的唯一标识 |
请求示例
["userid1","userid2"]
返回参数
参数 | 类型 | 选项 | 说明 |
---|---|---|---|
code | int | 必填 | 业务返回码 |
data | String/JSON Object | 必填 | 操作成功/失败的详细数据,当请求失败时,数据为空 |
message | string | 必填 | 业务返回详情,当成功时为 success,失败时将返回具体的失败原因 |
data 数据
当请求失败时,data 为空。
当上传成功或部分成功时,将返回成功/失败的详细数据,此时详细的参数如下:
参数 | 类型 | 选项 | 说明 |
---|---|---|---|
success | Object Array | 必填 | 操作成功的数据 |
fail | Object Array | 必填 | 操作失败的数据 |
userid | string | 可选 | 用户的唯一标识 |
errcode | string | 可选 | 当有失败数据时,返回具体的失败错误码 |
errmsg | string | 可选 | 当有失败数据时,返回具体的失败错误原因 |
返回示例
成功返回
{
"code":0,
"data":{
"success": ["具体userid"],
"fail": [{"userid": "具体userid", "errcode":"","errmsg":""}]
},
"message":"success"
}
失败返回
{
"code":5000,
"data":"",
"message":"错误信息"
}
调用返回
调用 API 后的返回码请参考业务返回码