用户属性

更新时间：2022-05-19

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

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

注意

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

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

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

• 已在环信即时通讯控制台 开通配置环信即时通讯 IM 服务。
• 已从服务端获取 app token，详见 使用环信 app token 鉴权。

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

Authorization：Bearer ${YourAppToken}

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

调用前请了解环信即时通讯 IM 的限制条件，详见 限制条件。

用户属性的内容为一个或多个纯文本键值对，默认单一用户的属性总长不得超过 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。

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'

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

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

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

方法：GET

接入点：https://{host}/{org_name}/{app_name}/metadata/user/{username}

curl -X GET 'http://a1.easemob.com/easemob-demo/testapp/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

curl -X POST -H 'Content-Type:  application/json' -d '{
  "properties": [
    "avatarurl",
    "ext",
    "nickname"
  ],
  "targets": [
    "user1",
    "user2",
    "user3"
  ]
}' 'http://a1.easemob.com/easemob-demo/testapp/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 下所有用户的属性数据大小，单位为 byte。

方法：GET

接入点：https://{host}/{org_name}/{app_name}/metadata/user/capacity

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

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

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

方法：DELETE

接入点：https://{host}/{org_name}/{app_name}/metadata/user/{username}

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

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