跳到主要内容

北极星（专业版）数据查询接口介绍

欢迎使用北极星（专业版）数据查询接口。本文档将引导您了解北极星专业版数据查询接口的工作原理，并完成您的第一次 API 调用，帮助您快速将数据查询能力集成到您的应用中。

通过北极星数据查询接口，您可以在您的应用服务器查询以下数据：

  • 消息数据：查询上行或下行消息量、消息分发量等统计数据
  • 服务端 API 调用数据：查询服务端 API 调用总量和报错数量
  • 用户数据：查询用户在线数量及收发消息的用户量
  • 业务数据：查询应用级别的用户信息和消息用量统计
前置条件

使用本套接口前，您需要先开通北极星专业版。

北极星专业版除支持通过接口查询数据外，还支持在开发者后台使用以下功能：

  • 业务数据实时统计看板：实时查看业务数据统计
  • 服务端 API 调用情况实时统计看板：实时查看服务端 API 调用情况
  • 告警通知：接收数据异常告警通知

北极星免费版与专业版的功能对比可在 北极星"概览" 页面查看。

核心概念​

为了更好地使用北极星数据查询接口，建议您了解以下核心概念：

实时数据 vs T+1 数据​

北极星数据查询接口提供两种类型的数据查询：

  • 实时数据：支持查询最近的数据，数据延迟不超过 120 秒。适用于需要实时监控的场景，如服务端 API 调用量监控、用户在线数监控等。
  • T+1 数据：支持查询前一天的离线统计数据，在当天 10:00 后可查询前一天的数据。适用于需要历史数据分析的场景，如日报统计、趋势分析等。

关于具体的数据项和查询类型，详见 数据查询 API。

开通北极星专业版​

开通方式​

  1. 访问控制台，进入北极星 > 概览页面。
  2. 在页面右上角的应用切换组件中，切换到需要开通专业版的应用。
  3. 在北极星 > 概览页面中，点击立即升级按钮即可开通。

开通页面截图

费用说明​

  • 月功能使用费：1999 元/月
  • 计费方式：开通时如果不满 1 个月，则按实际使用天数折算

快速入门：调用第一个接口​

下面，将以查询用户在线数为例，指导您完成一次完整的数据查询 API 调用。

第 1 步：准备工作​

在开始前，请确保：

  • 您已经开通了北极星专业版（详见开通北极星专业版）。
  • 您已经在控制台创建了 API Key（详见获取 API Key）。API Key 用于接口鉴权，可与其他服务共用一个 API Key。

第 2 步：构建并发送请求​

数据查询 API 的调用过程主要分为三步：准备参数、设置鉴权、发送请求。

1. 准备请求参数​

调用数据查询接口需要以下参数：

  • queryType：查询类型，固定枚举值。例如 active_user_all 表示查询所有在线用户数。
  • timestamp（可选）：事件时间，毫秒级时间戳。为空时查询最近的数据。

2. 设置鉴权​

在请求的 Header 中添加 Authorization 字段，值为您的 API Key：

HTTP
Authorization: sk_AIX8xIPL3FGg1TFDsuRiJhJ9PixpqOhEERdVacJ3SXXX

关于 API Key 的获取方式，详见获取 API Key。

3. 发送 HTTP 请求​

准备好所有参数后，就可以发送 HTTP 请求了。所有请求必须使用 HTTPS 协议，且接口为 POST 请求。

以下是一个调用数据查询接口的完整 HTTP 请求示例：

HTTP
POST /im/statistics/get HTTP/1.1
Host: data.rong-api.com
Authorization: sk_AIX8xIPL3FGg1TFDsuRiJhJ9PixpqOhEERdVacJ3XXX
Content-Type: application/json
Content-Length: 68

{"queryType": "active_user_all", "timestamp": 1747193100000}
说明

数据查询接口的域名 Host 在不同数据中心有多个可用地址。请根据您的应用所在数据中心，使用对应的请求域名。详见 数据查询 API - 请求域名。

第 3 步：处理响应​

请求成功后，服务端会返回 application/json 格式的响应数据。

一个成功的查询响应示例如下：

JSON
{
    "code": 10000,
    "data": [
        {
            "server_ts": 1747641000000,
            "online_count": 37,
            "app_key": "c9kqb3rdkbb8j"
        }
    ],
    "fields": null,
    "msg": null
}
  • code：响应状态码。10000 表示请求成功。
  • data：查询结果数据，包含您请求的统计数据。
  • fields：字段说明（通常为 null）。
  • msg：错误信息（成功时为 null）。

调用 API 准备工作​

调用北极星数据查询 API 前，请确保您的应用已生成 API Key（可与其他服务共用一个 API Key）。

获取 API Key​

按照以下步骤获取 API Key：

  1. 访问应用管理页面

    • 访问应用管理页面
    • 在应用列表中找到需要使用的应用

  2. 进入密钥管理页面

    • 点击该应用的密钥管理菜单项
    • 进入应用管理 > 密钥管理页面

  3. 创建 API Key

    • 在API Key 管理板块中，点击创建 API Key按钮
    • 在弹出的对话框中，自定义此 API Key 的名称
    • 点击确认按钮，即可完成 API Key 的创建

创建 API Key 页面截图

说明

创建成功后，请妥善保管您的 API Key。API Key 用于接口鉴权，泄露后可能影响您的数据安全。

下一步​

恭喜您！您已经了解了北极星数据查询接口的基本调用流程。现在，您可以：

最后于 更新