====== 在线状态订阅 RESTful API ====== 更新时间：2022-06-22 本文展示如何调用环信即时通讯 RESTful API 实现用户在线状态订阅，包括设置用户在线状态信息、批量订阅和获取在线状态、取消订阅以及查询订阅列表。调用以下方法前，请先参考 [[ccim:limitation|使用限制]] 了解即时通讯 RESTful API 的调用频率限制。 使用该特性前，你需要联系商务开通。 ===== 公共参数 ===== 以下表格列举了即时通讯 RESTful API 的公共请求参数和响应参数： ==== 请求参数 ==== ^参数 ^类型 ^描述 ^是否必填^ |''%%host%%'' |String |你在环信即时通讯云控制台注册项目时所在的集群服务器地址。 |是 | |''%%org_name%%'' |String |即时通讯服务分配给每个企业（组织）的唯一标识。你可以通过控制台获取该字段。 |是 | |''%%app_name%%'' |String |你在环信即时通讯云控制台注册项目时填入的应用名称。 |是 | |''%%uid%%'' |String |用户在即时通讯服务器上的唯一 ID。 |是 | ==== 响应参数 ==== ^参数 ^描述 ^ |''%%data%%'' |实际取到的数据详情。 | |''%%username%%'' |用户 ID。 | |''%%groupname%%'' |群组名。 | |''%%timestamp%%'' |请求响应的时间，Unix 时间戳，单位为 ms。 | ===== 认证方式 ===== 环信即时通讯 RESTful API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入如下 Authorization 字段： ''%%Authorization: Bearer ${YourAppToken}%%'' 为提高项目的安全性，环信使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。即时通讯 RESTful API 建议使用 App Token 的鉴权方式，详见 [[https://docs-im.easemob.com/ccim/authentication|使用 Token 鉴权]]。 ===== 设置用户在线状态信息 ===== 根据用户的唯一 ID 设置在线状态信息。 ==== HTTP 请求 ==== ''%%POST https://{host}/{org_name}/{app_name}/users/{uid}/presence/{resource}/{status}%%'' === 路径参数 === ^参数 ^类型 ^描述 ^是否必填 ^ |''%%resource%%'' |String |设备来源，格式为设备类型 + resource ID，例如，android_123423453246。 |是 | |''%%status%%'' |String |端状态码。该参数的取值如下：
- ''%%0%%''：离线；
- ''%%1%%''：在线；
- 其他值：自定义在线状态。 |是 | 其他参数及说明详见[[https://docs-im.easemob.com/ccim/rest/presence#公共参数|公共参数]]。 === 请求 header === ^参数 ^类型 ^描述 ^是否必填 ^ |''%%Content-Type%%'' |String |内容类型：''%%application/json%%''。 |是 | |''%%Authorization%%'' |String |''%%Bearer ${token}%%'' Bearer 是固定字符，后面加英文空格，再加上获取到的 app token 的值。 |是 | === 请求体 body === 请求包体为 JSON Object 类型，包含以下字段： ^参数 ^类型 ^描述 ^是否必填 ^ |''%%ext%%'' |String |在线状态扩展信息。建议不超过 64 字节。 |是 | ==== HTTP 响应 ==== === 响应 body === 如果返回的 HTTP 状态码为 ''%%200%%''，表示请求成功，响应包体中包含以下字段： ^字段 ^类型 ^说明 ^ |''%%result%%'' |String |操作结果。设置成功返回 ’ok’，否则返回相应的错误原因。 | 如果返回的 HTTP 状态码非 ''%%200%%''，表示请求失败。你可以参考 [[https://docs-im.easemob.com/ccim/rest/errorcode|错误码]] 了解可能的原因。 ==== 示例 ==== === 请求示例 === 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"}% ===== 批量订阅在线状态 ===== 你一次可订阅多个用户的在线状态。 ==== HTTP 请求 ==== ''%%POST https://{host}/{org_name}/{app_name}/users/{uid}/presence/{expiry}%%'' === 路径参数 === ^参数 ^类型 ^描述 ^是否必填 ^ |''%%expiry%%'' |String |订阅时长，单位为秒，最长为 30 天。 |是 | 其他参数及说明详见[[https://docs-im.easemob.com/ccim/rest/presence#公共参数|公共参数]]。 === 请求 header === ^参数 ^类型 ^描述 ^是否必填 ^ |''%%Content-Type%%'' |String |内容类型：''%%application/json%%''。 |是 | |''%%Authorization%%'' |String |''%%Bearer ${token}%%'' Bearer 是固定字符，后面加英文空格，再加上获取到的 App Token 的值。 |是 | === 请求 body === 请求包体为 JSON Object 类型，包含以下字段： ^字段 ^类型 ^描述 ^是否必填 ^ |''%%usernames%%'' |JSON ARRAY |订阅对象的用户名数组，例如 [“user1”, “user2”]。该数组最多可包含 100 个用户名。 |是 | ==== HTTP 响应 ==== === 响应 body === 如果返回的 HTTP 状态码为 ''%%200%%''，表示请求成功，响应包体中包含以下字段： ^字段 ^类型 ^描述 ^ |''%%result%%'' |JSON Array |订阅对象的在线状态信息，以数组形式返回。若订阅失败，返回相应的错误原因。 | |''%%uid%%'' |String |用户在即时通讯服务器的唯一 ID。 | |''%%last_time%%'' |Number |用户最近在线时间。服务端会在被订阅的用户登录和登出时记录该时间。 | |''%%expiry%%'' |Number |订阅的过期时间戳。 | |''%%ext%%'' |String |用户在线状态扩展信息，建议不超过 64 字节。 | |''%%status%%'' |JSON Array |用户多端的状态。该参数的取值如下：
- ''%%0%%''：离线；
- ''%%1%%''：在线；
- 其他值：用户可设置其他值自定义在线状态。 | 如果返回的 HTTP 状态码非 ''%%200%%''，表示请求失败。你可以参考 [[https://docs-im.easemob.com/ccim/rest/errorcode|错误码]] 了解可能的原因。 ==== 示例 ==== === 请求示例 === 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"}}]}% ===== 批量获取在线状态信息 ===== 你一次可获取多个用户的在线状态信息。 ==== HTTP 请求 ==== ''%%POST https://{host}/{org_name}/{app_name}/users/{uid}/presence%%'' === 路径参数 === 参数及说明详见[[https://docs-im.easemob.com/ccim/rest/presence#公共参数|公共参数]]。 === 请求 header === ^参数 ^类型 ^描述 ^是否必填 ^ |''%%Content-Type%%'' |String |内容类型：''%%application/json%%''。 |是 | |''%%Authorization%%'' |String |''%%Bearer ${token}%%'' Bearer 是固定字符，后面加英文空格，再加上获取到的 App Token 的值。 |是 | === 请求 body === 请求包体为 JSON Object 类型，仅支持以下字段： ^参数 ^类型 ^是否必需 ^说明 ^ |''%%usernames%%'' |Array |必需 |订阅对象的用户名数组，例如 [“user1”, “user2”]。该数组最多可包含 100 个用户名。 | ==== HTTP 响应 ==== === 响应 body === 如果返回的 HTTP 状态码为 ''%%200%%''，表示请求成功，响应包体中包含以下字段： ^参数 ^类型 ^说明 ^ |''%%result%%'' |JSON Array |订阅对象的在线状态信息，以数组形式返回。若订阅失败，返回相应的错误原因。 | |''%%uid%%'' |String |用户在即时通讯服务器的唯一 ID。 | |''%%last_time%%'' |Number |用户最近在线时间。 | |''%%ext%%'' |String |用户在线状态的扩展信息，建议不超过 64 字节。 | |''%%status%%'' |JSON Array |用户多端的状态。 | 如果返回的 HTTP 状态码非 ''%%200%%''，表示请求失败。你可以参考[[https://docs-im.easemob.com/ccim/rest/errorcode|错误码]]了解可能的原因。 ==== 示例 ==== === 请求示例 === 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"} }] } ===== 取消订阅 ===== 你可以取消订阅用户的在线状态。 ''%%DELETE https://{host}/{org_name}/{app_name}/users/{uid}/presence%%'' ==== 路径参数 ==== 参数及说明详见[[https://docs-im.easemob.com/ccim/rest/presence#公共参数|公共参数]]。 ==== 请求 header ==== ^参数 ^类型 ^描述 ^是否必填 ^ |''%%Content-Type%%'' |String |内容类型：''%%application/json%%''。 |是 | |''%%Authorization%%'' |String |''%%Bearer ${token}%%'' Bearer 是固定字符，后面加英文空格，再加上获取到的 App Token 的值。 |是 | ==== 请求 body ==== ^参数 ^类型 ^描述 ^是否必填 ^ |''%%users%%'' |Array |订阅对象的用户名数组，例如 [“user1”, “user2”]。该数组最多可包含 100 个用户名。 |是 | ==== HTTP 响应 ==== === 响应 body === 如果返回的 HTTP 状态码为 ''%%200%%''，表示请求成功，响应包体中包含以下字段： ^参数 ^类型 ^说明 ^ |''%%result%%'' |String |取消成功返回“ok”；取消失败返回相应的错误原因。 | 如果返回的 HTTP 状态码非 ''%%200%%''，表示请求失败。你可以参考[[https://docs-im.easemob.com/ccim/rest/errorcode|错误码]]了解可能的原因。 ==== 示例 ==== === 请求示例 === 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"}% ===== 查询订阅列表 ===== 查询当前用户已订阅在线状态的用户列表。 ==== HTTP 请求 ==== ''%%GET https://{host}/{org_name}/{app_name}/users/{uid}/presence/sublist?pageNum=1&pageSize=100%%'' === 路径参数 === ^参数 ^类型 ^描述 ^是否必填 ^ |''%%pageNum%%'' |int |要查询的页码。该参数的值须大于等于 1。 |是 | |''%%pageSize%%'' |int |每页显示的订阅用户数量。 该参数的值不得超 500。 |是 | 其他参数及说明详见[[https://docs-im.easemob.com/ccim/rest/presence#公共参数|公共参数]]。 === 请求 header === ^参数 ^类型 ^是否必需 ^描述 ^ |''%%Content-Type%%'' |String |必需 |内容类型：''%%application/json%%''。 | |''%%Authorization%%'' |String |必需 |''%%Bearer ${token}%%'' Bearer 是固定字符，后面加英文空格，再加上获取到的 App Token 的值。 | ==== HTTP 响应 ==== === 响应 body === 如果返回的 HTTP 状态码为 ''%%200%%''，表示请求成功，响应包体中包含以下字段： ^参数 ^类型 ^说明 ^ |''%%result%%'' |Object |订阅对象在线状态信息，以数组形式返回。若查询失败，返回相应的错误原因。 | |''%%totalnum%%'' |String |当前订阅的用户总数。 | |''%%sublist%%'' |Object |订阅对象的信息，以数组形式返回。 | |''%%uid%%'' |String |用户在即时通讯服务器的唯一 ID。 | |''%%expiry%%'' |String |订阅的过期时间戳。 | 如果返回的 HTTP 状态码非 ''%%200%%''，表示请求失败。你可以参考[[https://docs-im.easemob.com/ccim/rest/errorcode|错误码]]了解可能的原因。 ==== 示例 ==== === 请求示例 === 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"} ] } }