推送标签 REST API

推送功能新增选择标签进行推送,你可以通过 IM 管理后台创建和管理标签,也可以通过 REST API 进行管理。本文档主要介绍如何调用即时推送 REST API 实现创建及管理推送标签。

调用环信即时通讯推送 RESTful API,请确保满足以下要求:

路径参数

参数 类型 是否必需 描述
host String 必需 你在环信即时通讯 IM 管理后台注册项目时所在的集群服务器地址。
org_name String 必需 你在环信即时通讯 IM 管理后台注册项目时填入的公司(组织)名称。
app_name String 必需 你在环信即时通讯 IM 管理后台注册项目时填入的应用名称。
username String 必需 用户 ID。

请求参数

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

响应体公共参数

以下为常出现的响应体参数及描述:

参数 描述
action 请求方式,即接口方法名。
organization org_name,你在环信即时通讯 IM 管理后台注册项目时填入的公司(组织)名称。
application 应用在系统内的唯一标识。该标识由系统生成,开发者无需关心。
applicationName app_name,你在环信即时通讯 IM 管理后台注册项目时填入的应用名称。
uri 请求 URL。
path 请求路径,属于请求 URL 的一部分,开发者无需关注。
entities 详细信息。
data 实际获取的数据详情。
uuid 用户在系统内的唯一标识。该标识由系统生成,开发者无需关心。
created 群组创建时间,Unix 时间戳,单位为毫秒。
username 用户 ID。
timestamp Unix 时间戳,单位为毫秒。
duration 请求响应时间,单位为毫秒。

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

Authorization:Bearer ${YourAppToken}

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

方法:POST

接入点:{org_name}/{app_name}/push/label

请求头参数

参数及说明详见 公共参数

路径参数

参数及说明详见 公共参数

请求体参数

字段 是否必需 类型 说明
name 必需 string 标签名称,限制 64 字符以内。
description 非必需 string 标签描述 内容,限制 255 字符以内。

请求示例

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

响应示例

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

方法:GET

接入点:{org_name}/{app_name}/push/label/{labelname}

请求头参数

参数及说明详见公共参数

路径参数

字段 是否必需 类型 说明
labelname 必需 string 推送标签名称。

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

请求示例

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
}

方法:GET

接入点:{org_name}/{app_name}/push/label

请求头参数

参数及说明详见公共参数

路径参数

参数及说明详见公共参数

请求参数

字段 是否必需 类型 说明
limit 非必需 string 分页查询数量,默认 100。
cursor 非必需 string 分页查询游标。

请求示例

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

响应示例

{
    "timestamp": 1648720425599,
    "data": [
        {
            "name": "90后",
            "description": "hah",
            "count": 0,
            "createdAt": 1648720341118
        },
        {
            "name": "80后",
            "description": "80后人群",
            "count": 0,
            "createdAt": 1647512525642
        }
    ],
    "duration": 1
}

方法:DELETE

接入点:{org_name}/{app_name}/push/label/{labelname}

请求头参数

参数及说明详见公共参数

路径参数

字段 是否必需 类型 说明
labelname 必需 string 推送标签名称。

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

请求示例

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

响应示例

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

方法:POST

接入点:{org_name}/{app_name}/push/label/{labelname}/user

请求头参数

参数及说明详见公共参数

路径参数

字段 是否必需 类型 说明
labelname 必需 string 推送标签名称。

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

请求体参数

字段 是否必需 类型 说明
usernames 必需 List 标签户名列表,最大为 100 个。

请求示例

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

响应示例

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

方法:GET

接入点:{org_name}/{app_name}/push/label/{labelname}/user/{member}

请求头参数

参数及说明详见公共参数

路径参数

字段 是否必需 类型 说明
labelname 必需 string 推送标签名称。
member 必需 string 推送标签内成员 ID。

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

请求示例

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

响应示例

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

方法:GET

接入点:{org_name}/{app_name}/push/label/{labelname}/user

请求头参数

参数及说明详见公共参数

路径参数

字段 是否必需 类型 说明
labelname 必需 string 推送标签名称。

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

请求参数

字段 是否必需 类型 说明
limit 非必需 string 分页查询数量,默认 100。
cursor 非必需 string 分页查询游标。

请求示例

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

响应示例

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

方法:DELETE

接入点:{org_name}/{app_name}/push/label/{labelname}/user

请求头参数

参数及说明详见公共参数

路径参数

字段 是否必需 类型 说明
labelname 必需 string 推送标签名称。

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

请求体参数

字段 是否必需 类型 说明
usernames 必需 List 标签户名列表, 最大 100 个。

请求示例

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

响应示例

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