事件与历史消息查询 RESTful API

最近更新时间：2022-09-20 05:17:40

认证
Basic HTTP 认证
Token 认证
API 调用步骤
查询用户事件和频道事件
查询历史消息
数据格式
用户与频道事件 API
获取用户上线或下线事件 API（GET）
获取用户加入或离开频道事件 API（GET）
响应状态码
历史消息 API
创建历史消息查询资源 API（POST）
获取历史消息 API（GET）
获取历史消息数目 API（GET）
响应状态码

事件与历史消息查询 RESTful API

事件与历史消息查询 RESTful API 目前支持以下功能：

  • 查询用户事件和频道事件。
  • 查询历史消息。

认证

Basic HTTP 认证

实时消息 RESTful API 仅支持 HTTPS 协议。发送请求时，你需要提供 api_key:api_secret 通过 basic HTTP 认证并填入 HTTP 请求头部的 Authorization 字段。具体生成 Authorization 字段的方法请参考 RESTful API 认证。

Token 认证

如果你已经在服务端生成了 RTM Token，你也可以选用 token 认证。你需要在发送 HTTP 请求时在 HTTP 请求头部的 x-ar-token 字段和 x-ar-uid 字段分别填入：

  • 服务端生成的 RTM Token。
  • 生成 RTM Token 时使用的 uid。

示例代码

下面的 Java 示例代码展示了如何实现 token 认证。

Request request = new Request.Builder()
...
// 在 HTTP 请求头部的 x-ar-token 字段填入获取的 RTM Token
.addHeader("x-ar-token", "<Your RTM Token>")
// 在 HTTP 请求头部的 x-ar-uid 字段填入用于生成该 RTM Token 的 uid
.addHeader("x-ar-uid", "<Your uid used to generate the RTM Token>")
...
关于如何生成 RTM Token，详见校验用户权限。

API 调用步骤

查询用户事件和频道事件

查询历史消息

数据格式

所有的请求都发送给域名：api.agrtc.cn。

  • 请求：请求的格式详见下面各个 API 中的示例
  • 响应：响应内容的格式为 JSON
  • 基本 URL：https://api.agrtc.cn/dev/v2/project/<appid>
<appid> 是你的 RTM 项目使用的 App ID。所有的请求 URL 和请求包体内容都是区分大小写的。

用户与频道事件 API

获取用户上线或下线事件 API（GET）

该方法从 anyRTC RTM 服务器指定的地址获取用户上线或下线事件。已经获取的事件会从 anyRTC RTM 服务器中移除，你无法再次获取。

  • 每个 App ID 每秒钟的请求数不能超过 10 次。
  • 对于每个 App ID，RTM 后台最多存储 2000 条事件。如果事件超过 2000 条，最老的事件会被最新的事件替换。
  • 单次返回最多 1000 条事件。
  • anyRTC 对事件按地理区域缓存，因此不保证来自不同地理区域的事件顺序的正确性。
  • anyRTC 只在同一地理区域内同步事件，不在地理区域间同步。所以，你从某地理区域发起请求拉取了事件后，如果你从另一个区域再次发起请求可能会得到相同的事件。
  • 方法：GET
  • 接入点：/rtm/vendor/user_events

请求示例

请求 URL：

https://api.agrtc.cn/dev/v2/project/<appid>/rtm/vendor/user_events

请求参数

此 API 无请求参数。

响应示例

{
    "result": "success",
    "request_id" : "123434011673489545879347",
    "events" : [{
    "ms" : 1476095418189,
    "type" : "Login",
    "user_id": "web923909240"
}]
}

响应参数

参数类型描述
resultstring本次请求结果。
request_idstring本次请求唯一的 ID。
eventsJSON用户上线下线事件。

events 的成员包含以下内容：

参数类型描述
msint从1970 年 1 月 1 日（UTC）到服务器接受请求的时间（UTC）的毫秒数。
typestring事件类型：
  • Login: 用户登录（上线）事件。
  • Logout: 用户登出（下线）事件。
    • user_idstring本次事件对应的用户名。

    获取用户加入或离开频道事件 API（GET）

    该方法从 anyRTC RTM 服务器指定的地址获取用户加入或离开频道事件。已经获取的事件会从 anyRTC RTM 服务器中移除，你无法再次获取。

    • 每个 App ID 每秒钟的请求数不能超过 10 次。
    • 对于每个 App ID，RTM 系统最多存储 2000 条事件。如果事件超过 2000 条，最老的事件会被最新的事件替换。
    • 单次返回最多 1000 条事件。
    • anyRTC 对事件按地理区域缓存，因此不保证来自不同地理区域的事件顺序的正确性。
    • anyRTC 只在同一地理区域内同步事件，不在地理区域间同步。所以，你从某地理区域发起请求拉取了事件后，如果你从另一个区域再次发起请求可能会得到相同的事件。
    • 方法：GET
    • 接入点：/rtm/vendor/channel_events

    请求示例

    请求 URL：

    https://api.agrtc.cn/dev/v2/project/<appid>/rtm/vendor/channel_events

    请求参数

    此 API 无请求参数。

    响应示例

    {
    "result": "success",
    "request_id" : "123434011673489545879347",
    "events" : [{
    "group_id": "example_channel_id",
    "ms" : 1476095418189,
    "type" : "Join",
    "user_id": "userA"
}]
}
    参数类型描述
    resultstring本次请求结果。
    request_idstring本次请求唯一的 ID。
    eventsJSON Array加入退出频道事件。

    响应参数

    events 的成员包含以下内容：

    参数类型描述
    group_idstring本次事件对应的频道名。
    msint从1970 年 1 月 1 日（UTC）到服务器接受请求的时间（UTC）的毫秒数。
    typestring事件类型：
  • Join: 用户加入频道事件。
  • Leave: 用户离开频道事件。
    • user_idstring本次事件对应的用户名。

    响应状态码

    错误码描述
    200请求成功。
    400请求的语法错误。
    408服务器请求超时或服务器无响应。

    历史消息 API

    创建历史消息查询资源 API（POST）

    该方法向 anyRTC RTM 服务器申请历史消息查询资源。若请求成功，你可以通过获取历史消息 API从服务器返回的 location 获取查询到的历史消息。

    如果需要将某条点对点或频道消息存为历史消息，你必须在调用 sendMessage 或 sendMessageToPeer 时将 sendMessageOptions 类中的 enableHistoricalMessaging 成员变量设为 true。否则你无法通过 RESTful API 查询到这条历史消息。
    • 历史消息默认保留七天。
    • 当前版本仅支持文本消息，不支持自定义二进制消息。
    • 对于每个 App ID，每秒请求数不能超过 100 次。
    • 方法：POST
    • 接入点：/rtm/message/history/query

    请求示例

    请求 URL：

    https://api.agrtc.cn/dev/v2/project/<appid>/rtm/message/history/query

    请求参数

    请求包体的参数如下：

    参数类型描述
    filterJSON筛选条件。
    offsetint（可选）需要返回的历史消息起始序号偏移量。默认值为 0，即不发生偏移，获取历史消息 API 从第一条消息开始返回。如果设为 1，则偏移值为 1，获取历史消息 API 从第二条消息开始返回。返回的消息数为 limit 的值。
    limitint（可选）单次返回的历史消息条数。可选值：
    • （默认）20
    • 50
    • 100
    如果历史消息数量大于单次返回的历史消息条数，你可以通过 offset 设置偏移量，获取其余的历史消息。
    orderstring（可选）排序方法
    • asc（默认）：按时间顺序。
    • desc：按时间倒序。

    filter 中需要填写的内容如下：

    参数类型描述
    sourcestring（可选）消息发送方，必须是用户。 如果此参数不赋值，则 API 会筛选出消息接收方在指定时间段内收到的所有消息。
    destinationstring（可选）消息接收方，可以是用户或频道。如果此参数不赋值，则 API 会筛选出消息发送方在指定时间段内发送的所有消息。
    start_timestring历史消息查询起始时间。时间为从1970 年 1 月 1 日（UTC）到服务器接受请求的时间（UTC）的秒数。
    end_timestring历史消息查询结束时间。时间为从1970 年 1 月 1 日（UTC）到服务器接受请求的时间（UTC）的秒数。

    频道只能作为 destination。API 的筛选规则与 source 和 destination 的关系详见下表：

    sourcedestination筛选规则
    不赋值userAAPI 会筛选出 userA 在指定时间段内收到的所有消息，包括点对点消息和频道消息。
    不赋值channelAAPI 会筛选出 channelA 在指定时间段内收到的所有频道消息。
    userA不赋值API 会筛选出 userA 在指定时间段内发送的所有消息，包括点对点消息和频道消息。
    userAuserBAPI 会筛选出 userA 在指定时间段内发送给 userB 的所有点对点消息。
    userAchannelAAPI 会筛选出 userA 在指定时间段内发送到 channelA 的所有频道消息。

    start_time 和 end_time 仅支持 UTC 时间戳。

    请求示例

    下面的示例从第 101 条消息开始返回，单次返回 20 条消息，消息排序为按时间顺序。

    userA 在指定时间段内收到的所有消息
    {
    "filter": {
        "destination": "userA",
        "start_time" : 1433088000,
        "end_time" : 1433433600
    },
    "offset" : 100,
    "limit" : 20,
    "order" : "asc"
}
    channelA 在指定时间段内收到的所有消息
    {
    "filter": {
        "destination": "channelA",
        "start_time" : 1433088000,
        "end_time" : 1433433600
    },
    "offset" : 100,
    "limit" : 20,
    "order" : "asc"
}
    userA 在指定时间段内发送的所有消息
    {
    "filter": {
        "source": "userA",
        "start_time" : 1433088000,
        "end_time" : 1433433600
    },
    "offset" : 100,
    "limit" : 20,
    "order" : "asc"
}
    userA 在指定时间段内发送给 userB 的所有点对点消息
    {
    "filter": {
        "source": "userA",
        "destination": "userB",
        "start_time" : 1433088000,
        "end_time" : 1433433600
    },
    "offset" : 100,
    "limit" : 20,
    "order" : "asc"
}
    userA 在指定时间段内发送到 channelA 的所有频道消息
    {
    "filter": {
        "source": "userA",
        "destination": "channelA",
        "start_time" : 1433088000,
        "end_time" : 1433433600
    },
    "offset" : 100,
    "limit" : 20,
    "order" : "asc"
}

    响应示例

    {
    "result": "success",
    "offset" : 100,
    "limit" : 20,
    "order" : "asc",
    "location" : "~/rtm/message/history/query/123456123456"
}

    响应参数

    响应包体的参数如下：

    参数类型描述
    resultstring请求结果。
    offsetint当前时间段内的消息偏移量。
    limitint单次返回的历史消息条数。
    locationstring历史消息资源地址。你可以从这个 URL 调用获取历史消息 API 获取查询结果。

    获取历史消息 API（GET）

    该方法从创建历史消息查询资源 API 返回的查询资源 URL 获取历史消息。如果你已经通过某个查询资源 URL 获取了历史消息，则此查询资源 URL 会失效。你无法通过某个查询资源 URL 重复获取历史消息。

    如果需要将某条点对点或频道消息存为历史消息，你必须在调用 sendMessage 或 sendMessageToPeer 时将 sendMessageOptions 类中的 enableHistoricalMessaging 成员变量设为 true。否则你无法通过 RESTful API 查询到这条历史消息。
    • 历史消息默认保留七天。
    • 当前版本仅支持文本消息，不支持自定义二进制消息。
    • 对于每个 App ID，每秒请求数不能超过 100 次。
    • 方法：GET
    • 接入点：/rtm/message/history/query/$handle
    • 请求 URL：
    https://api.agrtc.cn/dev/v2/project/<appid>/rtm/message/history/query/$handle

    请求参数

    此 API 需要下列 URL 参数：

    参数类型描述
    $handlestring创建历史消息查询资源 API 返回的 location 字段中 ~/rtm/message/history/query/ 后面的部分。例如，如果 location 返回 "~/rtm/message/history/query/123456123456"，则 $handle 为 123456123456。

    请求示例

    $handle 为 aadksldfdsklfjdsl：

    https://api.agrtc.cn/dev/v2/project/<appid>/rtm/message/history/query/123456123456

    响应示例

    {
    "code": "ok",
    "messages": [
            {"dst": "dst",
            "message_type": "peer_message",
            "ms": 1587009745719,
            "payload": "123",
            "src": "src"}
        ],
    "request_id": "125877_12008901591665642856",
    "result": "success"
}

    响应参数

    响应包体的参数如下：

    参数类型描述
    resultstring本次请求结果。
    codestring资源准备情况：
    • ok：资源准备完成。
    • in progress：资源还未准备完成，请稍后重试。当服务器返回 in progress 时，请等待 2 秒再发起请求。
    • resource not exist：资源不存在。
    messageJSON历史消息列表。

    messages 的成员包含以下参数：

    参数类型描述
    srcstring消息发送方。
    dststring消息接收方。
    message_typestring消息类型。可以是 peer_message 或 channel_message。
    payloadstring消息体。当前版本仅支持文本消息。
    msint从1970 年 1 月 1 日（UTC）到服务器接受请求的时间（UTC）的毫秒数。

    获取历史消息数目 API（GET）

    该方法从 anyRTC RTM 服务器指定的地址获取历史消息数目。

    如果需要将某条点对点或频道消息存为历史消息，你必须在调用 sendMessage 或 sendMessageToPeer 时将 sendMessageOptions 类中的 enableHistoricalMessaging 成员变量设为 true。否则你无法通过 RESTful API 查询到这条历史消息。
    • 历史消息默认保留14天。
    • 当前版本仅支持文本消息，不支持自定义二进制消息。
    • 对于每个 App ID，每秒请求数不能超过 100 次。
    • 方法：GET
    • 接入点：/rtm/message/history/count

    请求示例

    请求 URL：

    https://api.agrtc.cn/dev/v2/project/<appid>/rtm/message/history/count

    请求参数

    请求的查询参数如下：

    参数类型描述
    sourcestring（可选）消息发送方，必须是用户。 如果此参数不赋值，则 API 会筛选出消息接收方在指定时间段内收到的所有消息。
    destinationstring（可选）消息接收方，可以是用户或频道。如果此参数不赋值，则 API 会筛选出消息发送方在指定时间段内发送的所有消息。
    start_timestring历史消息查询起始时间。时间为从1970 年 1 月 1 日（UTC）到服务器接受请求的时间（UTC）的秒数。
    end_timestring历史消息查询结束时间。时间为从1970 年 1 月 1 日（UTC）到服务器接受请求的时间（UTC）的秒数。

    频道只能作为 destination。API 的筛选规则与 source 和 destination 的关系详见下表：

    sourcedestination筛选规则
    不赋值userAAPI 会筛选出 userA 在指定时间段内收到的所有消息，包括点对点消息和频道消息。
    不赋值channelAAPI 会筛选出 channelA 在指定时间段内收到的所有频道消息。
    userA不赋值API 会筛选出 userA 在指定时间段内发送的所有消息，包括点对点消息和频道消息。
    userAuserBAPI 会筛选出 userA 在指定时间段内发送给 userB 的所有点对点消息。
    userAchannelAAPI 会筛选出 userA 在指定时间段内发送到 channelA 的所有频道消息。

    start_time 和 end_time 仅支持 UTC 时间戳。

    请求示例

    userA 在指定时间段内收到的所有消息
    https://api.agrtc.cn/dev/v2/project/<appid>/rtm/message/history/count?&destination="userA"&start_time=1433088000&end_time=1433433600
    channelA 在指定时间段内收到的所有消息
    https://api.agrtc.cn/dev/v2/project/<appid>/rtm/message/history/count?&destination="channelA"&start_time=1433088000&end_time=1433433600
    userA 在指定时间段内发送的所有消息
    https://api.agrtc.cn/dev/v2/project/<appid>/rtm/message/history/count?source="userA"&start_time=1433088000&end_time=1433433600
    userA 在指定时间段内发送给 userB 的所有点对点消息
    https://api.agrtc.cn/dev/v2/project/<appid>/rtm/message/history/count?source="userA"&destination="userB"&start_time=1433088000&end_time=1433433600
    userA 在指定时间段内发送到 channelA 的所有频道消息
    https://api.agrtc.cn/dev/v2/project/<appid>/rtm/message/history/count?source="userA"&destination="channelA"&start_time=1433088000&end_time=1433433600

    响应示例

    {
    "result": "success",
    "code" : "ok",
    "count" : 123
}

    响应参数

    参数类型描述
    resultstring本次请求结果。
    codestring资源准备情况：
    • ok：资源准备完成。
    • in progress：资源还未准备完成，请稍后重试。当服务器返回 in progress 时，请等待 2 秒再发起请求。
    • resource not exist：资源不存在。
    countint历史消息数目。

    响应状态码

    错误码描述
    200请求成功。
    400请求的语法错误。
    408服务器请求超时或服务器无响应。