用户在线状态管理 RESTful API
更新时间:2022 年 5 月 19 日
本文主要介绍用户在线状态相关 RESTful API 接口。
该功能需联系商务开通。
认证方式
环信即时通讯 RESTful API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时,都必须在请求头部填入如下 Authorization 字段:
Authorization:Bearer ${YourAppToken}
为提高项目的安全性,环信使用 Token(动态密钥)对即将登录即时通讯系统的用户进行鉴权。即时通讯 RESTful API 建议使用 App Token 的鉴权方式,详见使用 Token 鉴权。
用户在线状态管理具体接口
环信即时通讯 IM 提供多个接口实现用户在线状态的设置、订阅、获取、取消订阅以及查询订阅列表等管理功能。
名称 | 请求 | 描述 |
---|---|---|
设置用户在线状态信息 | /{org_name}/{app_name}/users/{uid}/presence/{resource}/{status} | 根据用户的唯一 ID 设置在线状态信息。 |
批量订阅在线状态 | /{org_name}/{app_name}/users/{uid}/presence/{expiry} | 订阅多个用户的在线状态信息。 |
批量获取在线状态信息 | /{org_name}/{app_name}/users/{uid}/presence | 获取多个用户的在线状态信息。 |
取消订阅 | /{org_name}/{app_name}/users/{uid}/presence | 取消订阅用户的在线状态。 |
查询订阅列表 | /{org_name}/{app_name}/users/{uid}/presence/sublist?pageNum=1&pageSize=100 | 查询当前用户已订阅在线状态的用户列表。 |
设置用户在线状态信息
方法:POST
接入点:/{org_name}/{app_name}/users/{uid}/presence/{resource}/{status}
路径参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在控制台注册项目时填入的应用名称。 |
uid | String | 必需 | 用户在即时通讯服务器端的唯一 ID。 |
resource | String | 必需 | 设备来源。 |
status | String | 必需 | 端状态码。该参数的取值如下: - 0 :离线; - 1 :在线;- 其他值:自定义在线状态。 |
请求头
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 必需 | 内容类型:application/json 。 |
Authorization | String | 必需 | Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 app token 的值。 |
请求体参数
参数 | 类型 | 是否必需 | 说明 |
---|---|---|---|
ext | String | 必需 | 在线状态扩展信息。建议不超过 64 字节。 |
响应参数
参数 | 类型 | 说明 |
---|---|---|
result | String | 操作结果。设置成功返回’ok’,否则返回相应的错误原因,详见响应码列表。 |
请求示例
curl -X POST 'a1-test.easemob.com:8089/5101220107132865/test/users/c1/presence/android/0' \
-H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
-H 'Content-Type: application/json' \
-d '{"ext":"123"}'
响应示例
{"result":"ok"}%
响应码
状态码 | 描述 |
---|---|
200 | 请求成功。 |
400 | 请求失败,错误原因如下: - set presence failed :在线状态设置失败;- ext is too big :在线状态扩展信息长度超过限制;- resource not exist :设备来源不存在。 |
401 | 鉴权失败(无 Token,Token 错误或者过期),请重新获取 Token 再试。 |
429,503 或者其他 5xx | 该接口可能限流了,请稍后重试。 |
500 | 服务器内部错误,请联系我们的技术支持团队。 |
批量订阅在线状态
一次可订阅多个用户的在线状态。
方法:POST
接入点:/{org_name}/{app_name}/users/{uid}/presence/{expiry}
路径参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在控制台注册项目时填入的应用名称。 |
uid | String | 必需 | 用户在即时通讯服务器上的唯一 ID。 |
expiry | String | 必需 | 订阅时间。 |
请求头参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 必需 | 内容类型:application/json 。 |
Authorization | String | 必需 | Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 App Token 的值。 |
请求体参数
参数 | 类型 | 是否必需 | 说明 |
---|---|---|---|
usernames | JSON ARRAY | 必需 | 订阅对象的用户名数组,例如 [“user1”, “user2”]。该数组最多可包含 100 个用户名。 |
响应参数
参数 | 类型 | 说明 |
---|---|---|
result | JSON Array | 订阅对象的在线状态信息,以数组形式返回。若订阅失败,返回相应的错误原因,详见响应码列表。 |
uid | String | 用户在即时通讯服务器的唯一 ID。 |
last_time | Number | 用户最近在线时间。 |
expiry | Number | 订阅的过期时间戳。 |
ext | String | 用户在线状态扩展信息,建议不超过 64 字节。 |
status | JSON Array | 用户多端的状态。该参数的取值如下: - 0 :离线;- 1 :在线;- 其他值:用户可设置其他值自定义在线状态。 |
请求示例
curl -X POST 'a1-test.easemob.com:8089/5101220107132865/test/users/wzy/presence/1000' \
-H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
-H 'Content-Type: application/json' \
-d '{"usernames":["c2","c3"]}'
响应示例
{"result":[{"uid":"","last_time":"1644466063","expiry":"1645500371","ext":"123","status":{"android":"1","android_6b5610ac-4e11-4661-82b3-dee17bc7b2cc":"0"}},{"uid":"c3","last_time":"1645183991","expiry":"1645500371","ext":"","status":{"android":"0","android_6b5610ac-4e11-4661-82b3-dee17bc7b2cc":"0"}}]}%
响应码
状态码 | 描述 |
---|---|
200 | 请求成功。 |
400 | 请求失败,错误原因如下:you can't sub yourself :无法订阅自己的在线状态;“too many sub prensence`:订阅用户数量超过上限。 |
401 | 鉴权失败(无 Token,Token 错误或者过期),请重新获取 Token 再试。 |
429,503 或者其他 5xx | 该接口可能限流了,请稍后重试。 |
500 | 服务器内部错误,请联系我们的技术支持团队。 |
批量获取在线状态信息
方法:POST
接入点:/{org_name}/{app_name}/users/{uid}/presence
路径参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在控制台注册项目时填入的应用名称。 |
uid | String | 必需 | 用户在即时通讯服务器的唯一 ID。 |
请求头
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 必需 | 内容类型:application/json 。 |
Authorization | String | 必需 | Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 App Token 的值。 |
请求体参数
参数 | 类型 | 是否必需 | 说明 |
---|---|---|---|
usernames | Array | 必需 | 订阅对象的用户名数组,例如 [“user1”, “user2”]。该数组最多可包含 100 个用户名。 |
响应参数
参数 | 类型 | 说明 |
---|---|---|
result | JSON Array | 订阅对象的在线状态信息,以数组形式返回。若订阅失败,返回相应的错误原因,详见响应码列表。 |
uid | String | 用户在即时通讯服务器的唯一 ID。 |
last_time | Number | 用户最近在线时间。 |
ext | String | 用户在线状态的扩展信息,建议不超过 64 字节。 |
status | JSON Array | 用户多端的状态。 |
请求示例
curl -X POST 'a1-test.easemob.com:8089/5101220107132865/test/users/wzy/presence' \
-H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
-H 'Content-Type: application/json' \
-d '{"usernames":["c2","c3"]}'
响应示例
{
"result":[
{"uid":"c2",
"last_time":"1644466063",
"ext":"",
"status":{"android":"0"}
},
{"uid":"c3",
"last_time":"1644475330",
"ext":"",
"status":{
"android":"0",
"android":"0"}
}]
}
响应码
状态码 | 描述 |
---|---|
200 | 请求成功。 |
400 | 请求失败,错误原因:“too many get presences”(获取在线状态的用户数量超过上限)。 |
401 | 鉴权失败(无 Token,Token 错误或者过期),请重新获取 Token 再试。 |
429,503 或者其他 5xx | 该接口可能限流了,请稍后重试。 |
500 | 服务器内部错误,请联系我们的技术支持团队。 |
取消订阅
方法:DELETE
接入点:/{org_name}/{app_name}/users/{uid}/presence
路径参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在控制台注册项目时填入的应用名称。 |
uid | String | 必需 | 用户在即时通讯服务器唯一 ID。 |
请求头参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 必需 | 内容类型:application/json 。 |
Authorization | String | 必需 | Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 App Token 的值。 |
请求体参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
users | Array | 必需 | 订阅对象的用户名数组,例如 [“user1”, “user2”]。该数组最多可包含 100 个用户名。 |
响应参数
参数 | 类型 | 说明 |
---|---|---|
result | String | 取消成功返回“ok”;取消失败返回相应的错误原因,详见响应码列表。 |
请求示例
curl -X DELETE 'a1-test.easemob.com:8089/5101220107132865/test/users/wzy/presence' \
-H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
-H 'Content-Type: application/json' \
-d '["c1"]'
响应示例
{"result":"ok"}%
响应码
状态码 | 描述 |
---|---|
200 | 请求成功。 |
400 | 请求失败,错误原因:“too many unsub presences”(取消订阅的用户数量超过上限)。 |
401 | 鉴权失败(无 Token,Token 错误或者过期),请重新获取 Token 再试。 |
429,503 或者其他 5xx | 该接口可能限流了,请稍后重试。 |
500 | 服务器内部错误,请联系我们的技术支持团队。 |
查询订阅列表
方法:GET
接入点:/{org_name}/{app_name}/users/{uid}/presence/sublist?pageNum=1&pageSize=100
路径参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
org_name | String | 必需 | 即时通讯服务分配给每个企业(组织)的唯一标识。你可以通过控制台获取该字段。 |
app_name | String | 必需 | 你在控制台注册项目时填入的应用名称。 |
uid | String | 必需 | 用户在即时通讯服务器的唯一 ID。 |
pageNum | int | 必需 | 要查询的页码。该参数的值须大于等于 1。 |
pageSize | int | 必需 | 每页显示的订阅用户数量。 该参数的值不得超 500。 |
请求头参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 必需 | 内容类型:application/json 。 |
Authorization | String | 必需 | Bearer ${token} Bearer 是固定字符,后面加英文空格,再加上获取到的 App Token 的值。 |
响应参数
参数 | 类型 | 说明 |
---|---|---|
result | Object | 订阅对象在线状态信息,以数组形式返回。若查询失败,返回相应的错误原因,详见响应码列表。 |
totalnum | String | 当前订阅的用户总数。 |
sublist | Object | 订阅对象的信息,以数组形式返回。 |
uid | String | 用户在即时通讯服务器的唯一 ID。 |
expiry | String | 订阅的过期时间戳。 |
请求示例
curl -X GET 'a1-test.easemob.com:8089/5101220107132865/test/users/wzy/presence/sublist?pageNum=1&pageSize=100' \
-H 'Authorization: Bearer YWMtnjEbUopPEeybKGMmN0wpeZsaLSh8UEgpirS4wNAM_qx8oS2wik8R7LE4Rclv5hu9AwMAAAF-4tr__wBPGgDWGAeO86wl2lHGeTnU030fpWuEDR015Vk6ULWGYGKccA' \
-H 'Content-Type: application/json'
响应示例
{"result":{"totalnum":"2","sublist":[{"uid":"lxml2","expiry":"1645822322"},{"uid":"lxml1","expiry":"1645822322"}]}}%
响应码
状态码 | 描述 |
---|---|
200 | 请求成功。 |
400 | 请求失败,错误原因:“too many queries”(查询次数超过限制)。 |
401 | 鉴权失败(无 Token,Token 错误或者过期),请重新获取 Token 再试。 |
429,503 或者其他 5xx | 该接口可能限流了,请稍后重试。 |
500 | 服务器内部错误,请联系我们的技术支持团队。 |