User service
This document describes a set of user-related service APIs. Client applications can use these APIs to retrieve a list of devices that are attached to a user. You can also use these APIs to detach devices and push channels.
User-device attachment relationships
- Retrieve a list of devices attached to a user
- Retrieve attachment relationships by device
- Sort the device list
- Retrieve the sub-device list of a gateway
- Query the relationship between a user and a device
- Detach a user and a device
- Detach a device as an administrator
- Query the attachment relationships of sub-devices of a gateway
Device sharing
- Generate a QR code for sharing
- Attach a device by scanning a QR code
- Share a device with a specified user
- Retrieve the shared notification list
- Cancel a share request as the initiator
- Accept or reject a share request as the recipient
- Set a device nickname
- Delete the shared message list
- Query the sharing relationships between devices and a target user in a batch as an administrator
User-message attachment relationships
Virtual users
Get a list of devices attached to a user
Definition
| path | Version | Description | Requires user identity authentication |
| /uc/listBindingByAccount | 1.0.8 | Gets a list of devices attached to a user. | Yes |
Request parameters
| Parameter | Type | Required | Description |
| thingType | String | No | The type of the device.
|
| nodeType | String | No | The node type of the device. Valid values: DEVICE and GATEWAY. |
| owned | Integer | No | The attachment type. 0: a shared device. 1: an owned device. null: all devices. |
| isSubDevice | Boolean | No | Specifies whether the device is a sub-device.
|
| pageNo | Integer | Yes | The page number. The value starts from 1. |
| pageSize | Integer | Yes | The number of entries per page. The value must be greater than or equal to 1 and less than or equal to 100. |
Response parameters
| Parameter | Sub-parameter | Type | Description |
| total | - | Long | The total number of devices that meet the criteria. |
| pageNo | - | Integer | The page number. |
| pageSize | - | Integer | Page size |
| data | - | JSONArray | A list of device details. |
| - | identityId | String | The identity ID of the user. |
| - | iotId | String | The iotId of the device. This is the unique identifier of the device. |
| - | deviceName | String | The name of the device. |
| - | productKey | String | The ProductKey of the product to which the device belongs. |
| - | productName | String | The name of the product to which the device belongs. |
| - | productImage | String | The icon of the product to which the device belongs. If no product icon is defined, this field has the same value as the categoryImage field. |
| - | productModel | String | The model of the product to which the device belongs. |
| - | categoryImage | String | The icon of the product category to which the device belongs. |
| - | nickName | String | The nickname of the device. This can be empty. |
| - | netType | String | The network connection type of the device. Valid values:
|
| - | thingType | String | The type of the device.
|
| - | status | Byte | The status of the device. 0: inactive. 1: online. 3: offline. 8: disabled. |
| - | owned | Integer | The relationship between the device and the user. 0: sharer. 1: owner. |
| - | nodeType | String | The node type of the device. Valid values: DEVICE and GATEWAY. |
| - | identityAlias | String | The display name of the user, such as mobile, loginName, or email. |
| - | subDevice | Boolean | Indicates whether the device is a sub-device. true: a sub-device. false or null: not a sub-device (a directly connected device). |
| - | gmtModified | Date | The time when the attachment was modified (attachment time). |
Examples
- Request example
{ "id":"xxx", "version":"1.0.0", "request":{ "language":"en-US", "appKey":"xxx", "iotToken":"xxx", "apiVer":"1.0.0" }, "params":{ "isSubDevice":false, "pageNo":1, "pageSize":10 } } - Successful response example
{ "id":"4de2c367-xxxx-xxxx-aa15-8c585e595d92", "code":200, "message":"success", "localizedMsg":null, "data":{ "total":2, "pageNo":1, "pageSize":10, "data":[ { "identityId":"xxx", "iotId":"edwB6TqvxxxxxxNa000100", "deviceName":"Camera1", "productKey":"Product PK", "productName":"Product Name", "productImage":"Product Image", "productModel":"Product Model", "categoryImage":"xxx", "nickName":"Device Nickname", "netType":"NET_WIFI", "thingType":"DEVICE", "status":1, "owned":1, "nodeType":"DEVICE", "identityAlias":"133xxx", "subDevice":false, "gmtModified":"xxx" }, { "identityId":"xxx", "iotId":"xadqskxxxxxx9h000100", "deviceName":"Camera2", "productKey":"Product PK", "productName":"Product Name", "productImage":"Product Image", "productModel":"Product Model", "categoryImage":"xxx", "nickName":"Device Nickname", "netType":"NET_WIFI", "thingType":"DEVICE", "status":1, "owned":1, "nodeType":"DEVICE", "identityAlias":"133xxx", "subDevice":false, "gmtModified":"xxx" } ] } }
Get attachment relationships by device
Definition
| path | Version | Description | Requires user identity authentication |
| /uc/listBindingByDev | 1.0.2 | Gets attachment relationships by device. | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| iotId | String | Yes | The device ID. |
| pageNo | Int | Yes | The current page number. The value starts from 1. |
| pageSize | Int | Yes | The number of entries per page. This is the maximum number of items on a single page. |
| owned | Int | No | The attachment type of the device. 0: a device shared by others. 1: the device owner. null: all. |
Response parameters
| Parameter | Sub-key | Type | Description |
| total | - | Integer | The total number on the cloud. |
| pageNo | - | Integer | The current page number. |
| pageSize | - | Integer | Page size |
| data | - | List<> | A list of devices attached to the user. |
| - | identityId | String | The identity ID of the user. |
| - | iotId | String | The iotId of the device. |
| - | productKey | String | The ProductKey of the device. |
| - | deviceName | String | Device Name |
| - | productName | String | The name of the product. |
| - | productImage | String | The image of the product. |
| - | productModel | String | The model of the product. |
| - | categoryImage | String | The category icon. |
| - | nickName | String | The nickname of the device set by the user. This is the nickname set using setDeviceNickName. |
| - | netType | String | The network connection type of the device. |
| - | thingType | String | The type of the device.
|
| - | nodeType | String | The node type of the device: DEVICE, GATEWAY. |
| - | status | Byte | The status of the device. 0: inactive. 1: online. 3: offline. 8: disabled. |
| - | owned | Byte | 0: sharer. 1: owner. |
| - | identityAlias | String | The display name of the user: mobile, loginName, or email. |
| - | gmtModified | Date | The time when the attachment was modified. |
| - | description | String | The description. |
Examples
- Request example
{ "request": { "iotToken": "109049c80xxxxxxxxf62e29a3ba", "apiVer": "1.0.2" }, "id": 150821281****, "params": { "pageNo":1, "pageSize":10, "iotId":"fy2Z1oZFxxxxxxxx101edf00" }, "version": "1.0" } - Successful response example
{ "code": 200, "data": [ { "productModel": "testProduct", "iotId": "fy2Z1oZFxxxxxxx00101edf00", "netType": "NET_WIFI", "identityId": "5082opabf5192xxxxxxxx980ae6f6093", "thingType": "DEVICE", "nodeType": "DEVICE", "productKey": "a1xxxxJNb", "deviceName": "b65cb59xxxxxxxx08592cd695fb", "productName": "0dxxxx95", "status": 3 } ], "id": "e2d74ffe-308e-xxxx-xxxx-9b44a43eabc9" } - Error response example
{ "code":2064, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Request error", "message":"need authorize to bind" }
Sort the device list
Definition
| path | Version | Description | Requires user identity authentication |
| /uc/sortDevices | 1.0.2 | Sorts the devices. | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Sub-key | Type | Required | Description |
| sortDeviceDTOList | - | List<> | Yes | Data of devices whose sort order has changed. |
| - | iotId | String | Yes | The device ID. |
| - | fromOrder | Integer | Yes | The position of the device before the sort order changed. |
| - | toOrder | Integer | Yes | The position of the device after the sort order changed. |
Return parameters
Examples
- Request example
{ "request": { "iotToken": "109049c80xxxxxxxxf6f62e29a3ba", "apiVer": "1.0.2" }, "id": 150821281****, "params": { "sortDeviceDTOList":[ {"iotId": "Z75bTa4dxxxxxxxxRW001056af10", "fromOrder": 1, "toOrder": 3 }, {"iotId": "faHSHCOxxxxxxxxxZQoN00108dcf00", "fromOrder": 2, "toOrder": 1 }, {"iotId": "Spb4eatt1Lxxxxxxxx00108a4410", "fromOrder": 3, "toOrder": 2 } ] }, "version": "1.0" } - Successful response example
{ "code": 200, "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5" } - Error response example
{ "code":2000, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Request error", "message":"sortDevice param error!" }
Generate a QR code for sharing
Definition
| path | Version | Description | Requires user identity authentication |
| /uc/generateShareQrCode | 1.0.2 | Generates a QR code for sharing devices. Batch sharing is supported. The QR code is valid for 30 minutes. | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| iotIdList | List< String > | No | A list of device iotIds. The list can contain up to 20 iotIds. This parameter cannot be empty. |
Response parameters
| Parameter | Type | Description |
| qrKey | String | The generated QR code key. |
Examples
- Request example
{ "request": { "iotToken": "109049cxxxxxxxx6f62e29a3ba", "apiVer": "1.0.2" }, "id": 150821281****, "params": { "iotIdList":["xxxx"], "sceneIdList":["xxxx"] }, "version": "1.0" } - Successful response example
{ "code": 200, "data": { "qrKey": "xxxxxx" }, "id": "6ec222eb-87fc-xxxx-xxxx-351df196ceb3" } - Error response example
{ "code":2081, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Request error", "message":"scene not found by sceneId" }
Attach a device or scenario by scanning a QR code
Description
| path | Version | Description | Requires user identity authentication |
| /uc/scanBindByShareQrCode | 1.0.8 | Attaches a device or scenario by scanning a QR code. After attachment, the user becomes a regular member. | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| qrKey | String | Yes | The key of the scanned QR code. |
Response parameters
| Parameter | Type | Description |
| ScanShareQrCodeV2Resp | Object | A list of attached device or scenario IDs. |
| Parameter | Type | Description |
| iotIdList | List | A list of attached device or scenario IDs. |
Examples
- Request example
{ "request":{ "iotToken":"109049c80xxxxxxxx6f62e29a3ba", "apiVer":"1.0.2" }, "id":150821281****, "params":{ "homeId":"50f5opxxxxxxxxxxxxf28104512", "qrKey":"xxxx" }, "version":"1.0" } - Successful response example
{ "code":200, "message":"success", "localizedMsg":"", "data":{ "iotIdList":[ "CKuX1xxxxxxxxxxxxxxxx00100", "vbiM2xxxxxxxxxxxxxxxx00100" ] }, "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5" } - Error response example
{ "code":2067, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Request error", "message":"qrKey not exist" }
Share a device with a specified user
Definition
| path | Version | Description | Requires authentication |
| /uc/shareDevicesAndScenes | 1.0.8 | Shares devices and scenarios with other users by specifying their mobile number, email address, or identityId. If you use a proprietary account system, the mobile numbers and email addresses of your accounts are typically not stored on the IoT Platform. In this case, you can call this API using the mapping between your proprietary account IDs and IoT Platform identityIds. You must store this mapping yourself. You can share up to 20 devices at a time. | Yes. The client SDK must enable user identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| iotIdList | List< String > | Yes | A list of device iotIds. You can share up to 20 devices at a time. |
| targetIdentityId | String | No | The ID of the target identity to share with. You must specify either the user attribute pair or the identity ID. |
| accountAttr | String | No | The attribute that uniquely identifies the target user, such as a mobile number or an email address. |
| accountAttrType | String | No | The type of attribute that uniquely identifies the target user, such as a mobile number or an email address. MOBILE: mobile number. EMAIL: email address. |
| mobileLocationCode | String | No | The country code for the mobile number, such as 86. |
| autoAccept | Boolean | No | Specifies whether to automatically accept the share request. To use this parameter, you must enable the whitelist feature. |
Return parameters
Examples
- Request example
{ "request": { "iotToken": "109049c80xxxxxxx5f6f62e29a3ba", "apiVer": "1.0.2" }, "id": 150821281****, "params": { "accountAttr":"1365663****", "accountAttrType": "MOBILE", "iotIdList":[ "inqfGrp0xxxxxxxxpD00100fd600", "ETytXLwjxxxxxxxx4qG0010629e00" ] }, "version": "1.0" } - Successful response example
{ "code": 200, "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5" } - Error response example
{ "code":2064, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Request error", "message":"need authorize to bind" }
Get the shared notification list
Definition
| path | Version | Description | Requires user identity authentication |
| /uc/getShareNoticeList | 1.0.7 | Gets the shared notification list. | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| pageNo | Int | Yes | The current page number. The value starts from 1. |
| pageSize | Int | Yes | The number of entries per page. The maximum value is 200. If you specify a value greater than 200, the system queries 200 entries. |
| groupBy | String | No | Specifies whether to get the notification list by batch. Valid values: NONE and BATCH. If you set this parameter to BATCH, only one notification is returned for shares in the same batch. The default value is NONE, which means no groupBy processing is performed. |
Response parameters
| Parameter | Sub-key | Sub-key | Type | Description |
| total | - | - | Integer | The total number on the cloud. |
| pageNo | - | - | Integer | The current page number. |
| pageSize | - | - | Integer | Page size |
| data | - | - | List<> | The share list. |
| - | initiatorAlias | - | String | The account of the user who initiated the share, which can be a mobile number or an email address. |
| - | receiverAlias | - | String | The account of the user who received the share, which can be a mobile number or an email address. |
| - | targetId | - | String | The ID of the shared item. Note If you query by BATCH and a batch contains multiple records, this field is not returned. |
| - | targetType | - | String | The type of the shared item. |
| - | productImage | - | String | The product image of the device. |
| - | deviceName | - | String | The deviceName of the device. Note If you query by BATCH and a batch contains multiple records, this field is not returned. |
| - | isReceiver | - | Integer | Indicates whether the current user is the message recipient. |
| - | gmtCreate | - | Long | The creation time. |
| - | gmtModified | - | Long | The modification time. |
| - | recordId | - | String | The unique identifier of the share record. Note If you query by BATCH and a batch contains multiple records, this field is not returned. |
| - | batchId | - | String | The share batch ID. When devices are shared in a batch, they have the same batch ID. The client can use this ID to determine if shares belong to the same batch for aggregation and display. |
| - | status | - | Integer | The status.
|
| - | description | - | String | The description. |
| - | categoryImage | - | String | The category icon. Note If you query by BATCH and a batch contains multiple records, this field is not returned. |
| - | productName | - | String | The product name. Note If you query by BATCH and a batch contains multiple records, this field is not returned. |
| - | batchInfo | - | Struct | If a batch contains multiple records, this field is not empty and contains information about the batch. |
| - | - | recordCount | Integer | The number of share records in the current batch. For example, if 10 devices are shared in a batch, there are 10 corresponding share records. |
Examples
- Request example
{ "request":{ "iotToken":"109049c80xxxxxxxx5fe29a3ba", "apiVer":"1.0.2" }, "id":150821281****, "params":{ "pageNo":1, "pageSize":10, "groupBy":"BATCH" }, "version":"1.0" } - Successful response example
{ "code":200, "data":{ "total":1, "pageNo":1, "pageSize":10, "data":[ { "gmtCreate":"1390000****", "gmtModified":"1390000****", "description":"Sharing device with 1390000****, waiting for confirmation", "targetType":"DEVICE", "batchId":"ACCOUNT_DEV_SHARE_3fbd910a-xxxxxx-09aabf5fe5b5", "initiatorAlias":"1390000****", "receiverAlias":"1390000****", "isReceiver":0, "status":-1, "batchInfo":{ "recordCount":10 } } ] }, "id":"e2d74ffe-308e-xxxx-xxxx-9b44a43eabc9" } - Error response example
{ "code":2062, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Request error", "message":"identityId not exist" }
Get the shared notification list within a batch
Description
| path | Version | Description | Requires user identity authentication |
| /living/user/device/shared/record/query | 1.0.0 | Queries device sharing records. You can query by batch ID. | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| pageNo | Int | Yes | The current page number. The value starts from 1. |
| pageSize | Int | Yes | The number of entries per page. The maximum value is 20. |
| batchId | String | Yes | The ID of the batch to query. |
Response parameters
| Parameter | Sub-key | Type | Description |
| total | - | Integer | The total number on the cloud. |
| pageNo | - | Integer | The current page number. |
| pageSize | - | Integer | Page size |
| data | - | List<> | The share list. |
| - | initiatorAlias | String | The alias of the user who initiated the share. |
| - | receiverAlias | String | The alias of the user who received the share. |
| - | targetId | String | The ID of the shared item. |
| - | targetType | String | The type of the shared item. |
| - | productImage | String | The product image of the device. |
| - | deviceName | String | The deviceName of the device. |
| - | isReceiver | Integer | Indicates whether the current user is the message recipient. |
| - | gmtCreate | Long | The creation time. |
| - | gmtModified | Long | The modification time. |
| - | recordId | String | The unique identifier of the share record. |
| - | batchId | String | The share batch ID. When devices are shared in a batch, they have the same batch ID. The client can use this ID to determine if shares belong to the same batch for aggregation and display. |
| - | status | Integer | The status.
|
| - | description | String | Description |
| - | categoryImage | String | The category icon. |
| - | productName | String | The product name. |
Examples
- Request example
{ "request":{ "iotToken":"109049c80xxxxxxxx5fe29a3ba", "apiVer":"1.0.2" }, "id":150821281****, "params":{ "pageNo":1, "pageSize":10, "batchId":"ACCOUNT_DEV_SHARE_3fbd910a-xxxxxx-09aabf5fe5b5" }, "version":"1.0" } - Successful response example
{ "code":200, "data":{ "total":1, "pageNo":1, "pageSize":10, "data":[ { "gmtCreate":"1390000****", "gmtModified":"1390000****", "targetId":"fy2Z1oZFW********0101edf00", "categoryImage":"http://xxx", "description":"Sharing device with 1390000****, waiting for confirmation", "targetType":"DEVICE", "recordId":"a1OwEjYxxxxdfdFJNb", "batchId":"ACCOUNT_DEV_SHARE_3fbd910a-xxxxxx-09aabf5fe5b5", "deviceName":"b65cb59********92cd695fb", "productName":"0d****195", "initiatorAlias":"1390000****", "receiverAlias":"1390000****", "isReceiver":0, "status":-1 } ] }, "id":"e2d74ffe-308e-xxxx-xxxx-9b44a43eabc9" } - Error response example
{ "code":2062, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Request error", "message":"identityId not exist" }
Cancel a share request as the initiator
Description
| path | Version | Description | Requires user identity authentication |
| /uc/cancelShare | 1.0.7 | The initiator cancels the share request before the recipient accepts it. | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| recordIdList | List< String > | No | A list of share records. You must specify either recordIdList or batchId. |
| batchId | String | No | The batch ID. You must specify either recordIdList or batchId. If you specify batchId, the sharing of all devices in the batch is canceled. |
Return Parameters
Examples
- Request example
{ "request":{ "iotToken":"109049c8xxxxxxxx6f62e29a3ba", "apiVer":"1.0.2" }, "id":150821281****, "params":{ "recordIdList":[ "d4eb352adxxxxxxxx1d53febd503", "2568degt2xxxxxxxxe91fb61d53febd3" ] }, "version":"1.0" } - Successful response example
{ "code": 200, "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5" } - Error response example
{ "code":2093, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Request error", "message":"forbidden to repeat cancel sharing." }
Accept or reject a share request as the recipient
Definition
| path | Version | Description | Requires user identity authentication |
| /uc/confirmShare | 1.0.7 | The recipient accepts or rejects the share request. | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| recordIdList | List< String > | No | A list of share records. You can accept or reject up to 10 share requests at a time. You must specify either recordIdList or batchId. |
| agree | Integer | Yes | 0: Reject. 1: Accept. |
| batchId | String | No | The batch ID. You must specify either recordIdList or batchId. If you specify batchId, you accept or reject the sharing of all devices in the batch. |
Return parameters
Examples
- Request example
{ "request":{ "iotToken":"109049c80xxxxxxxxf62e29a3ba", "apiVer":"1.0.2" }, "id":150821281****, "params":{ "recordIdList":[ "d4eb352adxxxxxxxx53febd503", "2568degt2xxxxxxxx91fb61d53febd3" ], "agree":1 }, "version":"1.0" } - Successful response example
{ "code": 200, "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5" } - Error response example
{ "code":2092, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Request error", "message":"forbidden to repeat reject sharing." }
Set a device nickname
Definition
| path | Version | Description | Requires user identity authentication |
| /uc/setDeviceNickName | 1.0.2 | Sets a device nickname. | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| iotId | String | Yes | The device ID. |
| nickName | String | Yes | The nickname. |
Return parameters
Examples
- Request example
{ "request": { "iotToken": "109049cxxxxxxxxf6f62e29a3ba", "apiVer": "1.0.2" }, "id": 150821281****, "params": { "iotId": "5070op867xxxxxxxx49d87c207471699", "nickName":"nickName" }, "version": "1.0" } - Successful response example
{ "code": 200, "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5" } - Error response example
{ "code":2062, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Request error", "message":"identityId not exist" }
Detach a user and a device
Definition
| path | Version | Description | Requires user identity authentication |
| /uc/unbindAccountAndDev | 1.0.2 | Detaches a user from a device.
| Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| iotId | String | No | The device ID. |
Return parameters
Examples
- Request example
{ "request": { "iotToken": "109049c8xxxxxxxx62e29a3ba", "apiVer": "1.0.2" }, "id": 150821281****, "params": { "iotId":"xxxx" }, "version": "1.0" } - Successful response example
{ "code": 200, "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5" } - Error response example
{ "code":2062, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Request error", "message":"identityId not exist" }
Query the relationship between a user and a device
Definition
| path | Version | Description | Requires user identity authentication |
| /uc/getByAccountAndDev | 1.0.2 | Queries the relationship between a user and a device. If no relationship exists, a null object is returned. | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| iotId | String | Yes | The device ID. |
Response parameters
| Parameter | Type | Description |
| identityId | String | The identity ID of the user. |
| iotId | String | The iotId of the device. |
| Product key | String | The ProductKey of the device. |
| deviceName | String | The deviceName of the device. |
| productName | String | The name of the product. |
| productImage | String | The image of the product. |
| productModel | String | The model of the product. |
| nickName | String | The nickname of the device set by the user. |
| netType | String | The network connection type of the device. |
| thingType | String | The type of the device:
|
| nodeType | String | The node type of the device: DEVICE; GATEWAY. |
| status | Byte | The status of the device. 0: inactive. 1: online. 3: offline. 8: disabled. |
| owned | Byte | 0: sharer. 1: owner. |
| identityAlias | String | The display name of the user: mobile, loginName, or email. |
| gmtModified | Date | The time when the attachment was modified. |
Examples
- Request example
{ "request": { "iotToken": "109049c80xxxxxxxx6f62e29a3ba", "apiVer": "1.0.2" }, "id": 150821281****, "params": { "iotId":"xxxx" }, "version": "1.0" } - Successful response example
{ "code": 200, "data": { "productModel": "testProduct", "iotId": "fy2Z1oZxxxxxxxx101edf00", "netType": "NET_WIFI", "identityId": "5082opabf51xxxxxxxx06fbdae6f6093", "thingType": "DEVICE", "nodeType": "DEVICE", "productKey": "a1OxxxxNb", "deviceName": "b65cb59e6xxxxxxxx2cd695fb", "productName": "0d2xxxx95", "status": 3 }, "id": "e2d74ffe-308e-xxxx-xxxx-9b44a43eabc9" } - Error response example
{ "code":2063, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Request error", "message":"iotId not exist" }
Detach a device as an administrator
Description
| path | Version | Description | Requires user identity authentication |
| /uc/unbindByManager | 1.0.2 | After a user accepts a device share, an administrator can detach the specified user and device. The current logon user must be the administrator or owner of the device. | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| targetIdentityId | String | Yes | The identityId of the user who received the share (a regular member of the device), not the administrator's identityId. |
| iotIdList | List< String> | Yes | A list of IDs of the devices to detach. |
Response parameters
Examples
- Request example
{ "request": { "iotToken": "109049c80xxxxxxxx62e29a3ba", "apiVer": "1.0.2" }, "id": 150821281****, "params": { "targetIdentityId":"xxxx", "iotIdList":[ "d4eb352adxxxxxxxx1d53febd503", "2568degt2xxxxxxxx91fb61d53febd3" ] }, "version": "1.0" } - Successful response example
{ "code": 200, "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5" } - Error response example
{ "code":2083, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Request error", "message":"you are not the manager of some devices" }
Query the attachment relationships of sub-devices under a gateway
Definition
| path | Version | Description | Requires user identity authentication |
| /living/device/subdevice/query | 1.0.0 | Queries the attachment relationships between sub-devices under a gateway and end users. | Yes |
Request parameters
| Parameter | Type | Required | Description |
| iotId | String | No | The device ID. This is the unique identifier issued to the device by the IoT Platform. |
| productKey | String | No | The ProductKey. This is part of the device certificate information. It is the globally unique identifier that the IoT Platform issues to the product when it is created. |
| deviceName | String | No | The device name. |
| pageNo | Integer | Yes | The page number. The value starts from 1. |
| pageSize | Integer | Yes | The number of entries per page. Valid values: 1 to 20. |
| lang | String | Yes | The language. zh-CN: Chinese. en-US: English. |
Response parameters
| Parameter | Sub-parameter | Type | Description |
| total | - | Long | The total number of devices that meet the criteria. |
| pageNo | - | Integer | The page number. |
| pageSize | - | Integer | The number of entries per page. |
| data | - | JSONArray | A list of device details. |
| - | iotId | String | The iotId of the device. This is the unique identifier of the device. |
| - | deviceName | String | The name of the device. |
| - | productKey | String | The ProductKey of the product to which the device belongs. |
| - | bound | String | The attachment status. 0: not attached. 1: attached. |
| - | status | String | The status of the device.
|
| - | nickName | String | The nickname of the device. This can be empty. |
Examples
- Request example
{ 'id': str(uuid.uuid4()), 'version': "1.0", 'request': { 'iotToken': "xxxx", 'apiVer': "1.0.0" }, 'params': { # API parameters 'iotId':"value1", 'productKey':"value2", 'deviceName':"value3", 'pageNo':"value4", 'pageSize':"value5", 'lang':"value6" } } Example of a successful response
{ "id": "4de2c367-c1db-xxxx-xxxx-8c585e595d92", "code": 200, "message": null, "localizedMsg": null, "data": "xxxx" }Example: Failed response
{ "id": "37f7e5fa-d6a5-xxxx-xxxx-5bf23dca6284", "code": 403, "message": "request forbidden.", "localizedMsg": "Request forbidden", "data": null }
Delete the shared message list
Definition
| path | Version | Description | Requires user identity authentication |
| /uc/clearShareNoticeList | 1.0.2 | Deletes the shared message list, including all messages initiated and received by the user. | Yes. The client SDK must enable identity authentication. |
Request parameters
Response parameters
Examples
- Request example
{ "request": { "iotToken": "c4b3f64xxxxxxxe7a06a3c5dcb3", "apiVer": "1.0.2" }, "id": 150821281****, "params": { }, "version": "1.0" } - Successful response example
{ "code": 200, "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5" } - Error response example
{ "code":2062, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Request error", "message":"identityId not exist" }
Query the sharing relationships between devices and a target user in a batch as an administrator
Definition
| path | Version | Description | Requires user identity authentication |
| /living/user/device/shared/batch/get | 1.0.0 | An administrator queries the sharing relationships between devices and a target user in a batch. | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Zi Jian | Type | Required | Description |
| targetIdentityId | - | String | Yes | The identityId of the target user. This is the unique identifier of the user. |
| deviceList | JSONArray | Yes | The list of devices. The maximum size is 50. | |
| iotId | String | No | The unique iotId of the device.
| |
| productKey | String | No | The ProductKey of the product to which the device belongs. This field is required when the iotId field is empty. | |
| deviceName | String | No | The name of the device. This field is required when the iotId field is empty. |
Response parameters
| Parameter | Sub-parameter | Type | Description |
| data | - | JSONArray | A list of device sharing relationship details. |
| - | iotId | String | The iotId of the device. This is the unique identifier of the device. |
| - | productKey | String | The ProductKey of the product to which the device belongs. |
| - | deviceName | String | The name of the device. |
| - | shared | Boolean | Indicates whether the device is shared with the target user. |
Examples
- Request example
{ "id":"xxx", "version":"1.0.0", "request":{ "language":"en-US", "appKey":"xxx", "iotToken":"xxx", "apiVer":"xxx" }, "params":{ "targetIdentityId": "xxx", "deviceList":[ { "iotId":"edwB6xxxxNa000100" } ] } } - Successful response example
{ "code":200, "message":"success", "localizedMsg":"", "data":[ { "iotId":"edwB6xxxxNa000100", "productKey":"xxx", "deviceName":"xxx", "shared":true } ] }
Attach a push channel
Definition
| path | Version | Description | Requires user identity authentication |
| /uc/bindPushChannel | 1.0.2 | Link push channel | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| deviceId | String | Yes | The deviceId of the push channel. |
| deviceType | String | Yes | The device type, such as iOS or ANDROID. The value is determined by the business party and the app. |
Returned parameters
Examples
- Request example
{ "request": { "iotToken": "109049c80xxxxxxxxf62e29a3ba", "apiVer": "1.0.2" }, "id": 150821281****, "params": { "deviceId":"xxxx", "deviceType":"iOS" }, "version": "1.0" } - Successful response example
{ "code": 200, "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5" } - Error response example
{ "code":2062, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Request error", "message":"identityId not exist" }
Detach a push channel
Definition
| path | Version | Description | Requires user identity authentication |
| /uc/unbindPushChannel | 1.0.2 | Attach a push channel | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| deviceId | String | Yes | The deviceId of the push channel. |
Response parameters
Examples
- Request example
{ "request": { "iotToken": "109049c80xxxxxxxf62e29a3ba", "apiVer": "1.0.2" }, "id": 150821281****, "params": { "deviceId":"xxxx" }, "version": "1.0" } - Successful response example
{ "code": 200, "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5" } - Error response example
{ "code":2062, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Request error", "message":"identityId not exist" }
Get the sub-device list of a gateway
Description
| path | Version | Description | Requires user identity authentication |
| /subdevices/list | 1.0.2 | Gets a list of gateway sub-devices attached to a user. | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| iotId | String | Yes | The device ID. |
| pageNo | Int | Yes | The current page number. The value starts from 1. |
| pageSize | Int | Yes | The number of entries per page. This is the maximum number of items on a single page. |
Response parameters
| Parameter | Sub-key | Type | Description |
| total | - | Integer | The total number on the cloud. |
| pageNo | - | Integer | The current page number. |
| pageSize | - | Integer | Page size |
| data | - | List<> | The sub-device list. |
| - | iotId | String | The iotId of the device. |
| - | productKey | String | The ProductKey of the device. |
| - | deviceName | String | The deviceName of the device. |
| - | nickName | String | The name of the product. |
| - | image | String | The category image. |
| - | status | Byte | The online status of the device. 0: inactive. 1: online. 3: offline. 8: disabled. |
Examples
- Request example
{ "request": { "iotToken": "109049c8xxxxxxxx6f62e29a3ba", "apiVer": "1.0.2" }, "id": 150821281****, "params": { "iotId":"xxxxxxx", "pageNo":1, "pageSize":10 }, "version": "1.0" } - Successful response example
{ "code": 200, "data": [ { "iotId": "testIot", "productKey": "fy2Z1oZxxxxxxxx0101edf00", "deviceName": "NET_WIFI", "nickName": "xxxxxx", "image": "http://abc.jpg", "status": 0 }, { "iotId": "testIot", "productKey": "fy2Z1oZFxxxxxxxx00101edf00", "deviceName": "NExxxxFI", "nickName": "xxxxxx", "image": "http://abc.jpg", "status": 0 } ], "id": "e2d74ffe-308e-xxxx-xxxx-9b44a43eabc9" } - Error response example
{ "code":2062, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Request error", "message":"identityId not exist" }
Create a virtual user
Definition
| path | Version | Description | Requires user identity authentication |
| /uc/virtual/user/create | 1.0.4 | Creates a virtual user under the current logon user. | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| attrList | List | No | The properties and property values of the user. If this is empty, a user with no properties is created. The property key must be one of the specified system properties. |
| Parameter | Type | Required | Description |
| attrKey | String | Yes | The property key. |
| attrValue | String | Yes | The property value. |
Response parameters
| Parameter | Type | Description |
| userId | String | The ID of the created virtual user. |
| attrList | List | The property values of the user. This has the same meaning as the request parameter. |
| Parameter | Type | Required | Description |
| attrKey | String | Yes | The property key. |
| attrValue | String | Yes | The property value. |
Examples
- Request example
{ "request": { "iotToken": "109049xxxxxxxxf62e29a3ba", "apiVer": "1.0.4" }, "id": 150821281****, "params": { "attrList": [ { "attrKey":"name", "attrValue":"Xiaoming" } ] }, "version": "1.0" } - Successful response example
{ "code": 200, "message": "success", "data": { "userId":"10B6336Exxxxxxxx428F58AA5A18", "attrList":[ { "attrKey":"name", "attrValue":"Xiao Ming" } ] } } - Error response example
{ "code":503, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Service unavailable", "message":"service not available." }
Delete a virtual user
Description
| path | Version | Description | Requires user identity authentication |
| /uc/virtual/user/delete | 1.0.4 | Deletes a virtual user under the current logon user. | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| virtualUserId | String | Yes | Virtual user ID |
Response Parameters
Examples
- Request example
{ "request": { "iotToken": "109049c80xxxxxxxxf6f62e29a3ba", "apiVer": "1.0.4" }, "id": 150821281****, "params": { "userId":"10B633xxxxxxxx99BDD428F58AA5A18" }, "version": "1.0" } - Successful response example
{ "code": 200, "message": "success", "data": { "userId":"10B6336EFxxxxxxxx8F58AA5A18", "attrList":[ { "attrKey":"name", "attrValue":"John Doe" } ] } } - Error response example
{ "code":503, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Service unavailable", "message":"service not available." }
Update virtual user information
Definition
| path | Version | Description | Requires user identity authentication |
| /uc/virtual/user/update | 1.0.4 | Updates the information of a virtual user under the current logon user. | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| virtualUserId | String | Yes | The virtual user ID. |
| opType | Integer | Yes | The operation type (opType) for updating properties. Only the following types are supported: 1 (ADD), 2 (UPDATE), and 3 (DELETE). |
| attrList | List | Yes | The properties and property values of the user. The property key must be one of the specified system properties. |
attrList list structure
| Parameter | Type | Required | Description |
| attrKey | String | Yes | The property key. |
| attrValue | String | Yes | The property value. |
Response parameters
| Parameter | Type | Description |
| userId | String | The ID of the created virtual user. |
| attrList | List | The property values of the user. This has the same meaning as the request parameter. |
attrList list structure
| Parameter | Type | Required | Description |
| attrKey | String | Yes | The property key. |
| attrValue | String | Yes | The property value. |
Examples
- Request example
{ "request": { "iotToken": "109049c8xxxxxxxx6f62e29a3ba", "apiVer": "1.0.4" }, "id": 150821281****, "params": { "userId":"10B6336EFxxxxxxxx28F58AA5A18", "opType":2, "attrList":[ { "attrKey":"name", "attrValue":"Li" } ] }, "version": "1.0" } - Successful response example
{ "code": 200, "message": "success", "data": { "userId":"10B6336EFxxxxxxxx428F58AA5A18", "attrList":[ { "attrKey":"name", "attrValue":"John Doe" } ] } } - Error response example
{ "code":503, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Service unavailable", "message":"service not available." }
Query the virtual user list
Description
| path | Version | Description | Requires user identity authentication |
| /uc/virtual/user/list | 1.0.4 | Queries the list of virtual users under the current logon user. | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| pageNo | Integer | Yes | The current page number. The value starts from 1. |
| pageSize | Integer | Yes | The number of entries per page. This is the maximum number of items on a single page. |
Response parameters
| Parameter | Type | Description |
| total | Long | The total number of virtual users. |
| pageNo | Integer | The current page number. |
| pageSize | Integer | Page size |
| data | List | The virtual user list. |
| Parameter | Type | Required | Description |
| userId | String | Yes | The virtual user ID. |
| attrList | List | Yes | The properties and property values of the user. The property key must be one of the specified system properties. |
| Parameter | Type | Required | Description |
| attrKey | String | Yes | The property key. |
| attrValue | String | Yes | Property Value |
Examples
- Request example
{ "request": { "iotToken": "109049c80xxxxxxxxf62e29a3ba", "apiVer": "1.0.4" }, "id": 150821281****, "params": { "pageNo":1, "pageSize":10 }, "version": "1.0" } - Successful response example
{ "code": 200, "message": "success", "data": { "total":1, "pageNo":1, "pageSize":10, "data":[ { "userId":"10B633xxxxxxxxBDD428F58AA5A18", "attrList":[ { "attrKey":"name", "attrValue":"Xiao Ming" } ] } ] } } - Error response example
{ "code":503, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Service unavailable", "message":"service not available." }
Query virtual user details
Description
| path | Version | Description | Requires user identity authentication |
| /uc/virtual/user/query | 1.0.4 | Queries the details of a virtual user under the current logon user. | Yes. The client SDK must enable identity authentication. |
Request parameters
| Parameter | Type | Required | Description |
| virtualUserId | String | Yes | The virtual user ID. |
Response parameters
| Parameter | Type | Required | Description |
| userId | String | Yes | The virtual user ID. |
| attrList | List | Yes | The properties and property values of the user. The property key must be one of the specified system properties. |
| Parameter | Type | Required | Description |
| attrKey | String | Yes | The property key. |
| attrValue | String | Yes | The property value. |
Examples
- Request example
{ "request": { "iotToken": "109049cxxxxxxxxf6f62e29a3ba", "apiVer": "1.0.4" }, "id": 150821281****, "params": { "userId":"10B6336Exxxxxxxx428F58AA5A18" }, "version": "1.0" } - Successful response example
{ "code": 200, "message": "success", "data": { "userId":"10B633xxxxxxxx28F58AA5A18", "attrList":[ { "attrKey":"name", "attrValue":"John Doe" } ] } } - Error response example
{ "code":503, "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3", "localizedMsg":"Service unavailable", "message":"service not available." }
Virtual user attribute definition table
| Parameter | Type | Description |
| displayName | String | Display name |
| name | String | Name |
| gender | Integer | Gender (1: male. 2: female) |
| birthday | String | Birthday |
| String | QQ number | |
| employeeID | String | Employee ID |
| extNum | String | Office extension number |
| homeAddress | String | Home address |
| companyAddress | String | Company address |
| companyName | String | Company name |
| country | String | Country name |
| region | String | Region |
| avatar | String | Profile picture (URL of the profile picture) |