标签绑定与解绑

最后更新时间:2020-10-16 19:57:39

    接口说明

    请求方式: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 在后)
    platform String 客户端平台类型:
  • Android:安卓 
  • iOS:苹果
  • 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"]
  • 列表最大不能超过20个值
  • 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"]
  • 列表最大不能超过20个值
  • tag 字符串长度不能超过50
  • tag_token_list Array 标签、设备对应列表:
  • operator_type =9,10时,必填
  • 格式 eg: [{"tag":"tag123", "token":"token123"}]
  • 每个对里面标签在前,token 在后
  • 列表最大不能超过20个值
  • tag 字符串长度不能超过50
  • token 字符串长度不能超过64
    • 单个应用最多可以有10000个自定义Tag, 每个设备Token最多可绑定100个自定义Tag,如需提高该限制,请与我们客服联系,每个自定义Tag可绑定的设备 token 数量无限制。
    • 如果仅单次而非连续的标签设置接口调用,则接口调用方式无限制。
    • 如果为连续标签设置接口调用,则需要注意如下:
      • 如果需要对超过10个标签或超过10个 token 的连续标签设置接口调用时,建议使用批量接口,但为保证标签操作的正确,建议两次接口调用的时间间隔不低于1s。
      • 如果调用非批量接口,则在明确拿到 TPNS 服务器的返回值时,再进行下次非批量标签接口调用,不建议使用多线程异步同时进行标签接口调用。
    • 英文冒号“:”是 TPNS 后台的关键字,用作标签的分类,如果设置标签时带了“:”,则将第一个“:”前面的字符串作为这个标签的类名,仅为了用于 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 请求出错时的错误信息
    result String 请求正确时:
  • 若有额外数据要返回,则结果封装在该字段的 json 中
  • 若无额外数据,则可能无此字段
  • 示例说明

    标签绑定解绑请求示例

    - 增加单个 tag1,对单个 token1

    {
        "operator_type": 1,
        "platform": "android",
        "tag_list": [
            "tag1"
        ],
        "token_list": [
            "token1"
        ]
    }

    - 删除单个 tag1,对单个 token1

    {
        "operator_type": 2,
        "platform": "android",
        "tag_list": [
            "tag1"
        ],
        "token_list": [
            "token1"
        ]
    }

    - 增加多个 tag1、tag2,对单个 token1

    {
        "operator_type": 3,
        "platform": "android",
        "tag_list": [
            "tag1",
            "tag2"
        ],
        "token_list": [
            "token1"
        ]
    }

    - 删除多个 tag1、tag2,对单个 token1

    {
        "operator_type": 4,
        "platform": "android",
        "tag_list": [
            "tag1",
            "tag2"
        ],
        "token_list": [
            "token1"
        ]
    }

    - 删除所有标签,对单个 token1

    {
        "operator_type": 5,
        "platform": "android",
        "tag_list": [
            "tag1",
            "tag2"
        ],
        "token_list": [
            "token1"
        ]
    }

    - 标签覆盖自定义类标签,对单个 token1

    {
        "operator_type": 6,
        "platform": "android",
        "tag_list": [
            "test:2",
            "level"
        ],
        "token_list": [
            "token1"
        ]
    }

    若有其中一个或多个标签不带“:”号,则将 test:2 和 level 标签覆盖 token1 的全部自定义标签。

    - 批量覆盖自定义类标签,对单个 token(此接口只覆盖到自定义类标签,而不是全部覆盖)

    {
        "operator_type": 6,
        "platform": "android",
        "tag_list": [
            "test:2",
            "level:2"
        ],
        "token_list": [
            "token1"
        ]
    }

    若全部标签都带“:”,由于第一个“:”前面的字符串为标签的类,则仅会覆盖设备对应相同类的标签,如test:2覆盖test:, level:2覆盖level:,不会影响其它标签。。

    - 为多个 token1、token2 添加单个 tag1

    {
        "operator_type": 7,
        "platform": "android",
        "tag_list": [
            "tag1"
        ],
        "token_list": [
            "token1",
            "token2"
        ]
    }

    - 多个 token1、token2 删除单个 tag1

    {
        "operator_type": 8,
        "platform": "android",
        "tag_list": [
            "tag1"
        ],
        "token_list": [
            "token1",
            "token2"
        ]
    }

    - 批量设置标签

    {
        "operator_type": 9,
        "platform": "android",
        "tag_token_list": [
            {
                "tag": "tag1",
                "token": "token1"
            }
        ]
    }

    - 批量删除标签,为 tag1、tag2、tag3 删除标签

    {
        "operator_type": 10,
        "platform": "android",
        "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,
        "platform": "android",
        "tag_list": [
            "tag1"
        ],
        "token_list": [
            "token1"
        ]
    }

    标签设置应答示例

    {
        "seq": 0,
        "ret_code": 0
    }

    Was this page helpful?

    本页内容是否解决了您的问题?

    • 完全没帮助
    • 文档较差
    • 文档一般
    • 文档不错
    • 文档很好
    反馈
    帮助