推送标签管理

大约 12 分钟

推送标签管理

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

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

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

公共参数

请求参数

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

响应参数

参数类型描述
timestampLong响应的 Unix 时间戳,单位为毫秒。
durationLong从发送请求到响应的时长,单位为毫秒。

认证方式

环信即时通讯 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

路径参数

参数及说明详见 公共参数

请求 header

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

请求 body

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

HTTP 响应

响应 body

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

字段类型描述
dataJSON推送标签的数据。
nameString推送标签的名称。
descriptionString推送标签的描述。
createdAtLong推送标签的创建时间。该时间为 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}

路径参数

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

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

请求 header

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

HTTP 响应

响应 body

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

字段类型描述
dataJSON推送标签的数据。
nameString推送标签的名称。
descriptionString推送标签的描述。
countInt该推送标签下的用户数量。
createdAtLong推送标签的创建时间。该时间为 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

路径参数

参数及说明详见 公共参数

查询参数

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

请求 header

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

HTTP 响应

响应 body

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

字段类型描述
dataJSON推送标签的数据。
nameString推送标签的名称。
descriptionString推送标签的描述。
countInt该推送标签下的用户数量。
createdAtLong推送标签的创建时间。该时间为 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}

路径参数

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

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

请求 header

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

HTTP 响应

响应 body

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

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

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

如果返回的 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

路径参数

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

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

请求 header

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

请求 body

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

HTTP 响应

响应 body

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

字段类型描述
dataJSON用户添加结果。
successList列明成功添加的用户 ID。
failJSON返回的用户添加失败的结果,为键值对格式,其中 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}

路径参数

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

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

请求 header

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

HTTP 响应

响应 body

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

字段类型描述
dataJSON用户数据。
usernameString要查询的用户 ID。
createdLong添加用户的 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

路径参数

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

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

查询参数

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

请求 header

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

HTTP 响应

响应 body

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

字段类型描述
cursorString下次查询的起始位置。
dataJSON获得的用户的数据。
usernameString获得的该标签下的用户 ID。
createdLong添加用户的 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

路径参数

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

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

请求 header

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

请求 body

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

HTTP 响应

响应 body

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

字段类型描述
dataJSON用户移出标签的结果。
SuccessList被移出标签的用户 ID。
failJSON返回的用户移出标签的结果,为键值对格式,其中 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
}
上次编辑于: