文档中心

用户属性指实时消息互动用户的信息，如用户昵称、头像、邮箱、电话、性别、签名、生日等。

例如，在招聘场景下，利用用户属性功能，可以存储性别、邮箱、用户类型（面试者）、职位类型（web 研发）等。当查看用户信息时，可以直接查询服务器存储的用户属性信息。

环信 IM 提供 RESTful API 接口方便开发者管理服务端的用户属性信息。

可以调用以下 RESTful API 实现用户属性功能：

#前提条件

要调用环信即时通讯 RESTful API，请确保满足以下条件：

• 已在环信即时通讯云控制台 开通配置环信即时通讯 IM 服务。
• 了解环信 IM REST API 的调用频率限制，详见 接口频率限制。

#公共参数

#请求参数

#响应参数

#认证方式

环信即时通讯 IM REST API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入如下 Authorization 字段：

Authorization: Bearer YourAppToken

为提高项目的安全性，环信使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。即时通讯 REST API 推荐使用 app token 的 鉴权方式，详见 使用环信 App Token 鉴权。

#设置用户属性

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

请求示例中使用的键为 avatarurl、ext、nickname，你可以根据实际使用场景确定键值。

#HTTP 请求

PUT https://{host}/{org_name}/{app_name}/metadata/user/{username}

#路径参数

参数及说明详见 公共参数。

#请求 header

#请求 body

请求 body 为 x-www-form-urlencoded 类型，发送请求时数据类型为 JSON String，长度不得超过 4 KB，包含以下字段：

例如:

requestBody = ‘name=ken&employer=easemob&title=developer’

JSONString = ‘{“name”:“ken”, “employer”:“easemob”, “title”:“developer”}’

这个 JSONString 的总长度不能超过 4 KB。

调用该 RESTful 接口设置用户昵称、头像、联系方式、邮箱、性别、签名、生日和扩展字段时，若要确保在客户端能够获取设置，请求中必须传以下键名，根据实际使用场景确定键值：

#HTTP 响应

#响应 body

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

其他字段及说明详见 公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 响应状态码 了解可能的原因。

#示例

#请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token curl -X PUT -H 'Content-Type: applic

ation/x-www-form-urlencoded' -H 'Authorization: Bearer <YourAppToken>' -d 'avatarurl=https

://www.easemob.com/avatar.png&ext=ext&nickname=nickname' 'https://XXXX/XXXX/XXXX/metadata/user/user1' 

#响应示例

{ "timestamp": 1620445147011, "data": { "ext": "ext", "nickname": "nickname", "avatarurl": 

"https://www.easemob.com/avatar.png" }, "duration": 166 } 

#获取用户属性

获取指定用户的全部用户属性键值对。需要在请求中填写 {username}，指定获取用户属性的用户 ID。

如果指定的用户或用户属性不存在，返回空数据 {}。

#HTTP 请求

GET https://{host}/{org_name}/{app_name}/metadata/user/{username}

#路径参数

参数及说明详见 公共参数。

#请求 header

#HTTP 响应

#响应 body

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

其他字段及说明详见 公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 响应状态码 了解可能的原因。

#示例

#请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token curl -X GET -H 'Content-Type: applicati

on/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/metadata/user/user1' 

#响应示例

{ "timestamp": 1620445147011, "data": { "ext": "ext", "nickname": "nickname", "avatarurl": "h

ttps://www.easemob.com/avatar.png" }, "duration": 166 } 

#批量获取用户属性

根据指定的用户 ID 列表和属性列表，查询用户属性。

如果指定的用户 ID 或用户属性不存在，返回空数据 {}。 每次最多可获取 100 个用户的属性。

#HTTP 请求

POST https://{host}/{org_name}/{app_name}/metadata/user/get

#路径参数

参数及说明详见 公共参数。

#请求 header

#请求 body

#HTTP 响应

#响应 body

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

其他字段及说明详见 公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 响应状态码 了解可能的原因。

#示例

#请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token curl -X POST -H 'Content-Type:  appl

ication/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
  "properties": [
    "avatarurl",
    "ext",
    "nickname"
  ],
  "targets": [
    "user1",
    "user2",
    "user3"
  ]
}' 'https://XXXX/XXXX/XXXX/metadata/user/get' 

#响应示例

{ "timestamp": 1620448826647, "data": { "user1": { "ext": "ext", "nickname": "nickname",

 "avatarurl": "https://www.easemob.com/avatar.png" }, "user2": { "ext": "ext", "nickname":

 "nickname", "avatarurl": "https://www.easemob.com/avatar.png" }, "user3": { "ext": "ext", 

"nickname": "nickname", "avatarurl": "https://www.easemob.com/avatar.png" } }, "duration": 3 } 

#获取 app 下用户属性总大小

获取该 app 下所有用户的属性数据大小，单位为字节。

#HTTP 请求

GET https://{host}/{org_name}/{app_name}/metadata/user/capacity

#路径参数

参数及说明详见 公共参数。

#请求 header

#HTTP 响应

#响应 body

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

其他字段及说明详见 公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 响应状态码 了解可能的原因。

#示例

#请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token curl -X GET -H 'Authorization: Bearer

 <YourAppToken>' 'https://XXXX/XXXX/XXXX/metadata/user/capacity' 

#响应示例

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

#删除用户属性

删除指定用户的所有属性。如果指定的用户或用户属性不存在（可能已删除），也视为删除成功。

#HTTP 请求

DELETE https://{host}/{org_name}/{app_name}/metadata/user/{username}

#路径参数

参数及说明详见 公共参数。

#请求 header

#HTTP 响应

#响应 body

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

其他字段及说明详见 公共参数。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 响应状态码 了解可能的原因。

#示例

#请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token curl -X DELETE -H 'Authorization: Bearer 

<YourAppToken>' 'https://XXXX/XXXX/XXXX/metadata/user/user1' 

#响应示例

{ "timestamp": 1616573382270, "duration": 10, "data": true }