Device Management

API List

Request method	API	description
GET	/v1.0/osaas/projects/{project_id}/devices	API for Querying the Device List of a Project.
GET	/v1.0/osaas/rooms/{room_id}/devices	API for Querying the Device List of a Room.
GET	/v1.0/osaas/devices/{device_id}	API for Querying Device Details.
PUT	/v1.0/osaas/devices/{device_id}/name	API for Changing a Device Name.
GET	/v1.0/osaas/devices/{device_id}/split-devices	API for Querying the Spilt Device List
PUT	/v1.0/osaas/devices/{device_id}/split-devices	API for Batch Update Split Devices

API for Querying the Device List of a Project

API Description

You can use this API to query the device list of a project based on the unique ID of the project.

API Address

GET /v1.0/osaas/projects/{project_id}/devices

Request Parameters

Parameter	Type	Position	Description	Mandatory
project_id	String	URI	Unique ID of a project.	Yes
page_no	Integer	URL	Page number. The default value is 1.	No
page_size	Integer	URL	Number of records on a page, which is greater than 0 and less than 100. If this parameter is not set, the number is 20 by default.	No
device_ids	String[]	URL	List of device IDs, which contains a maximum of 100 device IDs.	No

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
total	Integer	Total number of records.
page_no	Integer	Page number.
page_size	Integer	Number of records on a page.
devices	Arrays	Device set.

Parameters in devices

Parameter	Type	Description
device_id	String	Unique ID of a device.
product_id	String	Unique ID of a product.
product_name	String	Product name.
category	String	Device type.
category_code	String	Code of a device type.
name	String	Device name.
active_time	Long	Activation time, which is a 13-digit timestamp.
gmt_create	Long	Creation time, which is a 13-digit timestamp.
online	Boolean	Device status. true: online false: offline
software_version	String	Software version.
product_module	String	Product model.
position	String	Location of a device.

Request Example

GET {url}/v1.0/osaas/projects/1160823965053******/devices

Success Response Example

{
  "result": {
    "total": 1,
    "page_no": 1,
    "page_size": 10,
    "devices": [
      {
        "active_time": 1610278970000,
        "category": "Lamp",
        "category_code": "dj",
        "device_id": "vdevo16102789******",
        "gmt_create": 1610278971070,
        "name": "Switch 1",
        "online": true,
        "position": "Test position",
        "product_id": "uvn******",
        "product_module": "",
        "product_name": "HY",
        "project_id": "125614875324******",
        "room_id": "1341704857710******",
        "software_version": "1.0.0"
      }
    ]
  },
  "success": true,
  "t": 1561381210234
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Querying the Device List of a Room

API Description

You can use this API to query the device list of a room based on the unique ID of the room.

API Address

GET /v1.0/osaas/rooms/{room_id}/devices

Request Parameters

Parameter	Type	Position	Description	Mandatory
room_Id	String	URI	Unique ID of a room.	Yes
page_no	Integer	URL	Page number. The default value is 1.	No
page_size	Integer	URL	Number of records on a page, which is greater than 0 and less than 100. If this parameter is not set, the number is 20 by default.	No
device_ids	String[]	URL	List of device IDs, which contains a maximum of 100 device IDs.	No

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
total	Integer	Total number of records.
page_no	Integer	Page number.
page_size	Integer	Number of records on a page.
devices	Arrays	Device set.

Parameters in devices

Parameter	Type	Description
device_id	String	Unique ID of a device.
product_id	String	Unique ID of a product.
product_name	String	Product name.
category	String	Device type.
category_code	String	Code of a device type.
name	String	Device name.
active_time	Long	Activation time, which is a 13-digit timestamp.
gmt_create	Long	Creation time, which is a 13-digit timestamp.
online	Boolean	Device status. true:online false:offline
software_version	String	Software version.
product_module	String	Product model.
position	String	Location of a device.

Request Example

 GET /v1.0/osaas/rooms/123******/devices

Success Response Example

{
  "result": {
    "total": 1,
    "page_no": 1,
    "page_size": 10,
    "devices": [
      {
        "active_time": 1610278970000,
        "category": "Lamp",
        "category_code": "dj",
        "device_id": "vdevo16102789******",
        "gmt_create": 1610278971070,
        "name": "Switch 1",
        "online": true,
        "position": "Test position",
        "product_id": "uvn******",
        "product_module": "",
        "product_name": "HY",
        "project_id": "125614875324******",
        "room_id": "1341704857710******",
        "software_version": "1.0.0"
      }
    ]
  },
  "success": true,
  "t": 1561381210234
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Querying Device Details

API Description

You can use this API to query device details based on the unique ID of the device.

API Address

GET /v1.0/osaas/devices/{device_id}

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
device_id	String	Unique ID of a device.
product_id	String	Unique ID of a product.
product_name	String	Product name.
category	String	Device type.
category_code	String	Code of a device type.
name	String	Device name.
active_time	Long	Activation time, which is a 13-digit timestamp.
gmt_create	Long	Creation time, which is a 13-digit timestamp.
online	Boolean	Device status. true:online false:offline
software_version	String	Software version.
product_module	String	Product model.
position	String	Location of a device.
project_id	String	Unique ID of the project to which a device belongs.
room_id	String	Unique ID of the room to which a device belongs.

Request Example

GET {url}/v1.0/osaas/devices/6c5cc1ce9718d******

Success Response Example

{
  "result": {
      "active_time": 1610278970000,
      "category": "Lamp",
      "category_code": "dj",
      "device_id": "vdevo16102789******",
      "gmt_create": 1610278971070,
      "name": "Switch 1",
      "online": true,
      "position": "Test position",
      "product_id": "uvn******",
      "product_module": "",
      "product_name": "HY",
      "project_id": "125614875324******",
      "room_id": "1341704857710******",
      "software_version": "1.0.0"
  },
  "success": true,
  "t": 1561381210234
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Changing a Device Name

API Description

You can use this API to change a custom device name based on the unique ID of the device.

API Address

PUT /v1.0/osaas/devices/{device_id}/name

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes
name	String	BODY	Device name, which contains a maximum of 32 characters.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Boolean	Result object.

Request Example

PUT {url}/v1.0/osaas/devices/008239650531******/name

{
  "name": "Switch 1"
}

Success Response Example

{
  "success": true,
  "t": 1545447665981,
  "result": true
  }

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Querying the Spilt Device List

API Description

You can use this API to querying the Spilt Device List

API Address

GET  /v1.0/osaas/devices/{device_id}/split-devices

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	List	Result object.

Parameters in result

Parameter	Type	Description
code	String	The function code of the device.
name	String	The split device name

Request Example

GET  {url}/v1.0/osaas/devices/6c5cc1ce9718d/split-devices

Success Response Example

{
    "result": [
        {
            "code": "switch_1",
            "name": "fan"
        }
    ],
    "success": true,
    "t": 1561381210234
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Batch Update Split Devices

API Description

You can use this API to batch Update Split Devices

API Address

PUT /v1.0/osaas/devices/{device_id}/split-devices

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes
split_devices	object	body	split device list.	Yes

Parameters in split_devices

Parameter	Type	Position	Description	Mandatory
code	String	body	The function code of the device	Yes
name	String	body	The split device name	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Boolean	Result

Request Example

PUT {url}/v1.0/osaas/devices/vdevo18*****7444/split-devices

{
"split_devices":[
        {
            "code": "switch_1",
            "name": "fun1"
        },
        {
            "code": "switch_2",
            "name": "fun2"
        },
        {
            "code": "switch_3",
            "name": "fun3"
        },
        {
            "code": "switch_4",
            "name": "fun4"
        }
 ]
}

Success Response Example

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

Error Code

The following are common business exceptions for this interface. For more exception errors, see Global Error Codes.

error code	explain
500	system error