Device tags - IoT Platform - Alibaba Cloud Documentation Center

Some information about a device, such as the vendor and device model, can be reported to IoT Platform as device tags. You can also query and delete the tags of a device. This topic describes the topics and data formats that are used to submit, query, and delete device tags.

Submit tags

The following topics are used when a device sends requests to IoT Platform and IoT Platform sends responses to the device:

Request topic: /sys/${productKey}/${deviceName}/thing/deviceinfo/update
Response topic: /sys/${productKey}/${deviceName}/thing/deviceinfo/update_reply

Sample request in the Alink JSON format:

{
    "id": "123",
    "version": "1.0",
    "sys":{
        "ack":0
    },
    "params":[
        {
            "attrKey": "Temperature",
            "attrValue": "36.8"
        }
    ],
    "method": "thing.deviceinfo.update"
}

Sample response in the Alink JSON format:

{
    "id": "123",
    "code": 200,
    "data": {}
}

Parameters


Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version	String	The version number of the protocol. Set the value to 1.0.
sys	Object	The parameter for extended features. The value contains the fields for each feature. Note If no extended features are configured when you use a device SDK to develop device features, this parameter is unavailable. The extended features use the default configurations.
ack	Integer	The extended feature field in the sys parameter. This field specifies whether IoT Platform needs to return response data for the registration request. Valid values: 1: IoT Platform needs to return response data. 0: IoT Platform does not need to return response data. Important For more information about the parameter, see Examples on how to use a TSL model. If the feature is not configured, this parameter is unavailable. By default, IoT Platform returns response data for a registration request.
params	Object	The request parameters. The attrKey parameter specifies the tag key, and the attrValue parameter specifies the tag value. The params parameter can contain up to 200 elements in an array.
method	String	The request method. Set the value to `thing.deviceinfo.update`.
attrKey	String	The key of the tag. The key must be 1 to 30 characters in length, and can contain letters, digits, underscores (_), hyphens (-), number signs (#), at signs (@), percent signs (%), ampersands (&), asterisks (*), and periods (.).
attrValue	String	The value of the tag. The value must be 1 to 128 characters in length, and can contain Chinese characters, letters, digits, Japanese characters, underscores (_), hyphens (-), number signs (#), at signs (@), percent signs (%), ampersands (&), colons (:), and periods (.). Each Chinese character or Japanese character uses two characters.
code	Integer	The HTTP status code in the response. The value 200 indicates that the request was successful.

Error codes


Error code	Error message	Description
460	request parameter error	The error message returned because the request parameters are invalid.
6100	device not found	The error message returned because the device does not exist.

Queries tags

Important

You can query up to 10 tags at a time.
You can query only custom tags. You cannot query the internal tags of IoT Platform.
You must specify the key of the tag that you want to query. If you do not specify a tag key, no data is returned.

The following topics are used when a device sends requests to IoT Platform and IoT Platform sends responses to the device:

Request topic: /sys/${productKey}/${deviceName}/thing/deviceinfo/get
Response topic: /sys/${productKey}/${deviceName}/thing/deviceinfo/get_reply

Sample request in the Alink JSON format:

{
    "id": "123",
    "version": "1.0",
    "params":{ 
        "attrKeys":["attrKey1", "attrKey2", "attrKey3"]
    },
    "method": "thing.deviceinfo.get"
}

Sample response in the Alink JSON format:

{
    "id": "123",
    "code": 200,
    "data": [
        {
            "attrKey1":"v1"
        },
        {
            "attrKey2":"v2"
        },
        {
            "attrKey3":"v3"
        }
    ]
}

Parameters


Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version	String	The version number of the protocol. Set the value to 1.0.
params	Object	The request parameters. The attrKeys parameter specifies the keys of tags that you want to query.
attrKeys	JSONArray	The tag keys that you want to query. Note If a tag key is invalid, such as a duplicate tag key, an exception is returned. If a tag key does not exist, no data is returned. For more information about how to specify a tag in the key-value format for a device, see Add device tags.
method	String	The request method. Set the value to `thing.deviceinfo.get`.
data	JSONArray	The returned information about the tags, including the keys and values of the tags.
code	Integer	The HTTP status code in the response. The value 200 indicates that the request was successful.

The following table describes the error codes.


Error code	Error message	Description
460	request parameter error	The error message returned because the request parameters are invalid. For example, the value of the attrKeys parameter is not a JSON array, no tag keys are specified, the specified tag keys are duplicate, or the number of specified tag keys exceeds 10.
429	too many requests	The error message returned because throttling is triggered due to an excessively large number of queries per second (QPS). You can call this API operation up to 50 times per second per account. Note The RAM users of an Alibaba Cloud account share the quota of the account.

Delete tags

The following topics are used when a device sends requests to IoT Platform and IoT Platform sends responses to the device:

Request topic: /sys/${productKey}/${deviceName}/thing/deviceinfo/delete
Response topic: /sys/${productKey}/${deviceName}/thing/deviceinfo/delete_reply

Sample request in the Alink JSON format:

{
    "id": "123",
    "version": "1.0",
    "sys":{
        "ack":0
    },
    "params": [
        {
            "attrKey": "Temperature"
        }
    ],
    "method": "thing.deviceinfo.delete"
}

Sample response in the Alink JSON format:

{
    "id": "123",
    "code": 200,
    "data": {}
}

Parameters


Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version	String	The version number of the protocol. Set the value to 1.0.
sys	Object	The parameter for extended features. The value contains the fields for each feature. Note If no extended features are configured when you use a device SDK to develop device features, this parameter is unavailable. The extended features use the default configurations.
ack	Integer	The extended feature field in the sys parameter. This field specifies whether IoT Platform needs to return response data for the registration request. Valid values: 1: IoT Platform needs to return response data. 0: IoT Platform does not need to return response data. Important For more information about the parameter, see Examples on how to use a TSL model. If the feature is not configured, this parameter is unavailable. By default, IoT Platform returns response data for a registration request.
params	Object	The request parameters. The attrKey parameter specifies the keys of the tags that you want to delete.
method	String	The request method. Set the value to `thing.deviceinfo.delete`.
attrKey	String	The keys of the tags that you want to delete.
code	Integer	The HTTP status code in the response. The value 200 indicates that the request was successful.

Error codes


Error code	Error message	Description
460	request parameter error	The error message returned because the request parameters are invalid.
6100	device not found	The error message returned because the device does not exist.