管理用户属性

大约 12 分钟

管理用户属性

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

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

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

提示

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

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

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

前提条件

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

公共参数

请求参数

参数类型是否必需描述
hostString是即时通讯 IM 分配的用于访问 RESTful API 的域名。
app_idString是声网为每个项目自动分配的 App ID，作为项目唯一标识。
usernameString是用户 ID。

响应参数

参数类型描述
entitiesObject响应实体。
usernameString用户 ID。
data.nicknameString用户昵称。
data.extString自定义的用户属性扩展字段。
data.avatarurlString用户头像 URL。
timestampLongUnix 时间戳，单位为毫秒。
durationLong从发送 HTTP 请求到响应的时长, 单位为毫秒。

认证方式

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

Authorization: Bearer YourAppToken

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

设置用户属性

用户属性的内容为一个或多个纯文本键值对，默认单个用户的属性总长度不能超过 2 KB，默认单个 app 下所有用户的属性总长度不能超过 10 GB。利用该 API，每次只能设置一个用户的用户属性。

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

HTTP 请求

PUT https://{host}/app-id/{app_id}/metadata/user/{username}

路径参数

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

请求 header

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

请求 body

请求 body 为 x-www-form-urlencoded 类型，包含以下字段：

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

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

字段描述
nickname用户昵称。长度在 64 个字符内。
avatarurl用户头像 URL 地址。长度在 256 个字符内。
phone用户联系方式。长度在 32 个字符内。
mail用户邮箱。长度在 64 个字符内。
gender用户性别：
- 1：男；
- 2：女；
- 0：未知。
sign用户签名。长度在 256 个字符内。
birth用户生日。长度在 64 个字符内。
ext扩展字段。

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.shengwang.com/avatar.png&ext=ext&nickname=nickname' 'https://XXXX/app-id/XXXX/metadata/user/user1'

响应示例

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

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码错误类型错误提示可能原因处理建议
403FORBIDDEN{appkey} user metadata service not allow用户属性功能未开通。联系商务开通用户属性功能。
403FORBIDDENsize of metadata for this single user exceeds the user defined limit, {}Bytes单个用户的用户属性用量超过限制。默认单个用户的属性总长度不得超过 2 KB。调整用量或联系商务提升用量上限。
403FORBIDDENsize of metadata for this single user exceeds the current mysql column size, {}Bytes单个用户的用户属性超过字段长度限制。关于用户属性字段（例如，用户昵称）的长度限制，详见设置用户属性。减少用户属性字段的长度。
403FORBIDDENtotal size of user metadata for this app exceeds the user defined limit, {}Bytes整个应用的用户属性用量超过限制。默认单个 app 下所有用户的属性总长度不得超过 10 GB。调整用量或联系商务提升用量上限。
500INTERNAL_SERVER_ERRORupdate metadata failed服务异常导致更新用户属性失败。

关于其他错误，你可以参考 响应状态码 了解可能的原因。

获取用户属性

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

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

HTTP 请求

GET https://{host}/app-id/{app_id}/metadata/user/{username}

路径参数

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

请求 header

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

HTTP 响应

响应 body

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

字段类型描述
dataObject用户属性键值对。
如果 data 为空，请确认用户 ID 是否存在或该用户是否有用户属性。

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

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

示例

请求示例

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

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/app-id/XXXX/metadata/user/user1'

响应示例

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

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码错误类型错误提示可能原因处理建议
401metadata_errorauth error鉴权失败。例如，使用的 token 与路径参数 username 不匹配。使用正确的 token。
403FORBIDDEN{appkey} user metadata service not allow用户属性功能未开通。联系声网商务开通用户属性功能。
500INTERNAL_SERVER_ERROR服务未知异常。

关于其他错误，你可以参考 响应状态码 了解可能的原因。

批量获取用户属性

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

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

HTTP 请求

POST https://{host}/app-id/{app_id}/metadata/user/get

路径参数

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

请求 header

参数类型是否必需
描述
Content-TypeString是内容类型。请填 application/json。
AcceptString是内容类型。请填 application/json。
AuthorizationString是App 管理员的鉴权 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 'Accept: application/json'  \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
  "properties": [
    "avatarurl",
    "ext",
    "nickname"
  ],
  "targets": [
    "user1",
    "user2",
    "user3"
  ]
}' 'https://XXXX/app-id/XXXX/metadata/user/get'

响应示例

{
  "timestamp": 1620448826647,
  "data": {
    "user1": {
      "ext": "ext",
      "nickname": "nickname",
      "avatarurl": "https://www.XXXX.com/avatar.png"
    },
    "user2": {
      "ext": "ext",
      "nickname": "nickname",
      "avatarurl": "https://www.XXXX.com/avatar.png"
    },
    "user3": {
      "ext": "ext",
      "nickname": "nickname",
      "avatarurl": "https://www.XXXX.com/avatar.png"
    }
  },
  "duration": 3
}

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码错误类型错误提示可能原因处理建议
400BAD_REQUESTexceed allowed batch size %s超过允许获取的用户数的用户属性。每次最多可获取 100 个用户的用户属性。减少批量获取用户属性的用户数。
401metadata_errorauth error鉴权失败。
403FORBIDDEN{appkey} user metadata service not allow用户属性功能未开通。联系商务开通用户属性功能。

关于其他错误，你可以参考 响应状态码 了解可能的原因。

获取 app 下用户属性总大小

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

HTTP 请求

GET https://{host}/app-id/{app_id}/metadata/user/capacity

路径参数

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

请求 header

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

HTTP 响应

响应 body

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

参数类型描述
dataLong该 app 下所有用户属性的数据大小，单位为字节。

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

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

示例

请求示例

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

curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/app-id/XXXX/metadata/user/capacity'

响应示例

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

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedunauthorized鉴权失败。获取应用容量时需要使用 app 级别权限。
401metadata_errorauth error鉴权失败。使用正确的 token。
403FORBIDDEN{appkey} user metadata service not allow用户属性功能未开通。联系商务开通用户属性功能。

关于其他错误，你可以参考 响应状态码 了解可能的原因。

删除用户属性

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

HTTP 请求

DELETE https://{host}/app-id/{app_id}/metadata/user/{username}

路径参数

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

请求 header

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

HTTP 响应

响应 body

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

参数类型描述
dataBool是否删除成功：
- true：是。如果指定的用户不存在，或指定用户的用户属性不存在，也视为删除成功。
- false：否。

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

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

示例

请求示例

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

curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/app-id/XXXX/metadata/user/user1'

响应示例

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

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码错误类型错误提示可能原因处理建议
401metadata_errorauth error鉴权失败。使用正确的 token。
403FORBIDDEN{appkey} user metadata service not allow用户属性功能未开通。联系商务开通用户属性功能。

关于其他错误，你可以参考 响应状态码 了解可能的原因。

上次编辑于: