"> 用户API-个推文档中心

用户API

用户API

简述

开发者可对用户设定别名与标签,推送时可直接根据别名、标签进行推送,方便对用户的管理。

  • 别名:

    别名是开发者根据自身需求为每个用户设定的标识,建议对不同用户设定不同别名,保证可通过别名来唯一确认某特定用户。

    例子:可将用户的邮箱、昵称、手机号等设为别名,即可通过邮箱、昵称、手机号指定目标用户下发推送。

  • 标签:

    标签是用户的一种属性,每个用户(通过CID来标识 )可以打上100个标签。

    例子:“喜爱足球”,“喜爱动漫”

  • 黑名单用户

    黑名单用户无法收到推送消息

【别名】绑定别名

一个cid只能绑定一个别名,若已绑定过别名的cid再次绑定新别名,则前一个别名会自动解绑,并绑定新别名。

  • 接口地址: BaseUrl/user/alias
  • 请求方式: POST

Request请求说明:

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

body参数说明

  • content-type:application/json;charset=utf-8

  • 参数示例

{
    "data_list":[
        {
            "cid":"",
            "alias":""
        },
        {
            "cid":"",
            "alias":""
        }
    ]
}
  • 请求参数说明
名称 类型 是否必须 默认值 描述
data_list Json Array 数据列表,数组长度不大于200

data_list说明

名称 类型 是否必须 默认值 描述
cid String cid,用户标识
alias String 别名,有效的别名组成:
字母(区分大小写)、数字、下划线、汉字;
长度<40;
一个别名最多允许绑定10个cid。

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success"
}

请求示例

curl $BaseUrl/user/alias -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
    "data_list":[
        {
            "cid":"",
            "alias":""
        },
        {
            "cid":"",
            "alias":""
        }
    ]
}'

【别名】根据cid查询别名

通过传入的cid查询对应的别名信息

  • 接口地址: BaseUrl/user/alias/cid/$cid
  • 请求方式: GET

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
cid String 用户唯一标识

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "alias": ""
    }
}
名称 类型 描述
alias String 别名

请求示例

curl $BaseUrl/user/alias/cid/$cid -H "token: xxx"

【别名】根据别名查询cid

通过传入的别名查询对应的cid信息

  • 接口地址: BaseUrl/user/cid/alias/$alias
  • 请求方式: GET

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
alias String 别名

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "cid": ["xxx","xxx"]
    }
}
名称 类型 描述
alias String 别名

请求示例

curl $BaseUrl/user/cid/alias/$alias -H "token: xxx"

【别名】批量解绑别名

批量解除别名与cid的关系

  • 接口地址: BaseUrl/user/alias
  • 请求方式: DELETE

Request请求说明:

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

body参数说明

  • content-type:application/json;charset=utf-8

  • 参数示例

{
    "data_list":[
        {
            "cid":"",
            "alias":""
        },
        {
            "cid":"",
            "alias":""
        }
    ]
}
  • 请求参数说明
名称 类型 是否必须 默认值 描述
data_list Json Array 数据列表,数组长度不大于200

data_list

名称 类型 是否必须 默认值 描述
cid String 用户标识
alias String 别名

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success"
}

请求示例

curl $BaseUrl/user/alias -X DELETE -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
    "data_list":[
        {
            "cid":"",
            "alias":""
        },
        {
            "cid":"",
            "alias":""
        }
    ]
}'

【别名】解绑所有别名

解绑所有与该别名绑定的cid

  • 接口地址: BaseUrl/user/alias/$alias
  • 请求方式: DELETE

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
alias String 用户别名

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success"
}

请求示例

curl $BaseUrl/user/alias/$alias -X DELETE -H "token: xxx"

【标签】一个用户绑定一批标签

一个用户绑定一批标签,此操作为覆盖操作,会删除历史绑定的标签;
此接口有频次控制,tag的长度、个数、总长度也有限制,申请修改请联系邮箱:lieg@getui.com

  • 接口地址: BaseUrl/user/custom_tag/cid/$cid
  • 请求方式: POST

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
cid String 用户标识

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

body参数说明

  • content-type:application/json;charset=utf-8

  • 参数示例

{
    "custom_tag": [
        "tag1",
        "tag2"
    ]
}
  • 请求参数说明
名称 类型 是否必须 默认值 描述
custom_tag String Array 标签列表,标签中不能包含空格

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success"
}

请求示例

curl $BaseUrl/user/custom_tag/cid/$cid -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
    "custom_tag": [
        "tag1",
        "tag2"
    ]
}'

【标签】一批用户绑定一个标签

一批用户绑定一个标签
此功能需要申请开通才可以使用,tag的长度也有限制,申请修改请联系邮箱:lieg@getui.com
此接口是异步的,会有延迟

  • 接口地址: BaseUrl/user/custom_tag/batch/$custom_tag
  • 请求方式: PUT

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
custom_tag String 用户标签,标签中不能包含空格,如果含有中文字符需要编码(UrlEncode)

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

body参数说明

  • content-type:application/json;charset=utf-8

  • 参数示例

{
    "cid": [
        "xxx"
    ]
}
  • 请求参数说明
名称 类型 是否必须 默认值 描述
cid String Array 要修改标签属性的cid列表,数组长度不大于200

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "$cid": "true"
    }
}
名称 类型 描述
$cid String key为cid,value为结果,true表示成功,否则失败

请求示例

curl $BaseUrl/user/custom_tag/batch/$custom_tag -X PUT -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
    "cid": [
        "xxx"
    ]
}'

【标签】解绑标签

解绑用户的标签属性
此功能需要申请开通才可以使用,tag的长度也有限制,申请修改请联系邮箱:lieg@getui.com

  • 接口地址: BaseUrl/user/custom_tag/batch/$custom_tag
  • 请求方式: DELETE

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
custom_tag String 用户标签,标签中不能包含空格,如果含有中文字符需要编码(UrlEncode)

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

body参数说明

  • content-type:application/json;charset=utf-8

  • 参数示例

{
    "cid": [
        "xxx"
    ]
}
  • 请求参数说明
名称 类型 是否必须 默认值 描述
cid String Array 要删除标签属性的cid列表,数组长度不大于200

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例TODO 返回值格式很怪,map比较合适

{
    "msg": "success",
    "code": 0,
    "data": {
        "$cid": "true"
    }
}
名称 类型 描述
$cid String key为cid,value为结果,true表示成功,否则失败

请求示例

curl $BaseUrl/user/custom_tag/batch/$custom_tag -X DELETE -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
    "cid": [
        "xxx"
    ]
}'

【标签】查询用户标签

根据cid查询用户标签列表

  • 接口地址: BaseUrl/user/custom_tag/cid/$cid
  • 请求方式: GET

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
cid String 用户标识

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "msg": "success",
    "code": 0,
    "data": {
        "$cid": [
            "custom_tag1",
            "custom_tag2"
        ]
    }
}
名称 类型 描述
$cid Json key: cid,value: 标签列表

请求示例

curl $BaseUrl/user/custom_tag/cid/$cid -H "token: xxx"

【用户】添加黑名单用户

将单个或多个用户加入黑名单,对于黑名单用户在推送过程中会被过滤掉。

  • 接口地址: BaseUrl/user/black/cid/$cid,$cid
  • 请求方式: POST

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
cid String 用户标识,多个以英文逗号隔开,一次最多传200个

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success"
}

请求示例

curl $BaseUrl/user/black/cid/$cid,$cid -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: xxx"

【用户】移除黑名单用户

将单个cid或多个cid用户移出黑名单,对于黑名单用户在推送过程中会被过滤掉的,不会给黑名单用户推送消息

  • 接口地址: BaseUrl/user/black/cid/$cid,$cid
  • 请求方式: DELETE

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
cid String 用户标识,多个以英文逗号隔开,一次最多传200个

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success"
}

请求示例

curl $BaseUrl/user/black/cid/$cid,$cid -X DELETE -H "Content-Type: application/json;charset=utf-8" -H "token: xxx"

【用户】查询用户状态

查询用户的状态

  • 接口地址: BaseUrl/user/status/$cid,$cid
  • 请求方式: GET

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
cid String 用户标识,多个以英文逗号隔开,一次最多传200个

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "$cid": {
            "last_login_time":"1484018265935",
            "status":"offline"
        }
    }
}
名称 类型 描述
$cid Json key: cid,value: 用户状态信息
last_login_time String 毫秒时间戳
status String 状态,online在线 offline离线

请求示例

curl $BaseUrl/user/status/$cid,$cid -H "token: xxx"

【用户】设置角标(仅支持IOS)

通过cid通知个推服务器当前iOS设备的角标情况。

  • 接口地址: BaseUrl/user/badge/cid/$cid,$cid
  • 请求方式: POST

Request请求说明:

路径参数说明(路径中$开头的参数)

名称 类型 是否必须 默认值 说明
cid String 用户标识,多个以英文逗号隔开,一次最多传200个

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

body参数说明

  • content-type:application/json;charset=utf-8

  • 参数示例

{
    "badge": "-8"
}
  • 请求参数说明
名称 类型 是否必须 默认值 描述
badge String 用户应用icon上显示的数字
+N: 在原有badge上+N
-N: 在原有badge上-N
N: 直接设置badge(数字,会覆盖原有的badge值)

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success"
}

请求示例

curl $BaseUrl/user/badge/cid/$cid,$cid -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
    "badge": -8
}'

【用户】查询用户总量

通过指定查询条件来查询满足条件的用户数量

  • 接口地址: BaseUrl/user/count
  • 请求方式: POST

Request请求说明:

Header参数说明

名称 类型 是否必须 默认值 说明
token String 接口访问凭据,获取方式请参考获取鉴权token

body参数说明

  • content-type:application/json;charset=utf-8

  • 参数示例

{
    "tag": [
         {
            "key":"phone_type",
            "values": [
                "android"
            ],
            "opt_type":"and"
        },
        {
            "key":"region",
            "values": [
                "11000000"
            ],
            "opt_type":"not"
        },
         {
            "key":"custom_tag",
            "values": [
                "tag1",
                "tag2"
            ],
            "opt_type":"or"
        }
    ]
}
  • 请求参数说明
名称 类型 是否必须 默认值 描述
key String 查询条件(phone_type 手机类型,region 省市,custom_tag 用户标签,设置标签请见接口)
values String Array 查询条件值列表,其中
手机型号使用如下参数androidios
省市使用编号,点击下载文件region_code.data
opt_type String or(或),and(与),not(非),values间的交并补操作
  • 不同key之间是交集,同一个key之间是根据opt_type操作
  • 需要发送给城市在A,B,C里面,没有设置tagtest标签,手机型号为android的用户,用条件交并补功能可以实现,city(A|B|C) && !tag(tagtest) && phonetype(android)

Response响应说明

成功响应数据格式:

  • content-type: application/json;charset=utf-8

  • http code: 200(http code码说明)

  • 返回值示例

{
    "code": 0,
    "msg": "success",
    "data":{
        "user_count": 0
    }
}
名称 类型 描述
user_count Number 符合条件的用户数量

请求示例

curl $BaseUrl/user/count -X POST -H "Content-Type: application/json;charset=utf-8" -H "token: xxx" -d '{
    "tag": [
         {
            "key":"phone_type",
            "values": [
                "android"
            ],
            "opt_type":"or"
        },
         {
            "key":"region",
            "values": [
                "11000000",
                "12000000"
            ],
            "opt_type":"or"
        },
         {
            "key":"custom_tag",
            "values": [
                "aaa"
            ],
            "opt_type":"not"
        }
    ]
}'

开发者中心 SDK 下载

文档中心搜索