Request method: POST
Service URL/v3/device/tag
API service URLs correspond to service access points one to one. Please select the service URL corresponding to the service access point of your application.
API features:
Tag API is the general term for all tag APIs. Tag API includes various APIs for setting, updating, and deleting which are described as below:
For use cases of tags, see Tag Feature.
Parameter | Type | Required | Description |
---|---|---|---|
operator_type | Integer | Yes | Operation type:1 : add a tag to a token.2 : delete a tag from a token.3 : add multiple tags to a token.4 : delete multiple tags from a token.5 : delete all tags from a token.6 : add one or more tags or custom tags to a token in an overwriting manner.(This API starts to set new tags only after the tag history is cleared. Therefore, for the same token, it is recommended that the interval between API calls be over 1s; otherwise, the update may fail.) 7 : add a tag to multiple tokens.8 : delete a tag from multiple tokens.9 : batch add tags (up to 20 pairs are allowed per call; in each tag-token pair, the tag is before the token).10 : batch delete tags (up to 20 pairs are allowed per call; in each tag-token pair, the tag is before the token). |
token_list | Array | No | Device list:operator_type is 1 , 2 , 3 , 4 , 5 , 6 , 7 , or 8 .operator_type is 1 , 2 , 3 , 4 , 5 , or 6 and this parameter contains multiple tokens, only the first token will be set. |
tag_list | Array | No | Tag list:operator_type is 1 , 2 , 3 , 4 , 6 , 7 , or 8 ; ignored when operator_type is 5 .operator_type is 1 , 2 , 7 , or 8 and this parameter contains multiple tags, only the first tag will be set. |
tag_token_list | Array | No | Tag-device pair list:operator_type is 9 or 10 . |
Note:
- An application can have up to 10,000 custom tags. A single device token can be bound to up to 100 custom tags (if you want to raise this limit, submit a ticket). A single custom tag can be bound to an unlimited number of device tokens.
- If the API needs to be called only once, then there are no restrictions on the API call method.
- If the API needs to be called continuously, note the following:
- If the API needs to be called continuously to set more than 10 tags or tokens, you are advised to use batch APIs. It is recommended that the interval between API calls be no less than 1s to guarantee correct tag operations.
- If not using batch APIs, you should make the next call of the non-batch tag API after the TPNS server returns a value. You are not advised to concurrently make multiple tag API calls in the multi-thread async mode.
- Colon
:
is a keyword used by the TPNS backend for tag categorization. If you include:
in a tag when setting it, the string before the first:
serves as the category name of the tag. This is only used whenoperator_type
is6
, which means overwriting tags by category. For example, if the existing tags of a device arelevel:1
,level:2
, andmale
, you can directly overwritelevel:1
andlevel:2
withlevel:3
without having to unbindlevel:1
andlevel:2
one by one, and then bindlevel:3
. For more information, please see the following sample request whereoperator_type
is6
.
Parameter | Type | Required | Description |
---|---|---|---|
ret_code | Integer | Yes | Error code. For more information, please see the error codes table. |
err_msg | String | No | Error message when a request error occurs |
result | String | No | When the request is correct: |
Add a tag (tag1) to a token (token1)
{
"operator_type": 1,
"tag_list": [
"tag1"
],
"token_list": [
"token1"
]
}
Delete a tag (tag1) from a token (token1)
{
"operator_type": 2,
"tag_list": [
"tag1"
],
"token_list": [
"token1"
]
}
Add multiple tags (tag1 and tag2) to a token (token1)
{
"operator_type": 3,
"tag_list": [
"tag1",
"tag2"
],
"token_list": [
"token1"
]
}
Delete multiple tags (tag1 and tag2) from a token (token1)
{
"operator_type": 4,
"tag_list": [
"tag1",
"tag2"
],
"token_list": [
"token1"
]
}
Delete all tags from a token (token1)
{
"operator_type": 5,
"tag_list": [
"tag1",
"tag2"
],
"token_list": [
"token1"
]
}
Overwrite custom tags of a token (token1)
{
"operator_type": 6,
"tag_list": [
"test:2",
"level"
],
"token_list": [
"token1"
]
}
Note:If one or more tags do not contain
:
, then thetest:2
andlevel
tags overwrite all custom tags oftoken1
.
{
"operator_type": 6,
"tag_list": [
"test:2",
"level:2"
],
"token_list": [
"token1"
]
}
Note:If all the tags contain
:
, since the string before the first:
is the tag category, only tags in the same category bound to the device will be overwritten; for example,test:2
overwritestest:*
, andlevel:2
overwriteslevel:*
, without affecting other tags.
Add a tag (tag1) to multiple tokens (token1 and token2)
{
"operator_type": 7,
"tag_list": [
"tag1"
],
"token_list": [
"token1",
"token2"
]
}
Delete a tag (tag1) from multiple tokens (token1 and token2)
{
"operator_type": 8,
"tag_list": [
"tag1"
],
"token_list": [
"token1",
"token2"
]
}
Batch set tags
{
"operator_type": 9,
"tag_token_list": [
{
"tag": "tag1",
"token": "token1"
}
]
}
Batch delete tags (tag1, tag2, and 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"
]
}
{
"seq": 0,
"ret_code": 0
}
Was this page helpful?