用户管理 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

          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 jpush_web

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 个
email	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"] } }]

           [{
    "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":0,
    "data":{
      "success": ["具体userid"],
      "fail": [{"userid": "具体userid", "errcode":"","errmsg":""}]
   },
    "message":"success"
}

此代码块在浮窗中显示

失败返回

{ "code":5000, "data":"", "message":"错误信息" }

          {   
    "code":5000,    
    "data":"",
    "message":"错误信息"
}

此代码块在浮窗中显示

批量删除 API

POST https://api.ums.jiguang.cn/v1/user/delete

本 API 将删除用户的唯一 ID 及其所绑定的所有信息，请谨慎操作。该操作必须使用 AccessKey 进行鉴权。

本 API 的数据格式为 Array String

请求参数

参数	类型	选项	说明
userid	String	必填	用户的唯一标识

请求示例

["userid1","userid2"]

          ["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":0,
    "data":{
      "success": ["具体userid"],
      "fail": [{"userid": "具体userid", "errcode":"","errmsg":""}]
   },
    "message":"success"
}

此代码块在浮窗中显示

失败返回

{ "code":5000, "data":"", "message":"错误信息" }

          {   
    "code":5000,    
    "data":"",
    "message":"错误信息"
}

此代码块在浮窗中显示

调用返回

调用 API 后的返回码请参考业务返回码