管理用户属性

大约 9 分钟

管理用户属性

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

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

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

提示

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

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

功能描述
设置用户属性设置指定的用户属性。
获取指定用户的所有用户属性获取指定用户的所有用户属性。
批量获取用户属性根据指定的用户名列表和属性列表查询用户属性。
删除用户属性删除指定用户的所有属性。
获取 app 下用户属性总大小获取该 app 下所有用户的属性总大小。

前提条件

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

公共参数

请求参数

参数类型是否必需描述
hostString访问 RESTful API 的域名或服务器信息。
-公有云集成为 环信即时通讯控制台的 即时通讯->服务概览页面下的 域名配置- Rest Api
-私有化集成为部署后 服务器地址:端口
org_nameString每个公司(组织)分配的唯一标识。详见 环信即时通讯控制台的 应用概览->应用详情页面下的 应用信息-Orgname
app_nameString创建应用时填入的应用名称。详见 环信即时通讯控制台的 应用概览->应用详情页面下的 应用信息-Appname
usernameString用户 ID。

响应参数

参数类型描述
organizationString环信即时通讯 IM 为每个公司(组织)分配的唯一标识,与请求参数 org_name 相同。
applicationString应用在系统内的唯一标识。该标识由系统生成,开发者无需关心。
applicationNameString你在环信即时通讯云控制台创建应用时填入的应用名称,与请求参数 app_name 相同。
entitiesObject响应实体。
usernameString用户 ID。
data.nicknameString用户昵称。
data.extString自定义的用户属性扩展字段。
data.avatarurlString用户头像 URL。
timestampLongUnix 时间戳,单位为毫秒。
durationLong从发送 HTTP 请求到响应的时长, 单位为毫秒。

认证方式

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

Authorization: Bearer YourAppToken

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

设置用户属性

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

请求示例中使用的键为 avatarurlextnickname,你可以根据实际使用场景确定键值。

HTTP 请求

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

路径参数

参数及说明详见 公共参数

请求 header

参数类型是否必需描述
Content-TypeString内容类型。请填 application/x-www-form-urlencoded
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

请求 body 为 x-www-form-urlencoded 类型,长度不得超过 4 KB,包含以下字段:

字段类型描述是否必需
KeyString属性名称
ValueString属性值

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

字段类型描述
nicknameString用户昵称。长度在 64 个字符内。
avatarurlString用户头像 URL 地址。长度在 256 个字符内。
phoneString用户联系方式。长度在 32 个字符内。
mailString用户邮箱。长度在 64 个字符内。
genderInt用户性别:
- 1:男;
- 2:女;
- (默认)0:未知;
- 设置为其他值无效。
signString用户签名。长度在 256 个字符内。
birthString用户生日。长度在 64 个字符内。
extString扩展字段。

HTTP 响应

响应 body

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

字段类型描述
dataJSON响应中的数据详情,包含你在本次请求中设置的用户属性键值对。

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

如果返回的 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
}

获取用户属性

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

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

HTTP 请求

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

路径参数

参数及说明详见 公共参数

请求 header

参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

字段类型描述
dataObject用户属性键值对。
如果 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
}

批量获取用户属性

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

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

HTTP 请求

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

路径参数

参数及说明详见 公共参数

请求 header

参数类型是否必需
描述
Content-TypeString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

参数类型是否必需描述
targetsArray用户 ID 列表,最多可传 100 个用户 ID。
propertiesArray属性名列表,查询结果只返回该列表中包含的属性,不在该列表中的属性将被忽略。

HTTP 响应

响应 body

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

字段类型描述
dataObject用户属性键值对。
如果 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
}

获取 app 下用户属性总大小

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

HTTP 请求

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

路径参数

参数及说明详见 公共参数

请求 header

参数类型是否必需描述
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

参数类型描述
dataLong该 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 请求

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

路径参数

参数及说明详见 公共参数

请求 header

参数类型是否必需描述
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

HTTP 响应

响应 body

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

参数类型描述
dataBool是否删除成功:
- 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
}
上次编辑于: