API Description

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.

Parameters

Request parameters

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: Required when operator_type is 1, 2, 3, 4, 5, 6, 7, or 8. When operator_type is 1, 2, 3, 4, 5, or 6 and this parameter contains multiple tokens, only the first token will be set. Format example: ["token1","token2"] The list can contain up to 500 values. A token string cannot exceed 36 characters.
tag_list	Array	No	Tag list: Required when operator_type is 1, 2, 3, 4, 6, 7, or 8; ignored when operator_type is 5. When operator_type is 1, 2, 7, or 8 and this parameter contains multiple tags, only the first tag will be set. Format example: ["tag1","tag2"] The list can contain up to 500 values. A tag string cannot exceed 50 characters.
tag_token_list	Array	No	Tag-device pair list: Required when operator_type is 9 or 10. Format example: [{"tag":"tag123", "token":"token123"}] In each pair, the tag is before the token. The list can contain up to 500 values. A tag string cannot exceed 50 characters. A token string cannot exceed 36 characters.

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 when operator_type is 6, which means overwriting tags by category. For example, if the existing tags of a device are level:1, level:2, and male, you can directly overwrite level:1 and level:2 with level:3 without having to unbind level:1 and level:2 one by one, and then bind level:3. For more information, please see the following sample request where operator_type is 6.

Response parameters

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: If there is extra data to return, the result will be encapsulated in this parameter in JSON format. If there is no extra data, this parameter may not exist.

Examples

Examples of Tag Binding and Unbinding Requests

• 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 the test:2 and level tags overwrite all custom tags of token1.

• Batch overwrite custom tags of a token (this API overwrites custom tags only, not all tags)

  {
   "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 overwrites test:*, and level:2 overwrites level:*, 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"
       }
   ]
  }
  

Example of Tag Setting Request

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"
  ]
}

Example of Tag Setting Response

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