Query Things Data Model

Last Updated on : 2024-06-29 01:56:38download

Query the things data model defined for the specified device.

API address

GET: /v2.0/cloud/thing/{device_id}/model

Request parameter

Parameter nameTypeINRequiredDescription
device_idStringpathtrueThe device ID.

Return parameter

Parameter nameTypeDescription
resultObjectThe returned result.

Description of result

Parameter nameTypeDescription
modelStringThe functional definition of the specified things data model. For more information about the data format of model values, see Data description of the model field.

Request example

GET: /v2.0/cloud/thing/372817193*****/model

Return example

{
    "result": {
        "model": "{\"modelId\":\"000004****\",\"services\":[{\"code\":\"\",\"description\":\"\",\"name\":\"\",\"actions\":[{\"code\":\"setPassword\",\"inputParams\":[{\"code\":\"password\",\"name\":\"Password\",\"typeSpec\":{\"typeDefaultValue\":\"\",\"type\":\"string\",\"maxlen\":1024}}],\"description\":\"Set or update the unlocking password on the app\",\"outputParams\":[{\"code\":\"state\",\"name\":\"State\",\"typeSpec\":{\"max\":100,\"scale\":0,\"type\":\"value\",\"unit\":\"\",\"min\":1,\"step\":0}}],\"name\":\"Set Password\",\"abilityId\":104}],\"events\":[{\"code\":\"doorStateEvent\",\"description\":\"Report the unlocking event when unlocking is triggered\",\"outputParams\":[{\"code\":\"doorState\",\"name\":\"Door State\",\"typeSpec\":{\"range\":[\"Open\",\"Closed\"],\"type\":\"enum\"}}],\"name\":\"Unlocking Event\",\"abilityId\":103}],\"properties\":[{\"code\":\"batterLevel\",\"description\":\"Battery level of the door lock\",\"accessMode\":\"rw\",\"name\":\"Remaining Battery Capacity\",\"typeSpec\":{\"max\":100,\"scale\":0,\"type\":\"value\",\"unit\":\"%\",\"min\":1,\"step\":0},\"abilityId\":102}]}]}"
    },
    "t": 1673423649773,
    "success": true
}

Error code

For more information, see error code.

Limits on API Request Frequency

For more information, see Limits on API Request Frequency.

Structure specification of model

When you call the APIs related to the things data model, the return parameter includes model. The value format of model is the storage structure defined by the things data model in the Developer Platform system.

Parameter nameTypeDescription
modelIdStringThe ID of the specified things data model.
servicesListThe definition list of services.

{
  "modelId": "00000****",
  "services": [
    {
      "code": "",
      "name": "",
      "description": "",
      "properties": [
      ],
      "actions": [
      ],
      "events": [
      ]
    }
  ]
}

Structure specification of service

Parameter nameTypeDescription
codeStringThe code to identify the specified service. An empty string represents the default service.
nameStringThe name of the specified service.
descriptionStringThe description or remarks of the specified service.
propertiesListThe list of property definitions. For the description of parameters in the property data structure, see Structure specification of property.
actionsListThe list of action definitions. For the description of parameters in the action data structure, see Structure specification of action.
eventsListThe list of event definitions. For the description of parameters in the event data structure, see Structure specification of event.

Structure specification of property

Parameter nameTypeDescription
abilityIdIntegerThe ID of the specified capability in the form of an integer value. The ID is unique in the same service.
codeStringThe code to identify the specified property. An empty string represents the default property.
nameStringThe name of the specified property.
descriptionStringThe description or remarks of the specified property.
accessModeStringThe access mode. Valid values: ro: read-only. wr: write-only. rw: read-write.
typeSpecObjectThe specification of data types, including value, float, double, string, date, bool, enum, raw, bitmap, struct, and array. For more information, see Data structure specification of typeSpec.

Structure specification of action

Parameter nameTypeDescription
abilityIdIntegerThe ID of the specified capability in the form of an integer value. The ID is unique in the same service.
codeStringThe code of the specified action. The code is unique in the same service.
nameStringThe name of the specified action.
descriptionStringThe description or remarks of the specified action.
inputParamsListThe input parameters for the specified action. For more information about the data structure, see Structure specification of inputParam and outputParam.
outputParamsListThe output parameters for the specified action. For more information about the data structure, see Structure specification of inputParam and outputParam.

Structure specification of event

Parameter nameTypeDescription
abilityIdIntegerThe ID of the specified capability in the form of an integer value. The ID is unique in the same service.
codeStringThe code of the specified event. The code is unique in the same service.
nameStringThe name of the specified event.
descriptionStringThe description or remarks of the specified event.
outputParamsListThe output parameters for the specified event. For more information about the data structure, see Structure specification of inputParam and outputParam.

Structure specification of inputParam and outputParam

Parameter nameTypeDescription
codeStringThe code of the specified parameter.
nameStringThe name of the specified parameter.
typeSpecObjectThe specification of data types, including value, float, double, string, date, bool, enum, raw, bitmap, struct, and array. For more information, see Structure specification of typeSpec type.

Structure specification of typeSpec type

Structure specification of value type

32-bit value type, which can be an integer or a decimal.

Parameter nameTypeRequiredDescription
typeStringYesThe value of type is value.
minIntegerYesThe minimum value.
maxIntegerYesThe maximum value.
stepIntegerNoThe step of change.
unitStringNoThe unit, such as cm.
scaleIntegerNoThe scale, used to represent decimals. The parameter value is the product of multiplying the actual value by the scale power of 10. Default value: 0.

Type example

{
  "type":"value",
  "min":1,
  "max":100,
  "step":0,
  "unit":"cm",
  "scale":0 
}

Structure specification of float and double types

float: single-precision floating-point number. double: double-precision floating-point number.

Parameter nameTypeRequiredDescription
typeStringYesThe value of type is float or double.
minIntegerYesThe minimum value.
maxIntegerYesThe maximum value.
stepIntegerNoThe step of change.
unitStringNoThe unit, such as cm.

Type example

{
  "type":"float",
  "min":0.1,
  "max":100.1,
  "step":0.1,
  "unit":"cm"
}

Structure specification of bool type

Boolean type data. The value is true or false.

Parameter nameTypeRequiredDescription
typeStringYesThe value of type is bool.

Type example

{
    "type":"bool"
}

Structure specification of date type

The timestamp type. It can be a 10-digit (in seconds) or 13-digit (in milliseconds) integer.

Parameter nameTypeRequiredDescription
typeStringYesThe value of type is date.

Type example

{
    "type":"date"
}

Structure specification of string type

String type.

Parameter nameTypeRequiredDescription
typeStringYesThe value of type is string.
maxlenIntegerNostring: The maximum length of a string is 255.

Type example

{
    "type":"string",
    "maxlen":100
}

Structure specification of enum type

The enum type.

Parameter nameTypeRequiredDescription
typeStringYesThe value of type is enum.
rangeListYesThe enumeration value. For example, the value is ["Male","Female"].

Type example

{
   "type":"enum",
   "range": [
     "Male","Female"
   ]
}

Structure specification of raw type

Base64-encoded binary raw data.

Parameter nameTypeRequiredDescription
typeStringYesThe value of type is raw. Base64-encoded binary raw data.
maxlenIntegerNoThe maximum number of bytes of binary data supported.

Type example

{
  "type":"raw",
  "maxlen":128
}

Structure specification of bitmap type

The bitmap type, with up to 32 bits.

Parameter nameTypeRequiredDescription
typeStringYesThe value of type is bitmap.
maxlenIntegerNoThe maximum number of bits supported. Maximum value: 32 bits.
rangeListYesThe description of each binary bit.

Type example

{
  "type":"bitmap",
  "maxlen":31,
  "label":[
    "Fault 1","Fault 2"
  ]
}

Structure specification of struct type

Complex structure nesting. Currently, the data type of the struct property only supports value, string, bool, enum, and raw.

Parameter nameTypeRequiredDescription
typeStringYesThe value of type is struct.
propertiesObjectYesThe struct object. For example, {"code1":"typeSpec","code2":"typeSpec"...}. The key is the property representation of the struct, and the value is the data type specification of the property, including value, float, double, string, date, bool, enum, raw, bitmap, struct, and array. For more information, see Structure specification of typeSpec type.

Type example

{
    "type":"struct",
    "properties":{
        "name":{
            "type":"date"
        },
        "sex":{
            "type":"enum",
            "range":[
                "Male",
                "Female"
            ]
        }
    }
}

Structure specification of array type

The data type of the elements in the array. Currently, only value, string, bool, and raw are supported.

Parameter nameTypeRequiredDescription
typeStringYesThe value of type is array.
maxSizeIntegerNoThe maximum number of elements supported.
elementTypeSpecObjectYesThe specification of data types for elements in the array, including value, float, double, string, date, bool, enum, raw, bitmap, struct, and array. For more information, see Structure specification of typeSpec type.

Type example

{
    "type":"array",
    "maxSize":100,
    "elementTypeSpec":{
        "type":"date"
    }
}