推送标签管理

大约 12 分钟

推送标签管理

即时通讯服务支持通过设置标签自定义推送用户，实现精准推送。标签用于描述用户的生活习惯、兴趣爱好、行为特征等信息。对用户设置标签后，推送消息时，指定某一推送标签，即可向该标签下的用户发送消息。例如，可以为一些用户打上“时尚弄潮儿”标签后，可定期向该人群推送国内外潮流品牌的相关信息。

你可以通过环信即时通讯控制台创建和管理标签，也可以通过 REST API 进行标签管理。用户与标签是多对多的关系，即一个用户可以对应多个标签，一个标签也可以对应多个用户。

本文档主要介绍如何调用即时推送 REST API 实现创建及管理推送标签。

公共参数

请求参数

参数	类型	是否必需	描述
`host`	String	是	访问 RESTful API 的域名或服务器信息。 -公有云集成为环信即时通讯控制台的 `即时通讯->服务概览`页面下的 `域名配置- Rest Api`。 -私有化集成为部署后 `服务器地址:端口`。
`org_name`	String	是	每个公司（组织）分配的唯一标识。详见环信即时通讯控制台的 `应用概览->应用详情`页面下的 `应用信息-Orgname`。
`app_name`	String	是	创建应用时填入的应用名称。详见环信即时通讯控制台的 `应用概览->应用详情`页面下的 `应用信息-Appname`。
`username`	String	是	用户 ID。

响应参数

参数	类型	描述
`timestamp`	Long	响应的 Unix 时间戳，单位为毫秒。
`duration`	Long	从发送请求到响应的时长，单位为毫秒。

认证方式

环信即时通讯 RESTful API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入如下 Authorization 字段：

Authorization：Bearer ${YourAppToken}

为提高项目的安全性，环信使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。即时通讯 RESTful API 推荐使用 app token 的鉴权方式，详见使用 token 鉴权。

创建推送标签

为推送的目标用户添加标签，对用户进行分组，实现精细化推送。当前最多可创建 100 个推送标签。如需提升该上限，请联系商务。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/push/label

路径参数

参数及说明详见公共参数。

参数	类型	描述	是否必需
`Content-Type`	String	内容类型。请填 `application/json`。	是
`Authorization`	String	`Bearer ${YourAppToken}` Bearer 是固定字符，后面加英文空格，再加上获取到的 app token 的值。	是

请求 body

字段	类型	描述	是否必需
`name`	String	要创建的推送标签的名称，不能超过 64 个字符。支持以下字符集： - 26 个小写英文字母 a-z - 26 个大写英文字母 A-Z - 10 个数字 0-9 - “_“,”-“,”.” 标签名称区分大小写，因此 `Aa` 和 `aa` 为两个标签名称。同一个 app 下，标签名称必须唯一。	是
`description`	String	推送标签的描述，不能超过 255 个字符。	否

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

字段	类型	描述
`data`	JSON	推送标签的数据。
`name`	String	推送标签的名称。
`description`	String	推送标签的描述。
`createdAt`	Long	推送标签的创建时间。该时间为 Unix 时间戳，单位为毫秒。

其他参数及描述详见公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考响应状态码了解可能的原因。

示例

请求示例

curl -L -X POST 'localhost/hx/hxdemo/push/label' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A' \
-H 'Content-Type: application/json' \
-d '{
    "name":"post-90s",
    "description":"hah"
}'

响应示例

{
    "timestamp": 1648720341157,
    "data": {
        "name": "post-90s",
        "description": "hah",
        "createdAt": 1648720341118
    },
    "duration": 13
}

查询指定的推送标签

查询指定的推送标签。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/push/label/{labelname}

路径参数

参数	类型	描述	是否必需
`labelname`	String	要查询的推送标签的名称。	是

其他参数及描述详见公共参数。

请求 header

参数	类型	描述	是否必需
`Authorization`	String	`Bearer ${YourAppToken}` Bearer 是固定字符，后面加英文空格，再加上获取到的 app token 的值。	是

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

字段	类型	描述
`data`	JSON	推送标签的数据。
`name`	String	推送标签的名称。
`description`	String	推送标签的描述。
`count`	Int	该推送标签下的用户数量。
`createdAt`	Long	推送标签的创建时间。该时间为 Unix 时间戳，单位为毫秒。

其他参数及描述详见公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考响应状态码了解可能的原因。

示例

请求示例

curl -L -X GET 'localhost/hx/hxdemo/push/label/90' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A'

响应示例

{
    "timestamp": 1648720562644,
    "data": {
        "name": "90",
        "description": "hah",
        "count": 0,
        "createdAt": 1648720341118
    },
    "duration": 0
}

分页查询推送标签

分页查询推送标签。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/push/label

路径参数

参数及说明详见公共参数。

查询参数

字段	类型	描述	是否必需
`limit`	Int	每页显示的推送标签的数量，取值范围为 [1,100]，默认为 `100`。	否
`cursor`	String	数据查询的起始位置。	否

请求 header

参数	类型	描述	是否必需
`Authorization`	String	`Bearer ${YourAppToken}` Bearer 是固定字符，后面加英文空格，再加上获取到的 app token 的值。	是

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

字段	类型	描述
`data`	JSON	推送标签的数据。
`name`	String	推送标签的名称。
`description`	String	推送标签的描述。
`count`	Int	该推送标签下的用户数量。
`createdAt`	Long	推送标签的创建时间。该时间为 Unix 时间戳，单位为毫秒。

其他参数及描述详见公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考响应状态码了解可能的原因。

示例

请求示例

curl -L -X GET 'localhost/hx/hxdemo/push/label' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A'

响应示例

{
    "timestamp": 1648720425599,
    "data": [
        {
            "name": "post-90s",
            "description": "hah",
            "count": 0,
            "createdAt": 1648720341118
        },
        {
            "name": "post-80s",
            "description": "post-80s generation",
            "count": 0,
            "createdAt": 1647512525642
        }
    ],
    "duration": 1
}

删除指定的推送标签

删除指定的推送标签。每次只能删除单个推送标签。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/push/label/{labelname}

路径参数

参数	类型	描述	是否必需
`labelname`	String	要删除的推送标签的名称。	是

其他参数及描述详见公共参数。

请求 header

参数	类型	描述	是否必需
`Authorization`	String	`Bearer ${YourAppToken}` Bearer 是固定字符，后面加英文空格，再加上获取到的 app token 的值。	是

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

字段	类型	描述
`data`	JSON	推送标签成功删除的结果。

其他参数及描述详见公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考响应状态码了解可能的原因。

示例

请求示例

curl -L -X DELETE 'localhost/hx/hxdemo/push/label/post-90s' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A'

响应示例

{
    "timestamp": 1648721097405,
    "data": "success",
    "duration": 0
}

在推送标签下添加用户

为用户分配指定的推送标签。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/push/label/{labelname}/user

路径参数

参数	类型	描述	是否必需
`labelname`	String	推送标签的名称。	是

其他参数及描述详见公共参数。

请求 header

参数	类型	描述	是否必需
`Content-Type`	String	内容类型。请填 `application/json`。	是
`Authorization`	String	`Bearer ${YourAppToken}` Bearer 是固定字符，后面加英文空格，再加上获取到的 app token 的值。	是

请求 body

字段	类型	描述	是否必需
`usernames`	List	推送标签下的用户 ID 列表，最多可传 100 个用户 ID。	是

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

字段	类型	描述
`data`	JSON	用户添加结果。
`success`	List	列明成功添加的用户 ID。
`fail`	JSON	返回的用户添加失败的结果，为键值对格式，其中 key 为添加失败的用户 ID，value 为失败原因。

其他参数及描述详见公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考响应状态码了解可能的原因。

示例

请求示例

curl -L -X POST 'localhost/hx/hxdemo/push/label/post-90s/user' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A' \
-H 'Content-Type: application/json' \
-d '{
    "usernames":["hx1","hx2"]
}'

响应示例

{
    "timestamp": 1648721496345,
    "data": {
        "success": [
            "hx1",
            "hx2"
        ],
        "fail": {}
    },
    "duration": 18
}

查询指定标签下的指定用户

查询推送标签是否存在指定用户。若存在，返回该用户的用户 ID 以及为该用户添加标签的时间；若不存在则不返回这些信息。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/push/label/{labelname}/user/{username}

路径参数

参数	类型	描述	是否必需
`labelname`	String	推送标签的名称。	是
`username`	String	要查询的用户 ID。	是

其他参数及描述详见公共参数。

请求 header

参数	类型	描述	是否必需
`Content-Type`	String	内容类型。请填 `application/json`。	是
`Authorization`	String	`Bearer ${YourAppToken}` Bearer 是固定字符，后面加英文空格，再加上获取到的 app token 的值。	是

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

字段	类型	描述
`data`	JSON	用户数据。
`username`	String	要查询的用户 ID。
`created`	Long	添加用户的 Unix 时间戳，单位为毫秒。

其他参数及描述详见公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考响应状态码了解可能的原因。

示例

请求示例

curl -L -X GET 'localhost/hx/hxdemo/push/label/post-90s/user/hx1' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A'

响应示例

{
    "timestamp": 1648721589676,
    "data": {
        "username": "hx1",
        "created": 1648721496324
    },
    "duration": 1
}

分页查询指定标签下的用户

分页查询指定标签下包含的用户。

HTTP 请求

GET https://{host}/{org_name}/{app_name}/push/label/{labelname}/user

路径参数

参数	类型	描述	是否必需
`labelname`	String	推送标签的名称。	是

其他参数及描述详见公共参数。

查询参数

字段	类型	描述	是否必需
`limit`	String	每次获取的用户数量，取值范围为 [1,100]，默认为 100。	否
`cursor`	String	数据查询的起始位置。	否

请求 header

参数	类型	描述	是否必需
`Content-Type`	String	内容类型。请填 `application/json`。	是
`Authorization`	String	`Bearer ${YourAppToken}` Bearer 是固定字符，后面加英文空格，再加上获取到的 app token 的值。	是

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

字段	类型	描述
`cursor`	String	下次查询的起始位置。
`data`	JSON	获得的用户的数据。
`username`	String	获得的该标签下的用户 ID。
`created`	Long	添加用户的 Unix 时间戳，单位为毫秒。

其他参数及描述详见公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考响应状态码了解可能的原因。

示例

请求示例

curl -L -X GET 'localhost/hx/hxdemo/push/label/post-90s/user?limit=1' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A'

响应示例

{
    "timestamp": 1648721736670,
    "cursor": "ZWFzZW1vYjpwdXNoOmxhYmVsOmN1cnNvcjo5NTkxNTMwMDM4ODQxMzgwMjc",
    "data": [
        {
            "username": "hx1",
            "created": 1648721496324
        }
    ],
    "duration": 1
}

批量移出指定推送标签下的用户

一次移除指定推送标签下的单个或多个用户。

HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/push/label/{labelname}/user

路径参数

参数	类型	描述	是否必需
`labelname`	String	推送标签的名称。	是

其他参数及说明详见公共参数。

请求 header

参数	类型	描述	是否必需
`Content-Type`	String	内容类型。请填 `application/json`。	是
`Authorization`	String	`Bearer ${YourAppToken}` Bearer 是固定字符，后面加英文空格，再加上获取到的 app token 的值。	是

请求 body

字段	类型	描述	是否必需
`usernames`	List	要移出标签的用户 ID 列表，最多可传 100 个用户 ID。	是

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

字段	类型	描述
`data`	JSON	用户移出标签的结果。
`Success`	List	被移出标签的用户 ID。
`fail`	JSON	返回的用户移出标签的结果，为键值对格式，其中 key 为移出失败的用户 ID，value 为失败原因。

其他参数及描述详见公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考响应状态码了解可能的原因。

示例

请求示例

curl -L -X DELETE 'localhost/hx/hxdemo/push/label/post-90s/user' \
-H 'Authorization: Bearer YWMt5lyAUJnNEeyHUS2MdMYkPAAAAAAAAAAAAAAAAAAAAAEHMpqy501HZr2ms92z-Hz9AQMAAAF_SGRs1QBPGgBOIAaoCYWXntKF-h0vuvlyUCNB-IXTM4eEpSVqIdei9A' \
-H 'Content-Type: application/json' \
-d '{
    "usernames":["hx1","hx2"]
}'

响应示例

{
    "timestamp": 1648722018636,
    "data": {
        "success": [
            "hx1",
            "hx2"
        ],
        "fail": {}
    },
    "duration": 1
}

推送标签管理

# 推送标签管理

# 公共参数

# 请求参数

# 响应参数

# 认证方式

# 创建推送标签

# HTTP 请求

# 路径参数

# 请求 header

# 请求 body

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 查询指定的推送标签

# HTTP 请求

# 路径参数

# 请求 header

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 分页查询推送标签

# HTTP 请求

# 路径参数

# 查询参数

# 请求 header

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 删除指定的推送标签

# HTTP 请求

# 路径参数

# 请求 header

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 在推送标签下添加用户

# HTTP 请求

# 路径参数

# 请求 header

# 请求 body

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 查询指定标签下的指定用户

# HTTP 请求

# 路径参数

# 请求 header

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 分页查询指定标签下的用户

# HTTP 请求

# 路径参数

# 查询参数

# 请求 header

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 批量移出指定推送标签下的用户

# HTTP 请求

# 路径参数

# 请求 header

# 请求 body

# HTTP 响应

# 响应 body

推送标签管理

公共参数

请求参数

响应参数

认证方式

创建推送标签

HTTP 请求

路径参数

请求 header

请求 body

HTTP 响应

响应 body

示例

请求示例

响应示例

查询指定的推送标签

HTTP 请求

路径参数

请求 header

HTTP 响应

响应 body

示例

请求示例

响应示例

分页查询推送标签

HTTP 请求

路径参数

查询参数

请求 header

HTTP 响应

响应 body

示例

请求示例

响应示例

删除指定的推送标签

HTTP 请求

路径参数

请求 header

HTTP 响应

响应 body

示例

请求示例

响应示例

在推送标签下添加用户

HTTP 请求

路径参数

请求 header

请求 body

HTTP 响应

响应 body

示例

请求示例

响应示例

查询指定标签下的指定用户

HTTP 请求

路径参数

请求 header

HTTP 响应

响应 body

示例

请求示例

响应示例

分页查询指定标签下的用户

HTTP 请求

路径参数

查询参数

请求 header

HTTP 响应

响应 body

示例

请求示例

响应示例

批量移出指定推送标签下的用户

HTTP 请求

路径参数

请求 header

请求 body

HTTP 响应

响应 body

示例