User service-阿里云帮助中心

This service provides a set of user-related API operations. Cloud applications can use these operations to detach users, retrieve lists of devices attached to users, and more.

Perform a paged query for a user list
Query account information using a third-party external ID
Retrieve a list of devices attached to a user, including device details
Detach a user from a device
Forcefully detach all users from a device
Retrieve a third-party OpenID using an identity ID
Find all users attached to a device
Query account details using an identity ID
Update a user nickname on the platform from your account system

Perform a paged query for a user list

Description

path	Version	Description	cloudToken required
/cloud/account/queryIdentityByPage	1.0.4	Performs a paged query for the user list under a tenant.	Yes

Request parameters

Parameter	Type	Required	Description
offset	Integer	No	The query offset.
count	Integer	No	The number of entries to return on each page.

Response parameters

Name	Type	Description
identityId	String	The identity ID of the account.
loginId	String	Login ID
loginSource	String	The source of the account.
gmtCreate	Long	Creation Time
gmtModified	Long	Last Modified
loginName	String	The logon name.
phone	String	The phone number.
email	String	The email address.
nickName	String	The nickname.
avatarUrl	String	Profile picture
gender	String	The gender.
lastLoginTime	Date	The time of the last logon.
onlineStatus	Integer	The logon status of the account. 1: Online 0: Offline

Examples

Request example

{
     "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5",
      "request": {
        "cloudToken": "109049c8xxxxxxxxf62e29a3ba",
        "apiVer": "1.0.4"
      },
      "params": {
        "offset":0, "count":1
      },
      "version": "1.0"
}

Successful response example

{
    "code": 200,
    "data": [
        {
            "gmtModified": 1508314232000,
            "loginId": "4398047084811",
            "gmtCreate": 1508314232000,
            "identityId": "506bop1ef3axxxxxxxx7ae175ac94618",
            "loginSource": "openAccount",
            "loginName":"test",
            "phone":"1381111****",
            "email":"test@aliyun.com",
            "nickName":"test"
        }
    ],
    "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
}

Query account information using a third-party external ID

Description

path	Version	Description	cloudToken required
/cloud/account/getByOpenId	1.0.4	Queries account information using a third-party external ID.	Yes

Request parameters

Parameter	Type	Required	Description
openId	String	Yes	The external ID of your own account.
openIdAppKey	String	Yes	The appKey of the application.

Response parameters

Name	Type	Description
identityId	String	The identity ID of the account.
loginId	String	The openAccountId of the account.
loginSource	String	The source of the account.
gmtCreate	Long	Created At
gmtModified	Long	Last Modified
loginName	String	The logon name.
phone	String	The phone number.
email	String	mailbox
nickName	String	Nickname
tenantId	String	The tenant ID.
gender	String	The gender.
lastLoginTime	Long	The time of the last logon.
avatarUrl	String	Profile picture
onlineStatus	Integer	The logon status of the account. 1: Online 0: Offline

Examples

Request example

{
     "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5",
      "request": {
        "cloudToken": "109049c8xxxxxxxx6f62e29a3ba",
        "apiVer": "1.0.4"
      },
      "params": {
        "openId":"4398050099996", "openIdAppKey":"appkey1"
      },
      "version": "1.0"
}

Successful response example

{
    "code": 200,
    "data": 
        {
            "gmtModified":1515590332000,
            "loginId":"4398050099996",
            "gmtCreate":1513181985000,
            "lastLoginTime":1515590332000,
            "phone":"1390000****",
            "identityId":"5091op618xxxxxxxxe93ba653a5928119",
            "loginName":"1390000****",
            "tenantId":"45CFEA7xxxxxxxx05D59452B1437",
            "loginSource":"openAccount"
            "email":"test@aliyun.com",
            "nickName":"test"
        }
,
    "message":"success"
}

Get a list of devices attached to a user, including device details

Description

path	Version	Description	cloudToken required	Notes
/cloud/device/queryByUser	1.0.6	Gets a list of devices attached to a user, including device details.	Yes	Queries the list of devices attached to a user. Set different offsets to query any part of the records. A query for the total number of records is not supported.

Request parameters

Parameter	Type	Required	Description
openId	String	No	The external ID of the third-party user. You must specify either openId or identityId.
openIdAppKey	String	No	The appKey issued by the platform to the third-party application.
identityId	String	No	The identity ID of the user. You must specify either openId or identityId.
limit	int	No	This parameter was added in version 1.0.5. It specifies the maximum number of entries to return. The value of limit cannot exceed 100.
offset	int	No	This parameter was added in version 1.0.5. It specifies the offset.

Response parameters

Parameter	Type	Description
identityId	String	The identity ID of the user.
iotId	String	The iotId of the device.
productKey	String	The ProductKey of the device.
deviceName	String	The DeviceName of the device.
productName	String	The product name of the device.
categoryImage	String	The product image of the device.
productModel	String	The product model of the device.
nickName	String	The nickname that the user gives to the device.
netType	String	The network connection type of the device: LoRa: NET_LORA GPRS: NET_CELLULAR Wi-Fi: NET_WIFI Zigbee: NET_ZIGBEE Bluetooth: NET_BT Ethernet: NET_ETHERNET Other: NET_OTHER
thingType	String	The type of the Thing: VIRTUAL (virtual device) VIRTUAL_SHADOW (virtual shadow device) WEB APP DEVICE (regular device)
status	Byte	The status of the device. 0: Inactive, 1: Online, 3: Offline, 8: Disabled. Note This field is not supported in versions earlier than 1.0.6.
owned	int	The sharing flag. 0: Regular user (sharer) 1: Administrator (owner)

Examples

Request examples

Passing openId and openIdAppKey

{
   "id":"55428a70-a740-4xxxx-xxxx-89f727744740",
    "request": {
      "cloudToken": "109049cxxxxxxxx6f62e29a3ba",
      "apiVer": "1.0.6"
    },
    "params": {
      "openId":"10000000001",
      "openIdAppKey":"xxx",
      "limit":50,
      "offset":100
    },
    "version": "1.0"
}

Passing identityId

{
   "id":"55428a70-a740-xxxx-xxxx-89f727744740",
    "request": {
      "cloudToken": "109049c8xxxxxxxx6f62e29a3ba",
      "apiVer": "1.0.6"
    },
    "params": {
      "identityId": "506bop1efxxxxxxxx57ae175ac94618",
      "limit":50,
      "offset":100
    },
    "version": "1.0"
}

Successful response example

{
  "code": 200,
  "data": {
      "code": 200,
      "data": [{
          "iotId": "VPuHLddp6fixxxxxxxx10dbd910",
          "identityId": "50ceop3441838xxxxxxxx455be61f0356",
          "netType": "NET_WIFI",
          "thingType": "DEVICE",
          "productKey": "a1FNS8TYhpQ",
          "deviceName": "VD_sdDaqyTXeQ",
          "productName": "Fan3-Copy"
      }],
      "message": "success"
  },
  "id": "55428a70-a740-xxxx-xxxx-89f727744740"
}

Detach a user from a device

Description

path	Version	Description	cloudToken required
/cloud/user/device/unbind	1.0.4	Detaches a user from a device.	Yes

Request parameters

Parameter	Type	Required	Description
openId	String	No	The external ID of the third-party user. You must specify either openId or identityId.
openIdAppKey	String	No	The appKey issued by the Open Platform. This parameter is required if you use openId.
identityId	String	No	The identity ID of the user. You must specify either openId or identityId.
iotId	String	Yes	iotId

Response parameters

None.

Examples

Request examples

Pass openId and openIdAppKey

{
   "id":"3389580f-c698-xxxx-xxxx-b576c6d6c874",
    "request": {
      "cloudToken": "109049c80xxxxxxxx6f62e29a3ba",
      "apiVer": "1.0.4"
    },
    "params": {
      "openId":"10000000001",
      "openIdAppKey":"xxx"
      "iotId":"VPuHLddpxxxxxxxx0010dbd910"
    },
    "version": "1.0"
}

Pass identityId

{
   "id":"3389580f-c698-xxxx-xxxx-b576c6d6c874",
    "request": {
      "cloudToken": "109049c8xxxxxxxxf62e29a3ba",
      "apiVer": "1.0.4"
    },
    "params": {
      "identityId": "506bop1ef3a1xxxxxxxx7ae175ac94618"
      "iotId":"VPuHLddp6xxxxxxxx010dbd910"
    },
    "version": "1.0"
}

Successful response example

{
  "code": 200,
  "data": "",
  "id": "3389580f-c698-xxxx-xxxx-b576c6d6c874"
}

Forcefully detach all users from a device

Description

path	Version	Description	cloudToken required
/living/cloud/user/binding/device/unbind	1.0.0	Detaches all attachments from the specified device.	Yes

Request parameters

Parameter	Type	Required	Description
iotId	String	No	The unique ID of the device. This parameter is required if productKey and deviceName are empty.
productKey	String	No	The ProductKey of the device. This parameter is required if iotId is empty.
deviceName	String	No	The DeviceName of the device. This parameter is required if iotId is empty.

Response parameters

This operation does not return any business-related parameters.

Examples

Request example

{
     "id":"3389580f-c698-4a83-9eee-b576c6d6c874",
      "request": {
        "cloudToken": "109049c80bxxxxx06b15f6f62e29a3ba",
        "apiVer": "1.0.0"
      },
      "params": {
        "iotId":"Aawfy6tNxxxxxKOJ9Ffg000101"
      },
      "version": "1.0"
}

Successful response example

{
    "code": 200,
    "data": "",
    "id": "3389580f-c698-4a83-9eee-b576c6d6c874"
}

Get a third-party OpenID using an identity ID

Description

Path	Version	Description	cloudToken required
/cloud/account/openId/getByIdentityId	1.0.4	Gets a third-party OAuth OpenID using an identity ID.	Yes

Note Use this API operation only if you use a third-party account system.

Request parameters

Parameter	Type	Required	Description
identityId	String	Yes	The identity ID.
openIdAppKey	String	Yes	The appKey issued by the Open Platform.

Response parameters

Parameter	Type	Required	Description
data	String	Yes	The identity ID of the account.

Examples

Request example

{
    "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5",
    "request":{
        "apiVer":"1.0.4"
    },
    "params":{
        "identityId":"506bop1ef3xxxxxxxxf57ae175ac94618",
        "openIdAppKey":"12345678"
    },
    "version":"1.0"
}

Successful response example

{
    "code": 200,
    "data": "506bop1ef3a1cexxxxxxxx175ac94618",
"id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
}

Find all users attached to a device

Description

path	Version	Description	cloudToken required
/living/user/device/binding/query	1.0.0	Queries for accounts attached to a device based on the device iotId.	Yes

Request parameters

Parameter	Type	Required	Description
iotId	String	Yes	The device ID.
pageNo	Integer	Yes	The page number. Starts from 1.
pageSize	Integer	Yes	The number of entries per page.

Response parameters

Parameter	Sub-parameter	Second-level sub-parameter	Type	Description
data			JSON	The list of attached users.
	total		Integer	The total number of records.
	accountDevList		JSONArray	The list of attachments.
		deviceName	String	The DeviceName of the device.
		identityId	String	The user account ID.
		iotId	String	The iotId of the device.
		nickName	String	The nickname that the user sets for the device. Can be empty.
		owned	Integer	0: Sharer 1: Owner
		productKey	Date	The ProductKey of the device.
		productName	String	The product name of the device.

Examples

Request example

{
     "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5",
      "request": {
        "cloudToken": "109049c80bxxxxxxxx62e29a3ba",
        "apiVer": "1.0.0"
      },
      "params": {
        "iotId":"VPuHLddpxxxxxxxx0010dbd910",
        "pageNo": 1,
        "pageSize": 50
      },
      "version": "1.0"
}

Successful response example

{
    "code": 200,
    "data": 
{
    "accountDevList":[
        {
            "deviceName":"00158D00xxxxB3",
            "identityId":"50caop1fxxxxxxxxe55dae27b479165",
            "iotId":"OK61KXgxxxxxxxxtTk000100",
            "nickName":"Infrared Aisle 2",
            "owned":1,
            "productKey":"a1xxxxyZ",
            "productName":"Infrared Detector",
        }
    ],
    "total":1
},
    "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
}

Query account details using an identity ID

Description

path	Version	Description	cloudToken required
/cloud/account/getByIdentityId	1.0.4	Queries the details of an account using its IdentityId. You can get the IdentityId from the /cloud/account/queryIdentityByPage operation. Fields with no value are not returned.	Yes

Request parameters

Parameter	Type	Required	Description
identityId	String	Yes	Identity IDs

Response parameters

Name	Type	Description
identityId	String	The identity ID of the account.
loginId	String	The logon ID.
loginSource	String	The source of the account.
gmtCreate	Long	Creation Time
gmtModified	Long	Modification Time
loginName	String	The logon name.
phone	String	The phone number.
email	String	Mailbox
nickName	String	Nickname
avatarUrl	String	The profile picture.
gender	String	The gender.
lastLoginTime	Date	The time of the last logon.
onlineStatus	Integer	The logon status of the account. 1: Online 0: Offline

Examples

Request example

{
     "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5",
      "request": {
        "cloudToken": "109049c8xxxxxxxxf6f62e29a3ba",
        "apiVer": "1.0.4"
      },
      "params": {
        "identityId":"506bop1ef3xxxxxxxx57ae175ac94618"
      },
      "version": "1.0"
}

Successful response example

{
    "code": 200,
    "data": 
        {
            "gmtModified":1515590332000,
            "loginId":"4398050099996",
            "gmtCreate":1513181985000,
            "lastLoginTime":1515590332000,
            "phone":"1390000****",
            "identityId":"5091op61850061xxxxxxxxba653a5928119",
            "loginName":"1390000****",
            "tenantId":"45CFEA75xxxxxxxxD59452B1437",
            "loginSource":"openAccount"
            "email":"test@aliyun.com",
            "nickName":"test"
        },
    "message":"success"
}

Update a user nickname from your own account system on the platform

Description

path	Version	Description	cloudToken required
/user/account/info/update	1.0.0	-	Yes

Request parameters

Parameter	Type	Required	Description
openIdAppKey	String	Yes	The OpenId AppKey issued by the platform.
openId	String	No	The openId of your own account system.
identityId	String	No (You must specify at least one of openId or identityId)	The user account ID.
nickName	String	Yes	The user account nickname.

Response parameters

None.

Examples

Request example

{
     "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5",
      "request": {
        "cloudToken": "109049c8xxxxxxxxf6f62e29a3ba",
        "apiVer": "1.0.4"
      },
      "params": {
        "identityId":"506bop1ef3a1xxxxxxxxf57ae175ac94618",
        "nickName":"Feiyan User 001"
      },
      "version": "1.0"
}

Successful response example

{
    "code": 200,
    "data": {},
    "id":"bb179e80-39fd-xxxx-xxxx-48ca87a3f5c5"
}