用户管理 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 的关联标识仅允许传 all
  • 具体的 ChannelKey,在渠道信息中可获取到该值,对标签、手机号码、邮箱地址有效,如果需要设置某一渠道的专属信息,则可以用 Channel Key 做标识,如不需要,则传 all
  • 具体的通道编码,在通道详情中可获取到该值(在创建通道时由运营人员自行设定),在为 userID 绑定 App 注册 ID、微信公众号 ID、微信小程序 ID、支付宝生活号 ID 时必须指定通道编码

jpush_web

请求参数

本 API 的数据格式为 Array Object,参数说明如下:

参数 类型 选项 说明
userid String 必填 用户的唯一标识
add JSON Object 可选 对标签、App 注册 ID 进行增加操作
set JSON Object 可选 对标签、各通道注册 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 个

请求示例

 [{
    "userid": "具体userid",
    "add": {
        "tag": {
            "具体channel_key": ["具体tag_value"]
        }
        "app": {
            "具体sender_code": ["具体app_regid"]
        }
    },
    "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"
    },
    "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"
    }
}]

返回参数

参数 类型 选项 说明
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 后的返回码请参考业务返回码


Copyright 2011-2020, jiguang.cn, All Rights Reserved.
粤ICP备12056275号-13 深圳市和讯华谷信息技术有限公司

Documentation built with MkDocs.