Thing model services-阿里云帮助中心

This topic describes a set of service APIs for things, which are devices in the Internet of Things (IoT). Cloud applications can use these APIs to query and control thing information, such as their basic information and property templates.

Get thing properties
Get a thing template
Triggering a service
Set thing properties
Get the connection status of a thing
Get the basic information of a thing
Get things in a batch
Get the event timeline data of a thing
Get the property timeline data of a thing
Query the sub-device list of a gateway

Get thing properties

Definition

Path	Version	Description	cloudToken required
/cloud/thing/properties/get	1.0.2	Gets the snapshot data of all properties of a thing.	Yes

Request parameters

Parameter	Type	Required	Description
iotId	String	No (required under specific conditions)	The unique identifier of the thing. This parameter is required if productKey and deviceName are empty.
productKey	String	No (required under specific conditions)	The unique identifier of the product. This parameter is required if iotId is empty.
deviceName	String	No (required under specific conditions)	The device name. This parameter is required if iotId is empty.

Response parameters

Parameter	Sub-parameter	Type	Description
data		Array	The list of data.
	attribute	String	The property name.
	batchId	String	The batch ID for the batch property report from the device.
	gmtModified	Date	The time when the device property was collected.
	iotId	String	The unique value of the device.
	value	Object	The property value.

Examples

Request example

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "cloudToken": "token"
    },
    "params": {
        "iotId": "D95D242xxxx4F31A2697"
    }
}

Successful response

{
    "code":200,
    "data":[
        {
            "attribute":"AppointmentTime",
            "batchId":"992751fxxxx5b00dac8f4f",
            "gmtModified":1566026333540,
            "iotId":"D95D2xxxxE4F31A2697",
            "value":0
        },
        {
            "attribute":"CO2",
            "batchId":"5729c1c31c6xxxx25fa3b8e",
            "gmtModified":156xxxx430,
            "iotId":"D95D24xxxxF31A2697",
            "value":825
        }
    ],
    "message":"success"
}

Get a thing template

Definition

Path	Version	Description	cloudToken required
/cloud/thing/tsl/get	1.0.2	Gets the Thing Specification Language (TSL) template of a thing. The template includes definitions for properties, events, and services.	Yes

Request parameters

Parameter	Type	Required	Description
iotId	String	No (required under specific conditions)	The unique identifier of the thing. This parameter is required if productKey and deviceName are empty.
productKey	String	No (required under specific conditions)	The unique identifier of the product. This parameter is required if iotId is empty.
deviceName	String	No (required under specific conditions)	The device name. This parameter is required if iotId is empty.

Response parameters

None

Examples

Request example

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "cloudToken": "token"
    },
    "params": {
        "iotId": "D95D2xxxx4F31A2697"
    }
}

Successful response

{
    "code": 200,
    "data": {
        "schema": "http://aliyun/iot/thing/desc/schema",
        "profile": {
            "productKey": "xxxxxxx",
            "deviceName": "xxxxxxxxxxxxxxxx"
        },
        "link": "/sys/a1xxxxpck/YzqExxxxjjo/thing/",
        "services": [
            {
                "outputData": [

                ],
                "identifier": "ToggleLightSwitch",
                "inputData": [

                ],
                "method": "thing.service.ToggleLightSwitch",
                "name": "Flip main light switch",
                "required": false,
                "callType": "async"
            }
        ],
        "properties": [
            {
                "identifier": "LightSwitch",
                "dataType": {
                    "specs": {
                        "0": "Off",
                        "1": "On"
                    },
                    "type": "bool"
                },
                "name": "Main light switch",
                "accessMode": "rw",
                "required": true
            }
        ],
        "events": [
            {
                "outputData": [
                    {
                        "identifier": "ErrorCode",
                        "dataType": {
                            "specs": {
                                "0": "Normal"
                            },
                            "type": "enum"
                        },
                        "name": "Error code"
                    }
                ],
                "identifier": "Error",
                "method": "thing.event.Error.post",
                "name": "Report error",
                "type": "info",
                "required": true
            }
        ]
    },
    "message": "success",
}

Trigger service

Description

Path	Version	Description	cloudToken required
/cloud/thing/service/invoke	1.0.2	Trigger Service	Yes

Request parameters

Parameter	Type	Required	Description
iotId	String	No	The unique identifier of the thing. If this parameter is not empty, it is used with priority.
productKey	String	Yes	The unique identifier of the product. This parameter is required.
deviceName	String	Yes	The device name. This parameter is required.
identifier	String	Yes	The service identifier.
args	JSON	Yes	The input parameters for the service.

Response parameters

Parameter	Type	Description
data	Object	The type and value of this response parameter depend on the implementation logic on the device.

Examples

Example request

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.1",
        "cloudToken": "token"
    },
    "params": {
        "iotId": "D95D2429xxxx4F31A2697",
        "identifier": "xxxx",
        "args": {}
    }
}

Example of a successful response

{
  "code": 200,
  "data": null,
  "message": "success",
  "localizedMsg": ""
}

Set thing properties

Definition

Path	Version	Description	cloudToken required
/cloud/thing/properties/set	1.0.2	Sets the properties of a thing.	Yes

Request parameters

Parameter	Type	Required	Description
iotId	String	No (required under specific conditions)	The unique identifier of the thing. This parameter is required if productKey and deviceName are empty.
productKey	String	No (required under specific conditions)	The unique identifier of the product. This parameter is required if iotId is empty.
deviceName	String	No (required under specific conditions)	The device name. This parameter is required if iotId is empty.
items	JSON	Yes	The parameters to set.

Response parameters

None

Examples

Request example

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "cloudToken": "token"
    },
    "params": {
        "iotId": "D95D24xxxxE4F31A2697",
        "items": {
            "LightSwitch1": 0,
            "LightSwitch2": 0
        }
    }
}

Successful response

{
  "code": 200,
  "data": null,
  "message": "success",
  "localizedMsg": ""
}

Get the connection status of a thing

Description

Path	Version	Description	cloudToken required
/cloud/thing/status/get	1.0.2	Gets the connection status of a thing.	Yes

Request parameters

Parameter	Type	Required	Description
iotId	String	No (required under specific conditions)	The unique identifier of the thing. This parameter is required if productKey and deviceName are empty.
productKey	String	No (required under specific conditions)	The unique identifier of the product. This parameter is required if iotId is empty.
deviceName	String	No (required under specific conditions)	The device name. This parameter is required if iotId is empty.

Response parameters

Parameter	Type	Description
status	Integer	The device status. 0: Inactive 1: Online 3: Offline 8: Disabled
time	Long	The time when the status changed.

Examples

Request example

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "cloudToken": "token"
    },
    "params": {
        "iotId": "D95D24xxxxCCE4F31A2697"
    }
}

Successful response

{
  "code": 200,
  "data": {
    "time": 1517923297000,
    "status": 3
  },
  "message": "success",
  "localizedMsg": null,
}

Get the basic information of a thing

Description

Path	Version	Description	cloudToken required
/cloud/thing/info/get	1.0.2	Gets the basic information of a thing.	Yes

Request parameters

Parameter	Type	Required	Description
iotId	String	No (required under specific conditions)	The unique identifier of the thing. This parameter is required if productKey and deviceName are empty.
productKey	String	No (required under specific conditions)	The unique identifier of the product. This parameter is required if iotId is empty.
deviceName	String	No (required under specific conditions)	The device name. This parameter is required if iotId is empty.

Response parameters

Parameter	Type	Description
gmtModified	Long	The time when the data was modified.
activeTime	Long	The time when the device was activated.
gmtCreate	Long	The time when the device was created.
productKey	String	The unique identifier of the product.
statusLast	Integer	The previous status of the device.
mac	String	The MAC address.
deviceSecret	String	The DeviceSecret of the device.
iotId	String	The unique identifier of the device.
name	String	The device name.
nickname	String	The device nickname.
sdkVersion	String	The SDK version.
sn	String	The device SN.
thingType	String	The device type.
region	String	The region.
firmwareVersion	String	The firmware version number.
rbacTenantId	String	The tenant ID.
status	Integer	Device Status

Examples

Request example

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "cloudToken": "token"
    },
    "params": {
        "iotId": "D95D24xxxxE4F31A2697"
    }
}

Successful response

{
    "code": 200,
    "data": {
        "gmtModified": 1517918765000,
        "activeTime": null,
        "deviceKey": "Kq7rgxxxxexwJh",
        "gmtCreate": 1500017648000,
        "productKey": "kQxxxxqA",
        "statusLast": null,
        "mac": null,
        "netAddress": null,
        "deviceSecret": "xxxxxxxxxxxxxxxxxxxxx",
        "iotId": "03iGXYVlxxxx9ccwgzHG",
        "name": "Kq7rgvxxxxexwJh",
        "tenantId": 7,
        "nickname": null,
        "sdkVersion": null,
        "sn": null,
        "thingType": "DEVICE",
        "region": "daily",
        "firmwareVersion": "1.0.0",
        "rbacTenantId": "ADSBCUYxxxx8327917",
        "ownerDomain": "kQxxxxqA",
        "status": 1
    },
    "message": "success",
    "localizedMsg": null
}

Get things in a batch

Definition

Path	Version	Description	cloudToken required
/cloud/things/get	1.0.2	Batch Retrieve Objects	Yes

Request parameters

Parameter	Type	Required	Description
productKey	String	Yes	Unique Product Identifier
status	Int	Yes	The device status. 0: Inactive 1: Online 3: Offline 8: Disabled
currentPage	Int	Yes	paged query
pageSize	Int	Yes	The number of entries per page.

Response parameters

Parameter	Type	Required	Description
totalNum	Long	Yes	The total number of records.
items	List	No	The list of devices. The parameters in the list are the same as the response parameters of the Get the basic information of a thing operation.

Examples

Request example

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "cloudToken": "token"
    },
    "params": {
        "productKey": "xxxxxxxxxxxxx",
        "status": 3,
        "currentPage": 1,
        "pageSize": 2
    }
}

Successful response

{
    "code": 200,
    "data": [
        {
            "gmtModified": 1517922329000,
            "offset": null,
            "activeTime": null,
            "deviceKey": "d7Clxxxxu1Lp",
            "gmtCreate": 1501110001000,
            "productKey": "wxxxxtR",
            "statusLast": null,
            "mac": null,
            "netAddress": null,
            "iotId": "d7CllTxxx0010990700",
            "deviceSecret": "u98xxxxzhy/4cV1ThAEGxxxxf48Cf6YX+sqcP1Ky7",
            "name": "\r\n",
            "tenantId": 7,
            "nickname": null,
            "limit": null,
            "sdkVersion": null,
            "sn": null,
            "thingType": "DEVICE",
            "region": "daily",
            "firmwareVersion": null,
            "rbacTenantId": "ADSBCxxxx327917",
            "ownerDomain": "wLxxxxtR",
            "status": 1
        },
        {
            "gmtModified": 1517922329000,
            "offset": null,
            "activeTime": null,
            "deviceKey": "K1XuExxxxWgiQaq",
            "gmtCreate": 1501123511000,
            "productKey": "wxxxR",
            "statusLast": null,
            "mac": null,
            "netAddress": null,
            "iotId": "K1XuEDskxxxxxxxxq0010d93300",
            "deviceSecret": "bZxxxj/hZs27AJsNKg3xxxxxxxxxxxxjqcP1Ky7",
            "name": "K1XuxxxxgiQaq",
            "tenantId": 7,
            "nickname": null,
            "limit": null,
            "sdkVersion": null,
            "sn": null,
            "thingType": "DEVICE",
            "region": "daily",
            "firmwareVersion": null,
            "rbacTenantId": "ADSBCUYxxxx27918327917",
            "ownerDomain": "wLxxxxtR",
            "status": 1
        }
    ],
    "message": "success",
    "localizedMsg": null
}

Get the event timeline data of a thing

Description

Path	Version	Description	cloudToken required
/cloud/thing/event/timeline/get	1.0.2	Gets the event timeline data of a thing. You can get data from the last year at most.	Yes

Request parameters

Parameter	Type	Required	Description
iotId	String	No (required under specific conditions)	The unique identifier of the thing. This parameter is required if productKey and deviceName are empty.
productKey	String	No (required under specific conditions)	The unique identifier of the product. This parameter is required if iotId is empty.
deviceName	String	No (required under specific conditions)	The device name. This parameter is required if iotId is empty.
identifier	String	Yes	Property Identifier
eventType	String	Yes	The event type.
start	Long	Yes	The start time of the timeline.
end	Long	Yes	The end time of the timeline.
pageSize	Int	Yes	The number of entries to return on each page.
ordered	Boolean	Yes	The query order. true: Ascending false: Descending

Response parameters

Parameter	Type	Description
eventCode	String	The event identifier.
iotId	String	The unique identifier of the thing.
eventName	String	The event name.
eventType	String	The event type.
eventBody	Object	The event parameters.
batchId	String	The batch ID.
timestamp	Long	The time when the data was collected.

Examples

Request example

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "cloudToken": "token"
    },
    "params": {
        "iotId": "D95D242941xxxxCCE4F31A2697",
        "identifier": "xxxx",
        "eventType": "xxxx",
        "start": 1517217645000,
        "end": 1517217645000,
        "pageSize": 10,
        "ordered": true
    }
}

Successful response

{
    "code": 200,
    "message": "success",
    "localizedMsg": "",
    "data": {
        "items": [
            {
                "eventCode": "Error",
                "iotId": "YzqEnI5Dxxxxjjo0010840500",
                "eventName": "Report error",
                "eventType": "info",
                "eventBody": {
                    "ErrorCode": 0
                },
                "batchId": "5ebc6a9c7dxxxxedde6d28c8fb3",
                "timestamp": 1516342985261
            },
            {
                "eventCode": "Error",
                "iotId": "YzqEnI5Dxxxxxxxxjo0010840500",
                "eventName": "Report error",
                "eventType": "info",
                "eventBody": {
                    "ErrorCode": 0
                },
                "batchId": "4a0b5a7ac8xxxxd5ff77456f1",
                "timestamp": 1516342995305
            }
        ],
        "timestamp": 1516343075699
    }
}

Get the property timeline data of a thing

Description

Path	Version	Description	cloudToken required
/cloud/thing/property/timeline/get	1.0.2	Gets the property timeline data of a thing. You can get data from the last year at most.	Yes

Request parameters

Parameter	Type	Required	Description
iotId	String	No (required under specific conditions)	The unique identifier of the thing. This parameter is required if productKey and deviceName are empty.
productKey	String	No (required under specific conditions)	The unique identifier of the product. This parameter is required if iotId is empty.
deviceName	String	No (required under specific conditions)	The device name. This parameter is required if iotId is empty.
identifier	String	Yes	The property identifier.
start	Long	Yes	The start time of the timeline.
end	Long	Yes	The end time of the timeline.
pageSize	Int	Yes	The number of entries to return on each page. Maximum value: 200.
ordered	Boolean	Yes	The query order. true: Ascending false: Descending

Response parameters

Parameter	Type	Description
iotid	String	The device identifier.
data	Object	The timeline data of the device.
modifytime	Long	The time when the property was updated.
property	String	The property identifier.
batchId	String	The batch ID.
timestamp	Long	The timestamp when the property was collected.

Examples

Request example

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "cloudToken": "token"
    },
    "params": {
        "iotId": "D95D24294xxxx1ECCE4F31A2697",
        "identifier": "xxxx",
        "start": 1517217645000,
        "end": 1517217645000,
        "pageSize": 10,
        "ordered": true
    }
}

Successful response

{
  "code": 200,
  "message": "success",
  "localizedMsg": null,
  "data": {
    "items": [
      {
        "iotid": "xqxyZjSKzCxxxxvbv0O0010851c00",
        "data": 1.23,
        "modifytime": 1511812747287,
        "property": "LightVolt",
        "batchId": "2fc766c5e7xxxx3ed1f3e4b61803",
        "group": null,
        "timestamp": 1511812747245
      },
      {
        "iotid": "xqxyZjSKzxxxx0O0010851c00",
        "data": 1.24,
        "modifytime": 1511812747288,
        "property": "LightVolt",
        "batchId": "2fc766c5exxxx3ed1f3e4b61803",
        "group": null,
        "timestamp": 1511812747245
      }
    ],
    "timestamp": 1511812747245
  }
}

Query the sub-device list of a gateway

Definition

Path	Version	Description	cloudToken required
/living/cloud/device/subdevice/query	1.0.0	Performs a paged query for a list of sub-devices of a gateway.	Yes

Request parameters

Parameter	Type	Required	Description
iotId	String	No (required under specific conditions)	The unique identifier of the thing. This parameter is required if productKey or deviceName is empty.
productKey	String	No (required under specific conditions)	The key of the product. This parameter is required if iotId is empty.
deviceName	String	No (required under specific conditions)	The device name. This parameter is required if iotId is empty.
pageNo	Int	Yes	The page number for the paged query.
pageSize	Int	Yes	The number of entries per page for the paged query. Maximum value: 20.

Response parameters

Parameter	Level-1 sub-parameter	Level-2 sub-parameter	Type	Description
data				The list of sub-devices of the gateway.
	total		Long	The total number of sub-devices.
	pageNo		Int	The current page number. Page numbers start from 1.
	pageSize		Int	Page size
	items		JSON Array	Device Certificate List
		iotId	String	The device ID.
		deviceName	String	The device name.
		productKey	String	The ProductKey of the device.
		thingType	String	The type of the device: VIRTUAL WEB APP DEVICE
		firmwareVersion	String	The firmware version number. This value is reported by the device. If the device has not reported this value, this parameter is not returned.
		sdkVersion	String	The SDK version number.
		status	Int	The device status. 0: Inactive 1: Online 3: Offline 8: Disabled
		nodeType	String	The node type of the device: DEVICE GATEWAY
		region	String	The site where the device is located.
		rbacTenantId	String	The ID of the tenant to which the device belongs.
		gmtCreate	Long	The time when the record was created. This is the total number of milliseconds from 1970-01-01 to the present.
		gmtModified	Long	The time when the record was modified. This is the total number of milliseconds from 1970-01-01 to the present.

Examples

Request example

{
    "id": "15090xxxx4180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.0",
        "cloudToken": "tokenxxxxxxxx"
    },
    "params": {
      "iotId":"CHWlsAQxxxxxMy4zs000101",
      "pageNo":1,
      "pageSize":10
    }
}

Successful response

{
    "code":200,
    "data":{
        "total":1,
        "pageNo":1,
        "pageSize":10,
        "items":[
            {
                "iotId":"c2NBjWQUxxxxxxxxTPFu8000101",
                "gmtModified":15789xxxx6000,
                "thingType":"DEVICE",
                "productKey":"a1HxxxxRiox",
                "region":"cn-hangzhou",
                "gmtCreate":15789xxxx6000,
                "deviceName":"tesxxxxv0",
                "rbacTenantId":"380D6988CxxxxxxxxxD9CBBDAC071",
                "status":0
            }
        ]
    },
    "id":"3f757e2b-xxxx-xxxx-9926-b435bfe4bb6e"
}