管理用户属性

大约 9 分钟

管理用户属性

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

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

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

提示

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

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

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

前提条件

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

已在环信即时通讯云控制台开通配置环信即时通讯 IM 服务。

公共参数

请求参数

参数	类型	是否必需	描述
`host`	String	是	访问 RESTful API 的域名或服务器信息。 -公有云集成为环信即时通讯控制台的 `即时通讯->服务概览`页面下的 `域名配置- Rest Api`。 -私有化集成为部署后 `服务器地址:端口`。
`org_name`	String	是	每个公司（组织）分配的唯一标识。详见环信即时通讯控制台的 `应用概览->应用详情`页面下的 `应用信息-Orgname`。
`app_name`	String	是	创建应用时填入的应用名称。详见环信即时通讯控制台的 `应用概览->应用详情`页面下的 `应用信息-Appname`。
`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。

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

HTTP 请求

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

路径参数

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

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

请求 body

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

字段	类型	描述	是否必需
`Key`	String	属性名称	是
`Value`	String	属性值	是

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

字段	类型	描述
`nickname`	String	用户昵称。长度在 64 个字符内。
`avatarurl`	String	用户头像 URL 地址。长度在 256 个字符内。
`phone`	String	用户联系方式。长度在 32 个字符内。
`mail`	String	用户邮箱。长度在 64 个字符内。
`gender`	Int	用户性别： - `1`：男； - `2`：女； - （默认）`0`：未知； - 设置为其他值无效。
`sign`	String	用户签名。长度在 256 个字符内。
`birth`	String	用户生日。长度在 64 个字符内。
`ext`	String	扩展字段。

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
}

获取用户属性

获取指定用户的全部用户属性键值对。需要在请求中填写 {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
}

批量获取用户属性

根据指定的用户 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
}

获取 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 请求

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 请求

# 路径参数

# 请求 header

# 请求 body

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 获取用户属性

# HTTP 请求

# 路径参数

# 请求 header

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 批量获取用户属性

# HTTP 请求

# 路径参数

# 请求 header

# 请求 body

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

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

# HTTP 请求

# 路径参数

# 请求 header

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 删除用户属性

# HTTP 请求

# 路径参数

# 请求 header

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

管理用户属性

前提条件

公共参数

请求参数

响应参数

认证方式

设置用户属性

HTTP 请求

路径参数

请求 header

请求 body

HTTP 响应

响应 body

示例

请求示例

响应示例

获取用户属性

HTTP 请求

路径参数

请求 header

HTTP 响应

响应 body

示例

请求示例

响应示例

批量获取用户属性

HTTP 请求

路径参数

请求 header

请求 body

HTTP 响应

响应 body

示例

请求示例

响应示例

获取 app 下用户属性总大小

HTTP 请求

路径参数

请求 header

HTTP 响应

响应 body

示例

请求示例

响应示例

删除用户属性

HTTP 请求

路径参数

请求 header

HTTP 响应

响应 body

示例

请求示例

响应示例