===== 用户属性管理 =====

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

新版文档见：[[ccim:rest:userprofile|用户属性管理]]。

==== 设置用户属性 ====


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

=== HTTP Request ===

^{{:im:server:ready:put.png?nolink&90|}}^**/{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字段包含的信息

=== 请求示例 ===

<code php>
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'
</code>


=== 可能返回的结果示例 ===

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

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

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

<code json>
{
    "desc": "unauthorized",
    "duration": 10,
    "timestamp": 1616573382270
}
</code>

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

<code json>
{
    "desc": "user metadata length exceed the limit",
    "duration": 10,
    "timestamp": 1616573382270
}
</code>

**返回值404，表示用户不存在。** 
<code json>
{
    "timestamp":1620445340631,
    "desc":"Not Found",
    "duration":0
}
</code>

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

<code json>
{
   "desc": "update userMetadata failed, concurrent updates not allowed",
   "duration": 10,
   "timestamp": 1616573382270
}
</code>

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

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

如果返回结果是<wrap em>429、503</wrap>或者其他<wrap em>5xx</wrap>，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]]

[[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]]

----

==== 获取用户属性 ====

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

=== HTTP Request ===

^{{:im:server:ready:get.png?nolink&90 |}}^**/{org_name}/{app_name}/metadata/user/{username}**^
需要在请求时对应填写{username}，需要获取用户属性的 IM 用户名。

=== Request Headers ===

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

=== Response Body ===

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

=== 请求示例 ===

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

=== 可能返回的结果示例 ===

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

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

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

<code json>
{
    "timestamp":1620446033278,
    "data":{

    },
    "duration":9
}
</code>

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

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

如果返回结果是<wrap em>429、503</wrap>或者其他<wrap em>5xx</wrap>，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]]

[[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]]
----

==== 批量获取用户属性 ====

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

=== HTTP Request ===

^{{:im:server:ready:post.png?nolink&90 |}}^**/{org_name}/{app_name}/metadata/user/get**^

=== Request Headers ===

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

=== Request Body ===

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

=== Response Body ===

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

=== 请求示例 ===

<code php>
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'
</code>

=== 可能返回的结果示例 ===

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

<code json>
{
    "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
}
</code>

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

<code json>
{
   "desc": "exceed allowed batch size 100",
   "duration": 10,
   "timestamp": 1616573382270
}
</code>

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

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

如果返回结果是<wrap em>429、503</wrap>或者其他<wrap em>5xx</wrap>，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]]

[[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]]
----

==== 获取用户属性总量大小 ====

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

=== HTTP Request ===

^{{:im:server:ready:get.png?nolink&90 |}}^**/{org_name}/{app_name}/metadata/user/capacity**^

=== Request Headers ===

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

=== Response Body ===

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

=== 请求示例 ===

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

=== 可能返回的结果示例 ===

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

<code json>
{
    "timestamp": 1620447051368,
    "data": 1673,
    "duration": 55
}
</code>

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

<code json>
{
   "desc": "unauthorized",
   "duration": 10,
   "timestamp": 1616573382270
}
</code>

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

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

如果返回结果是<wrap em>429、503</wrap>或者其他<wrap em>5xx</wrap>，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]]

[[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]]
----

==== 删除用户属性 ====

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

=== HTTP Request ===

^{{:im:server:ready:delete.png?nolink&90 |}}^**/{org_name}/{app_name}/metadata/user/{username}**^

=== Request Headers ===

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

=== Response Body ===

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

=== 请求示例 ===

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

=== 可能返回的结果示例 ===

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

<code json>
{
    "timestamp": 1620447526237,
    "data": true,
    "duration": 160
}
</code>

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

<code json>
{
   "desc": "unauthorized",
   "duration": 10,
   "timestamp": 1616573382270
}
</code>

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

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

如果返回结果是<wrap em>429、503</wrap>或者其他<wrap em>5xx</wrap>，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]]

[[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]]
----