用户属性管理 [IM 开发文档]

更新时间：2021-12-31 该文档已不再维护，请看新版 3.X 文档。

设置用户属性

对指定的用户设置用户属性。只有该用户本人或app管理员有权限做设置。

HTTP Request

	/{org_name}/{app_name}/metadata/user/{username}

Request Headers

参数	说明
Content-Type	application/x-www-form-urlencoded
Authorization	Bearer ${token}

Request Body

用户属性的内容为一个或多个纯文本键值对。默认单一用户的属性总长不得超过2KB. 默认一个app下所有用户的所有属性总长不得超过10GB。

请求示例中使用的键是avater、ext、nickname，当然这不是固定的只是举例，完全由您自己来决定键值是什么。

SDK端上的用户属性使用以下字段

字段	类型	备注
nickname	String	昵称
avatarurl	String	头像
phone	String	联系方式
mail	String	邮箱
gender	Number	性别
sign	String	签名
birth	String	生日
ext	String	自定义字段

Response Body

在返回值中查看data字段包含的信息

请求示例

curl -X PUT -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: Bearer WMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw12' -d 'avatarurl=http://www.easemob.com/avatar.png&ext=ext&nickname=nickname' 'http://a1.easemob.com/easemob-demo/testapp/metadata/user/user1'

可能返回的结果示例

返回值200，表示设置用户属性成功

{
    "timestamp":1620445147011,
    "data":{
        "ext":"ext",
        "nickname":"nickname",
        "avatarurl":"http://www.easemob.com/avatar.png"
    },
    "duration":166
}

返回值401，只有用户本人或app管理员有权修改他的属性。普通用户尝试修改一个不存在用户的属性时，也会返回401，因为普通用户无权知道某个用户名是否存在。

{
    "desc": "unauthorized",
    "duration": 10,
    "timestamp": 1616573382270
}

返回值403，您尝试设置的用户属性值超过长度限制。该限制可能是对一个用户下的属性总长限制，也可能是对一个app下所有用户属性的总长限制。

{
    "desc": "user metadata length exceed the limit",
    "duration": 10,
    "timestamp": 1616573382270
}

返回值404，表示用户不存在。

{
    "timestamp":1620445340631,
    "desc":"Not Found",
    "duration":0
}

返回值409，您尝试修改的用户已经被“别人”修改了。由于我们对用户属性使用乐观锁处理并发修改问题，当多个线程同时对同一用户做属性修改时，只有其中一个线程会修改成功并返回200，其他线程都会修改失败并返回409。

{
   "desc": "update userMetadata failed, concurrent updates not allowed",
   "duration": 10,
   "timestamp": 1616573382270
}

返回值500，一般是mysql错误。如果问题持续存在，请联系我们的技术支持团队。

{
   "desc": "org.hibernate.exception.JDBCConnectionException: Unable to acquire JDBC Connection",
   "duration": 10,
   "timestamp": 1616573382270
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

获取用户属性

获取指定用户的所有用户属性键值对。如果指定用户不存在，或指定用户的属性不存在，则返回空数据{}。

HTTP Request

	/{org_name}/{app_name}/metadata/user/{username}

需要在请求时对应填写{username}，需要获取用户属性的 IM 用户名。

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

在返回值中查看data字段包含的信息

请求示例

curl -X GET -H 'Content-Type: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/metadata/user/user1'

可能返回的结果示例

返回值200，表示获取用户属性成功

{
    "timestamp":1620446048161,
    "data":{
        "ext":"ext",
        "nickname":"nickname",
        "avatarurl":"http://www.easemob.com/avatar.png"
    },
    "duration":2
}

返回值404，表示该用户不存在

{
    "timestamp":1620446033278,
    "data":{

    },
    "duration":9
}

返回值500，一般是mysql错误。如果问题持续存在，请联系我们的技术支持团队。

{
    "desc": "org.hibernate.exception.JDBCConnectionException: Unable to acquire JDBC Connection",
    "duration": 10,
    "timestamp": 1616573382270
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

批量获取用户属性

根据指定的用户名列表和属性列表，查询用户属性。如果指定的用户/属性不存在，则返回空数据{}。每次最多指定100个用户。

HTTP Request

	/{org_name}/{app_name}/metadata/user/get

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

Request Body

参数	说明
targets	用户名列表，最多100个用户名
properties	属性名列表，查询结果只返回该列表中包含的属性，不在该列表中的属性将被忽略

Response Body

在返回值中查看data字段包含的信息

请求示例

curl -X POST -H 'Content-Type:  application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' -d '{
  "properties": [
    "avatarurl",
    "ext",
    "nickname"
  ],
  "targets": [
    "user1",
    "user2",
    "user3"
  ]
}' 'http://a1.easemob.com/easemob-demo/testapp/metadata/user/get'

可能返回的结果示例

返回值200，表示获取用户属性成功

{
    "timestamp":1620448826647,
    "data":{
        "user1":{
            "ext":"ext",
            "nickname":"nickname",
            "avatarurl":"http://www.easemob.com/avatar.png"
        },
        "user2":{
            "ext":"ext",
            "nickname":"nickname",
            "avatarurl":"http://www.easemob.com/avatar.png"
        },
        "user3":{
            "ext":"ext",
            "nickname":"nickname",
            "avatarurl":"http://www.easemob.com/avatar.png"
        }
    },
    "duration":3
}

返回值403，指定的用户名数量超过100

{
   "desc": "exceed allowed batch size 100",
   "duration": 10,
   "timestamp": 1616573382270
}

返回值500，一般是mysql错误。如果问题持续存在，请联系我们的技术支持团队。

{
    "desc": "org.hibernate.exception.JDBCConnectionException: Unable to acquire JDBC Connection",
    "duration": 10,
    "timestamp": 1616573382270
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

获取用户属性总量大小

获取该app下所有用户的用户属性总大小，单位Bytes。

HTTP Request

	/{org_name}/{app_name}/metadata/user/capacity

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

在返回值中查看data字段包含的信息

请求示例

curl -X GET -H 'Content-Type: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/metadata/user/capacity'

可能返回的结果示例

返回值200，表示获取用户属性总量大小成功

{
    "timestamp": 1620447051368,
    "data": 1673,
    "duration": 55
}

返回值401，只有app管理员有权限。

{
   "desc": "unauthorized",
   "duration": 10,
   "timestamp": 1616573382270
}

返回值500，一般是mysql错误。如果问题持续存在，请联系我们的技术支持团队。

{
    "desc": "org.hibernate.exception.JDBCConnectionException: Unable to acquire JDBC Connection",
    "duration": 10,
    "timestamp": 1616573382270
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试

删除用户属性

删除指定用户的所有用户属性。如果指定的用户不存在，或其用户属性不存在（也许已经被删除了），也视作删除成功。

HTTP Request

	/{org_name}/{app_name}/metadata/user/{username}

Request Headers

参数	说明
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

在返回值中查看data字段包含的信息，true代表删除成功

请求示例

curl -X DELETE -H 'Content-Type: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/metadata/user/user1'

可能返回的结果示例

返回值200，data为true表示删除用户属性成功，注意删除不存在用户也视作成功。

{
    "timestamp": 1620447526237,
    "data": true,
    "duration": 160
}

返回值401，只有用户本人或app管理员有权删除他的用户属性。

{
   "desc": "unauthorized",
   "duration": 10,
   "timestamp": 1616573382270
}

返回值500，一般是mysql错误。如果问题持续存在，请联系我们的技术支持团队。

{
    "desc": "org.hibernate.exception.JDBCConnectionException: Unable to acquire JDBC Connection",
    "duration": 10,
    "timestamp": 1616573382270
}

如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见接口限流说明

使用 Easemob REST API 在线测试