移动推送标签绑定与解绑-API 文档-文档中心-腾讯云

接口说明
请求方式：POST。
服务地址/v3/device/tag
接口服务地址与服务接入点一一对应，请选择与您的应用服务接入点对应的 服务地址。
接口功能：
Tag API 是所有 tag 接口的统称。Tag API 有多种设置、更新、删除接口，具体的接口见下文。
标签功能的使用场景可参考文档 标签功能使用说明。
参数说明
请求参数
参数名
类型
是否必需
参数说明
operator_type
Integer
是
操作类型：
1 - 增加单个 tag，对单个 token 而言
2 - 删除单个 tag，对单个 token 而言
3 - 增加多个 tag，对单个 token 而言
4 - 删除多个 tag，对单个 token 而言
5 - 删除所有标签，对单个 token 而言
6 - 标签覆盖接口（支持多个标签或自定义类标签覆盖），对单个 token 而言（此接口要清除历史标签之后，才开始设置新的标签，所以针对单个相同 token 的调用，需要间隔一段时间（建议大于1s），否则可能造成更新失败）
7 - 添加单个 tag，对多个 token 而言
8 - 删除单个 tag，对多个 token 而言
9 - 批量添加标签（每次调用最多允许设置20对，每个对里面标签在前，token 在后）
10 - 批量删除标签（每次调用最多允许设置20对，每个对里面标签在前，token 在后）
token_list
Array
否
设备列表：
operator_type = 1,2,3,4,5,6,7,8时，必填
operator_type = 1,2,3,4,5,6时如果该参数包含多个 token 只会设置第一个 token
格式 eg：["token1","token2"] 
列表最大不能超过500个值
token 字符串长度不能超过36字符
tag_list
Array
否
标签列表：
operator_type = 1,2,3,4,6,7,8时，必填，operator_type = 5时忽略
operator_type = 1,2,7,8 时，如果该参数包含多个 tag 时，如果只是对单个 tag 操作，则只会设置第一个 tag
格式 eg：["tag1","tag2"]
列表最大不能超过500个值
tag 字符串长度不能超过50字符
tag_token_list
Array
否
标签、设备对应列表：
operator_type =9,10时，必填
格式 eg： [{"tag":"tag123", "token":"token123"}]
每个对里面标签在前，token 在后 
列表最大不能超过500个值 
tag 字符串长度不能超过50字符
token 字符串长度不能超过36字符
注意
单个应用最多可以有10000个自定义Tag， 每个设备Token最多可绑定100个自定义Tag，每个自定义Tag可绑定的设备 token 数量无限制。
如果仅单次而非连续的标签设置接口调用，则接口调用方式无限制。
如果为连续标签设置接口调用，则需要注意如下：
如果需要对超过10个标签或超过10个 token 的连续标签设置接口调用时，建议使用批量接口，但为保证标签操作的正确，建议两次接口调用的时间间隔不低于1s。
如果调用非批量接口，则在明确拿到移动推送服务器的返回值时，再进行下次非批量标签接口调用，不建议使用多线程异步同时进行标签接口调用。
英文冒号“:”是移动推送后台的关键字，用作标签的分类，如果设置标签时带了“:”，则将第一个“:”前面的字符串作为这个标签的类名，仅为了用于 operator_type 为6时按类进行标签覆盖的场景，如设备原来的标签为 level:1, level:2, male 这3个时，此种方式可直接用 level:3标签覆盖 level 类标签下的 level:1和 level:2标签，而无需先逐个解绑 level:1和 level:2后再绑定 level:4标签，详情见下面请求示例中  operator_type 为6的示例。
应答参数
字段名
类型
是否必填
注释
ret_code
Integer
是
错误码，详细参照错误码对照表
err_msg
String
否
请求出错时的错误信息
seq
Integer
是
与请求包一致（如果请求包是非法 json 该字段为0）
result
String
否
请求正确时：
若有额外数据要返回，则结果封装在该字段的 json 中
若无额外数据，则此字段为空
invalid_tokens
array string
否
请求返回错误的 token
invalid_tags
array string
否
请求返回错误的 tags
示例说明
标签绑定解绑请求示例
增加单个 tag1，对单个 token1
{
    "operator_type": 1,
    "tag_list": [
        "tag1"
    ],
    "token_list": [
        "token1"
    ]
}
删除单个 tag1，对单个 token1
{
    "operator_type": 2,
    "tag_list": [
        "tag1"
    ],
    "token_list": [
        "token1"
    ]
}
增加多个 tag1、tag2，对单个 token1
{
    "operator_type": 3,
    "tag_list": [
        "tag1",
        "tag2"
    ],
    "token_list": [
        "token1"
    ]
}
删除多个 tag1、tag2，对单个 token1
{
    "operator_type": 4,
    "tag_list": [
        "tag1",
        "tag2"
    ],
    "token_list": [
        "token1"
    ]
}
删除所有标签，对单个 token1
{
    "operator_type": 5,
    "tag_list": [
        "tag1",
        "tag2"
    ],
    "token_list": [
        "token1"
    ]
}
标签覆盖自定义类标签，对单个 token1
{
    "operator_type": 6,
    "tag_list": [
        "test:2",
        "level"
    ],
    "token_list": [
        "token1"
    ]
}
说明
 若有其中一个或多个标签不带“：”号，则将 test:2 和 level 标签覆盖 token1 的全部自定义标签。
批量覆盖自定义类标签，对单个 token（此接口只覆盖到自定义类标签，而不是全部覆盖）
{
    "operator_type": 6,
    "tag_list": [
        "test:2",
        "level:2"
    ],
    "token_list": [
        "token1"
    ]
}
说明
 若全部标签都带“:”，由于第一个“:”前面的字符串为标签的类，则仅会覆盖设备对应相同类的标签，如test:2覆盖test:*， level:2覆盖level:*，不会影响其它标签。
为多个 token1、token2 添加单个 tag1
{
    "operator_type": 7,
    "tag_list": [
        "tag1"
    ],
    "token_list": [
        "token1",
        "token2"
    ]
}
多个 token1、token2 删除单个 tag1
{
    "operator_type": 8,
    "tag_list": [
        "tag1"
    ],
    "token_list": [
        "token1",
        "token2"
    ]
}
批量设置标签
{
    "operator_type": 9,
    "tag_token_list": [
        {
            "tag": "tag1",
            "token": "token1"
        }
    ]
}
批量删除标签，为 tag1、tag2、tag3 删除标签
{
    "operator_type": 10,
    "tag_token_list": [
        {
            "tag": "tag1",
            "token": "token1"
        },
        {
            "tag": "tag2",
            "token": "token2"
        },
        {
            "tag": "tag3",
            "token": "token3"
        }
    ]
}
标签设置请求示例
POST /v3/device/tag HTTP/1.1
Host: api.tpns.tencent.com
Content-Type: application/json
Authorization: Basic YTViNWYwNzFmZjc3YTplYTUxMmViNzcwNGQ1ZmI1YTZhOTM3Y2FmYTcwZTc3MQ==
Cache-Control: no-cache
Postman-Token: 4b82a159-afdd-4f5c-b459-de978d845d2f
{
    "operator_type": 1,
    "tag_list": [
        "tag1"
    ],
    "token_list": [
        "token1"
    ]
}
标签设置应答示例
{
    "ret_code": 0,
    "err_msg": "",
    "seq": 0,
    "result": ""
}
﻿

参数名	类型	是否必需	参数说明
operator_type	Integer	是	操作类型： 1 - 增加单个 tag，对单个 token 而言 2 - 删除单个 tag，对单个 token 而言 3 - 增加多个 tag，对单个 token 而言 4 - 删除多个 tag，对单个 token 而言 5 - 删除所有标签，对单个 token 而言 6 - 标签覆盖接口（支持多个标签或自定义类标签覆盖），对单个 token 而言（此接口要清除历史标签之后，才开始设置新的标签，所以针对单个相同 token 的调用，需要间隔一段时间（建议大于1s），否则可能造成更新失败） 7 - 添加单个 tag，对多个 token 而言 8 - 删除单个 tag，对多个 token 而言 9 - 批量添加标签（每次调用最多允许设置20对，每个对里面标签在前，token 在后） 10 - 批量删除标签（每次调用最多允许设置20对，每个对里面标签在前，token 在后）
token_list	Array	否	设备列表： operator_type = 1,2,3,4,5,6,7,8时，必填 operator_type = 1,2,3,4,5,6时如果该参数包含多个 token 只会设置第一个 token 格式 eg：["token1","token2"] 列表最大不能超过500个值 token 字符串长度不能超过36字符
tag_list	Array	否	标签列表： operator_type = 1,2,3,4,6,7,8时，必填，operator_type = 5时忽略 operator_type = 1,2,7,8 时，如果该参数包含多个 tag 时，如果只是对单个 tag 操作，则只会设置第一个 tag 格式 eg：["tag1","tag2"] 列表最大不能超过500个值 tag 字符串长度不能超过50字符
tag_token_list	Array	否	标签、设备对应列表： operator_type =9,10时，必填格式 eg： [{"tag":"tag123", "token":"token123"}] 每个对里面标签在前，token 在后列表最大不能超过500个值 tag 字符串长度不能超过50字符 token 字符串长度不能超过36字符

字段名	类型	是否必填	注释
ret_code	Integer	是	错误码，详细参照错误码对照表
err_msg	String	否	请求出错时的错误信息
seq	Integer	是	与请求包一致（如果请求包是非法 json 该字段为0）
result	String	否	请求正确时：若有额外数据要返回，则结果封装在该字段的 json 中若无额外数据，则此字段为空
invalid_tokens	array string	否	请求返回错误的 token
invalid_tags	array string	否	请求返回错误的 tags

标签绑定与解绑

本页目录：

接口说明

参数说明

请求参数

应答参数

示例说明

标签绑定解绑请求示例

标签设置请求示例

标签设置应答示例