用户属性管理

更新时间：2022-06-30

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

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

环信即时通讯提供给开发者从服务端 REST API 接口管理相关用户属性信息的方式。

注意

为保证用户信息安全，环信即时通讯 IM 仅支持用户本人或 app 管理员设置用户属性。

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

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

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

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

Authorization：Bearer ${YourToken}

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

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

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

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

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

请求体的长度限制:

用户属性键值对的 JSON String 长度不能 超过 4 KB。

比如:

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

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

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

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

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

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

# 将 <YourToken> 替换为你在服务端生成的 Token

curl -X PUT -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: Bearer <YourToken>' -d 'avatarurl=http://www.easemob.com/avatar.png&ext=ext&nickname=nickname' 'http://XXXX/XXXX/XXXX/metadata/user/user1'

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

获取指定用户的所有用户属性键值对。需要在请求时对应填写 {username}，需要获取用户属性的用户 ID。

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

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

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

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

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

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

# 将 <YourToken> 替换为你在服务端生成的 Token

curl -X GET -H 'Content-Type: application/json' -H 'Authorization: Bearer <YourToken>' 'http://XXXX/XXXX/XXXX/metadata/user/user1'

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

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

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

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

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

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

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

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

# 将 <YourToken> 替换为你在服务端生成的 Token

curl -X POST -H 'Content-Type:  application/json' -H 'Authorization: Bearer <YourToken>' -d '{
  "properties": [
    "avatarurl",
    "ext",
    "nickname"
  ],
  "targets": [
    "user1",
    "user2",
    "user3"
  ]
}' 'http://XXXX/XXXX/XXXX/metadata/user/get'

{
    "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
}

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

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

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

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

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

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

# 将 <YourToken> 替换为你在服务端生成的 Token

curl -X GET -H 'Authorization: Bearer <YourToken>' 'http://XXXX/XXXX/XXXX/metadata/user/capacity'

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

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

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

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

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

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

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

# 将 <YourToken> 替换为你在服务端生成的 Token

curl -X DELETE -H 'Authorization: Bearer <YourToken>' 'http://XXXX/XXXX/XXXX/metadata/user/user1'

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