Device Group

Last Updated on : 2023-06-20 12:34:12download

This topic describes the related APIs of device groups.

API list

Request method	API	API description
GET	/v1.0/device-groups	Query device group list.
GET	/v1.0/device-groups/{group_id}	Query group details
GET	/v1.0/users/{uid}/device-groups	Query the group list
POST	/v1.0/device-groups	Create a device group
PUT	/v1.0/device-groups/{group_id}	Modify a device group
DELETE	/v1.0/device-groups/{group_id}	Delete a device group
POST	/v1.0/device-groups/{device_group_id}/issued	Send instructions to device groups.

Query device group list

API address

GET /v1.0/device-groups

Request parameter

Parameter name	Data type	Parameter type	Description	Required
uid	String	URL	User ID	No
pid	String	URL	Product ID	Yes
owner_id	String	URL	Home ID	Yes

Return parameter

Parameter name	Data type	Description
code	Integer	Error code.
success	Boolean	Whether the request succeeded or not. true: succeeded false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
t	Long	Return a 13-bit timestamp.
result	List	Device group list.

Result

Parameter name	Data type	Description
device_id	String	Device ID
device_name	String	Device name
online	Boolean	Online status
check	Boolean	Whether to check or not.

Request example

GET /v1.0/device-groups/?pid=jQRc7Cgy8OVzwSRG&uid=ay15512324287785nVuX&owner_id=379****

Return example

{
    "result": [
      {
        "device_id": "deveo45678op****",
        "device_name": "",
        "online": true,
        "check": false
      }
    ],
    "success": true,
    "t": 1586138482180
}

Error code

The following are common service exceptions for this API. For more exception errors, see Error Code.

Error code	Description
500	System error

Query group details

API address

GET /v1.0/device-groups/{group_id}

Request parameter

Parameter name	Data type	Parameter type	Description	Required
group_id	String	URI	Device group ID	Yes

Return parameter

Parameter name	Data type	Description
code	Integer	Error code.
success	Boolean	Whether the request succeeded or not. true: succeeded false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
t	Long	Return a 13-bit timestamp.
result	Object	Group details.

Result

Parameter name	Data type	Description
id	String	Device ID
name	String	Device name
device_num	Int	The number of devices
devices	List	Device information list

Devices

Parameter name	Data type	Description
device_id	String	Device ID
device_name	String	Device name
online	Boolean	Online status
check	Boolean	Whether to check or not.

Request example

GET /v1.0/device-groups/{group_id}

Return example

{
    "result": {
      "id": "",
      "name": "",
      "device_num": 1,
      "devices" : [{
        "device_id": "deveo45678op****",
        "device_name": "",
        "online": true,
        "check": false
      }]
      },
    "success": true,
    "t": 1586138482180
}

Error code

The following are common service exceptions for this API. For more exception errors, see Error Code.

Error code	Description
500	System error

Query the group list

API address

GET /v1.0/users/{uid}/device-groups

Request parameter

Parameter name	Data type	Parameter type	Description	Required
uid	String	URI	User ID	Yes
type	Int	URL	Group type: 0: single product group (default) 1: sub-device group	No

Return parameter

Parameter name	Data type	Description
code	Integer	Error code.
success	Boolean	Whether the request succeeded or not. true: succeeded false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
t	Long	Return a 13-bit timestamp.
result	List	Device group list.

Result

Parameter name	Data type	Description
id	String	Device ID
name	String	Device name
device_num	Int	The number of devices
devices	List	Device information list

Description of devices

Parameter name	Data type	Description
device_id	String	Device ID
device_name	String	Device name
online	Boolean	Online status
check	Boolean	Whether to check or not.

Request example

GET /v1.0/users/{uid}/device-groups

Return example

{
  "result": [
    {
      "id": "",
      "name": "",
      "device_num": 1,
      "devices": [
        {
          "device_id": "deveo45678op****",
          "device_name": "",
          "online": true,
          "check": false
        }
      ]
    }
  ],
  "success": true,
  "t": 1586138482180
}

Error code

The following are common service exceptions for this API. For more exception errors, see Error Code.

Error code	Description
500	System error

Create a group list

API address

POST /v1.0/device-groups

Request parameter

Parameter name	Data type	Parameter type	Description	Required
uid	String	Body	User ID	Yes
name	String	Body	Group name	Yes
pid	Int	Body	Product ID	Yes
owner_id	String	Body	Home ID	Yes
device_list	List	Body	Device	Yes

Return parameter

Parameter name	Data type	Description
code	Integer	Error code.
success	Boolean	Whether the request succeeded or not. true: succeeded false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
t	Long	Return a 13-bit timestamp.
result	Object	Device group list.

Result

Parameter name	Data type	Description
id	String	Group ID
name	String	Group name
functions	List	Command set

Request example

POST /v1.0/device-groups
{
    "uid":"aye78w****",
    "name":"test",
    "pid":"jhisd4****",
    "owner_id":"788732****",
    "device_list":["devo537878w7", "devo732878w7"],
}

Return example

{
  "result": [
    {
      "id": "5678978****",
      "name": "test",
      "functions": [
        {
          "code": "",
          "value": ""
        }
      ]
    }
  ],
  "success": true,
  "t": 1586138482180
}

Error code

The following are common service exceptions for this API. For more exception errors, see Error Code.

Error code	Description
500	System error

Modify a device group

API address

PUT /v1.0/device-groups/{group_id}

Request parameter

Parameter name	Data type	Parameter type	Description	Required
group_id	String	URI	Group ID	Yes
name	String	Body	Group name	Yes
device_list	List	Body	Device	Yes

Return parameter

Parameter name	Data type	Description
code	Integer	Error code.
success	Boolean	Whether the request succeeded or not. true: succeeded false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
t	Long	Return a 13-bit timestamp.
result	Boolean	Update results.

Request example

PUT /v1.0/device-groups/{group_id}
{
    
    "name":"test",
    "device_list":["devo537878w7", "devo732878w7"]
}

Return example

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

Error code

The following are common service exceptions for this API. For more exception errors, see Error Code.

Error code	Description
500	System error

Delete device group

API address

DELETE /v1.0/device-groups/{group_id}

Request parameter

Parameter name	Data type	Parameter type	Description	Required
group_id	String	URI	Device group ID	Yes

Return parameter

Parameter name	Data type	Description
code	Integer	Error code.
success	Boolean	Whether the request succeeded or not. true: succeeded false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
t	Long	Return a 13-bit timestamp.
result	Boolean	Delete results.

Request example

DELETE /v1.0/device-groups/787382328

Return example

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

Error code

The following are common service exceptions for this API. For more exception errors, see Error Code.

Error code	Description
500	System error

Send instructions to device groups

Note: The device types in the same device group are identical.

API address

POST /v1.0/device-groups/{device_group_id}/issued

Request parameter

Parameter name	Data type	Parameter type	Description	Required
device_group_id	String	URI	Device group ID	Yes
functions	Object	Body	Command set	Yes

Return parameter

Parameter name	Data type	Description
code	Integer	Error code.
success	Boolean	Whether the request succeeded or not. true: succeeded false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
t	Long	Return a 13-bit timestamp.
result	Object	Device group list.

Request example

POST /v1.0/device-groups/724682634/issued
{
   "functions"：[
   {
       "code":"switch_led",
       "value":true
   },
   {
       "code":"bright",
       "value":30
   }]
}

Return example

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

Error code

The following are common service exceptions for this API. For more exception errors, see Error Code.

Error code	Description
500	System error