管理用户属性
管理用户属性
用户属性指实时消息互动用户的信息,如用户昵称、头像、邮箱、电话、性别、签名、生日等。
例如,在招聘场景下,利用用户属性功能,可以存储性别、邮箱、用户类型(面试者)、职位类型(web 研发)等。当查看用户信息时,可以直接查询服务器存储的用户属性信息。
环信 IM 提供 RESTful API 接口方便开发者管理服务端的用户属性信息。
提示
为保证用户信息安全,环信即时通讯 IM 仅支持用户本人或 app 管理员设置用户属性。
可以调用以下 RESTful API 实现用户属性功能:
功能 | 描述 |
---|---|
设置用户属性 | 设置指定的用户属性。 |
获取指定用户的所有用户属性 | 获取指定用户的所有用户属性。 |
批量获取用户属性 | 根据指定的用户名列表和属性列表查询用户属性。 |
删除用户属性 | 删除指定用户的所有属性。 |
获取 app 下用户属性总大小 | 获取该 app 下所有用户的属性总大小。 |
前提条件
要调用环信即时通讯 RESTful API,请确保满足以下条件:
- 已在环信即时通讯云控制台 开通配置环信即时通讯 IM 服务。
- 了解环信 IM REST API 的调用频率限制,详见 接口频率限制。
公共参数
请求参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
host | String | 是 | 环信即时通讯 IM 分配的用于访问 RESTful API 的域名。详见 获取环信即时通讯 IM 的信息。 |
org_name | String | 是 | 环信即时通讯 IM 为每个公司(组织)分配的唯一标识。详见 获取环信即时通讯 IM 的信息。 |
app_name | String | 是 | 你在环信即时通讯云控制台创建应用时填入的应用名称。详见 获取环信即时通讯 IM 的信息。 |
username | String | 是 | 用户 ID。 |
响应参数
参数 | 类型 | 描述 |
---|---|---|
organization | String | 环信即时通讯 IM 为每个公司(组织)分配的唯一标识,与请求参数 org_name 相同。 |
application | String | 应用在系统内的唯一标识。该标识由系统生成,开发者无需关心。 |
applicationName | String | 你在环信即时通讯云控制台创建应用时填入的应用名称,与请求参数 app_name 相同。 |
entities | Object | 响应实体。 |
username | String | 用户 ID。 |
data.nickname | String | 用户昵称。 |
data.ext | String | 自定义的用户属性扩展字段。 |
data.avatarurl | String | 用户头像 URL。 |
timestamp | Long | Unix 时间戳,单位为毫秒。 |
duration | Long | 从发送 HTTP 请求到响应的时长, 单位为毫秒。 |
认证方式
环信即时通讯 IM REST API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时,都必须在请求头部填入如下 Authorization
字段:
Authorization: Bearer YourAppToken
为提高项目的安全性,环信使用 Token(动态密钥)对即将登录即时通讯系统的用户进行鉴权。即时通讯 REST API 推荐使用 app token 的 鉴权方式,详见 使用环信 App Token 鉴权。
设置用户属性
用户属性的内容为一个或多个纯文本键值对,默认单个用户的属性总长度不能超过 2 KB,默认单个 app 下所有用户的属性总长度不能超过 10 GB。利用该 API,每次只能设置一个用户的用户属性。
请求示例中使用的键为 avatarurl
、ext
、nickname
,你可以根据实际使用场景确定键值。
HTTP 请求
PUT https://{host}/{org_name}/{app_name}/metadata/user/{username}
路径参数
参数及说明详见 公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 是 | 内容类型。请填 application/x-www-form-urlencoded 。 |
Authorization | String | 是 | App 管理员的鉴权 token,格式为 Bearer YourAppToken ,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。 |
请求 body
请求 body 为 x-www-form-urlencoded
类型,包含以下字段:
字段 | 类型 | 描述 | 是否必需 |
---|---|---|---|
Key | String | 属性名称 | 是 |
Value | String | 属性值 | 是 |
关于用户属性,客户端针对用户的昵称、头像 URL、联系方式、邮箱、性别、签名、生日和扩展字段默认使用以下键名。调用该 RESTful 接口设置用户属性时,若要确保在客户端能够获取设置,请求中必须传以下键名与客户端保持一致,键值可根据实际使用场景确定:
字段 | 描述 |
---|---|
nickname | 用户昵称。长度在 64 个字符内。 |
avatarurl | 用户头像 URL 地址。长度在 256 个字符内。 |
phone | 用户联系方式。长度在 32 个字符内。 |
mail | 用户邮箱。长度在 64 个字符内。 |
gender | 用户性别: - 1 :男;- 2 :女;- 0 :未知。 |
sign | 用户签名。长度在 256 个字符内。 |
birth | 用户生日。长度在 64 个字符内。 |
ext | 扩展字段。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200
,表示请求成功,响应包体中包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
data | JSON | 响应中的数据详情,包含你在本次请求中设置的用户属性键值对。 |
其他字段及说明详见 公共参数。
如果返回的 HTTP 状态码非 200
,表示请求失败。你可以参考 错误码 了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X PUT -H 'Content-Type: application/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
}
错误码
如果返回的 HTTP 状态码非 200
,表示请求失败,可能提示以下错误码:
HTTP 状态码 | 错误类型 | 错误提示 | 可能原因 | 处理建议 |
---|---|---|---|---|
403 | FORBIDDEN | {appkey} user metadata service not allow | 用户属性功能未开通。 | 联系商务开通用户属性功能。 |
403 | FORBIDDEN | size of metadata for this single user exceeds the user defined limit, {}Bytes | 单个用户的用户属性用量超过限制。默认单个用户的属性总长度不得超过 2 KB。 | 调整用量或联系商务提升用量上限。 |
403 | FORBIDDEN | size of metadata for this single user exceeds the current mysql column size, {}Bytes | 单个用户的用户属性超过字段长度限制。关于用户属性字段(例如,用户昵称)的长度限制,详见设置用户属性。 | 减少用户属性字段的长度。 |
403 | FORBIDDEN | total size of user metadata for this app exceeds the user defined limit, {}Bytes | 整个应用的用户属性用量超过限制。默认单个 app 下所有用户的属性总长度不得超过 10 GB。 | 调整用量或联系商务提升用量上限。 |
500 | INTERNAL_SERVER_ERROR | update metadata failed | 服务异常导致更新用户属性失败。 |
关于其他错误,你可以参考 响应状态码 了解可能的原因。
获取用户属性
获取单个用户的全部用户属性键值对。需要在请求中填写 {username},指定获取用户属性的用户 ID。
如果指定的用户或用户属性不存在,返回空数据 {}。
HTTP 请求
GET https://{host}/{org_name}/{app_name}/metadata/user/{username}
路径参数
参数及说明详见 公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 是 | 内容类型。请填 application/json 。 |
Authorization | String | 是 | App 管理员的鉴权 token,格式为 Bearer YourAppToken ,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200
,表示请求成功,响应包体中包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
data | Object | 用户属性键值对。 如果 data 为空,请确认用户 ID 是否存在或该用户是否有用户属性。 |
其他字段及说明详见 公共参数。
如果返回的 HTTP 状态码非 200
,表示请求失败。你可以参考 错误码 了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X GET -H 'Content-Type: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/metadata/user/user1'
响应示例
{
"timestamp": 1620445147011,
"data": {
"ext": "ext",
"nickname": "nickname",
"avatarurl": "https://www.easemob.com/avatar.png"
},
"duration": 166
}
错误码
如果返回的 HTTP 状态码非 200
,表示请求失败,可能提示以下错误码:
HTTP 状态码 | 错误类型 | 错误提示 | 可能原因 | 处理建议 |
---|---|---|---|---|
401 | metadata_error | auth error | 鉴权失败。例如,使用的 token 与路径参数 username 不匹配。 | 使用正确的 token。 |
403 | FORBIDDEN | {appkey} user metadata service not allow | 用户属性功能未开通。 | 联系商务开通用户属性功能。 |
500 | INTERNAL_SERVER_ERROR | 服务未知异常。 |
关于其他错误,你可以参考 响应状态码 了解可能的原因。
批量获取用户属性
根据指定的用户 ID 列表和属性列表,查询用户属性。
如果指定的用户 ID 或用户属性不存在,返回空数据 {}。 每次最多可获取 100 个用户的属性。
HTTP 请求
POST https://{host}/{org_name}/{app_name}/metadata/user/get
路径参数
参数及说明详见 公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 是 | 内容类型。请填 application/json 。 |
Authorization | String | 是 | App 管理员的鉴权 token,格式为 Bearer YourAppToken ,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。 |
请求 body
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
targets | Array | 是 | 用户 ID 列表,最多可传 100 个用户 ID。 |
properties | Array | 是 | 属性名列表,查询结果只返回该列表中包含的属性,不在该列表中的属性将被忽略。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200
,表示请求成功,响应包体中包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
data | Object | 用户属性键值对。 如果 data 为空,请确认用户 ID 是否存在或用户是否有用户属性。 |
其他字段及说明详见 公共参数。
如果返回的 HTTP 状态码非 200
,表示请求失败。你可以参考 错误码 了解可能的原因。
示例
请求示例
# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X POST -H 'Content-Type: application/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
}
错误码
如果返回的 HTTP 状态码非 200
,表示请求失败,可能提示以下错误码:
HTTP 状态码 | 错误类型 | 错误提示 | 可能原因 | 处理建议 |
---|---|---|---|---|
400 | BAD_REQUEST | exceed allowed batch size %s | 超过允许获取的用户数的用户属性。每次最多可获取 100 个用户的用户属性。 | 减少批量获取用户属性的用户数。 |
401 | metadata_error | auth error | 鉴权失败。 | |
403 | FORBIDDEN | {appkey} user metadata service not allow | 用户属性功能未开通。 | 联系商务开通用户属性功能。 |
关于其他错误,你可以参考 响应状态码 了解可能的原因。
获取 app 下用户属性总大小
获取该 app 下所有用户的属性数据大小,单位为字节。
HTTP 请求
GET https://{host}/{org_name}/{app_name}/metadata/user/capacity
路径参数
参数及说明详见 公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Authorization | String | 是 | App 管理员的鉴权 token,格式为 Bearer YourAppToken ,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200
,表示请求成功,响应包体中包含以下字段:
参数 | 类型 | 描述 |
---|---|---|
data | Long | 该 app 下所有用户属性的数据大小,单位为字节。 |
其他字段及说明详见 公共参数。
如果返回的 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 状态码非 200
,表示请求失败,可能提示以下错误码:
HTTP 状态码 | 错误类型 | 错误提示 | 可能原因 | 处理建议 |
---|---|---|---|---|
401 | unauthorized | unauthorized | 鉴权失败。 | 获取应用容量时需要使用 app 级别权限。 |
401 | metadata_error | auth error | 鉴权失败。 | 使用正确的 token。 |
403 | FORBIDDEN | {appkey} user metadata service not allow | 用户属性功能未开通。 | 联系商务开通用户属性功能。 |
关于其他错误,你可以参考 响应状态码 了解可能的原因。
删除用户属性
删除单个用户的所有属性。如果指定的用户或用户属性不存在(可能已删除),也视为删除成功。
HTTP 请求
DELETE https://{host}/{org_name}/{app_name}/metadata/user/{username}
路径参数
参数及说明详见 公共参数。
请求 header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Authorization | String | 是 | App 管理员的鉴权 token,格式为 Bearer YourAppToken ,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200
,表示请求成功,响应包体中包含以下字段:
参数 | 类型 | 描述 |
---|---|---|
data | Bool | 是否删除成功: - true :是。如果指定的用户不存在,或指定用户的用户属性不存在,也视为删除成功。- false :否。 |
其他字段及说明详见 公共参数。
如果返回的 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
}
错误码
如果返回的 HTTP 状态码非 200
,表示请求失败,可能提示以下错误码:
HTTP 状态码 | 错误类型 | 错误提示 | 可能原因 | 处理建议 |
---|---|---|---|---|
401 | metadata_error | auth error | 鉴权失败。 | 使用正确的 token。 |
403 | FORBIDDEN | {appkey} user metadata service not allow | 用户属性功能未开通。 | 联系商务开通用户属性功能。 |
关于其他错误,你可以参考 响应状态码 了解可能的原因。