API 参考已发布

RAILWISE-OS 数据接入规范

RAILWISE-OS 监测数据接入标准规范，包含数据格式、校验规则、批量导入与实时推送协议

复核 2026-07-09入门公开可引用RailWise 技术团队

API 参考

RAILWISE-OS 数据接入规范

AI语义标签: #数据接入 #监测数据格式 #数据校验 #批量导入 #实时推送 #数据规范

1. 概述

RAILWISE-OS 支持多种数据接入方式，适用于不同场景下的监测数据汇入需求：

接入方式	适用场景	实时性	数据量	复杂度
REST API 批量写入	定期批量上传、第三方系统对接	分钟级	中	低
MQTT 实时推送	自动化监测设备、IoT传感器	秒级	高	中
文件批量导入	历史数据迁移、外业数据整理	离线	大	低
数据库直连同步	私有化部署、已有数据库系统	准实时	大	高

2. 数据格式标准

2.1 通用数据模型

所有监测数据遵循统一的数据模型：

interface MonitoringRecord {
  // 必填字段
  project_id: string;           // 项目ID
  point_id: string;             // 监测点ID（项目内唯一）
  sensor_type: SensorType;      // 传感器类型
  measured_at: string;          // 测量时间（ISO 8601，带时区）
  values: RecordValues;         // 测量值（见下文）

  // 可选字段
  device_id?: string;           // 设备ID
  operator_id?: string;         // 操作人ID
  weather?: WeatherInfo;        // 天气信息
  temperature?: number;         // 环境温度（℃）
  remark?: string;              // 备注
}

type SensorType =
  | 'total_station'   // 全站仪
  | 'level'           // 水准仪
  | 'gnss'            // GNSS接收机
  | 'inclinometer'    // 测斜仪
  | 'strain_gauge'    // 应变计
  | 'pressure_cell'   // 土压力计
  | 'settlement_gauge' // 沉降计
  | 'crack_meter'     // 裂缝计
  | 'thermometer'     // 温度计
  | 'custom';         // 自定义传感器

2.2 传感器类型数据格式

全站仪 (total_station)

{
  "point_id": "point_k12_350_01",
  "sensor_type": "total_station",
  "measured_at": "2026-07-08T08:00:00+08:00",
  "values": {
    "x": 395123.456,        // 坐标X（米）
    "y": 2812345.678,       // 坐标Y（米）
    "z": 15.234,            // 高程H（米）
    "dx": 0.5,              // X方向累计位移（mm）
    "dy": -0.3,             // Y方向累计位移（mm）
    "dz": 0.1,              // Z方向累计位移（mm）
    "distance": 123.456,    // 斜距（m，可选）
    "horizontal_angle": 120.5,  // 水平角（°，可选）
    "vertical_angle": 85.2      // 竖直角（°，可选）
  },
  "unit": "mm"
}

水准仪 (level)

{
  "point_id": "point_bm_01",
  "sensor_type": "level",
  "measured_at": "2026-07-08T08:00:00+08:00",
  "values": {
    "elevation": 15.234,      // 高程（m）
    "settlement": -2.5,       // 累计沉降（mm）
    "settlement_rate": -0.1   // 沉降速率（mm/d）
  },
  "unit": "mm"
}

GNSS (gnss)

{
  "point_id": "point_gnss_01",
  "sensor_type": "gnss",
  "measured_at": "2026-07-08T08:00:00+08:00",
  "values": {
    "latitude": 29.817123,    // 纬度（°）
    "longitude": 121.550456,  // 经度（°）
    "elevation": 15.234,      // 椭球高（m）
    "dx": 1.2,                // 东方向位移（mm）
    "dy": -0.8,               // 北方向位移（mm）
    "dz": 0.3,                // 垂直方向位移（mm）
    "hdop": 1.5,              // 水平精度因子
    "vdop": 2.1               // 垂直精度因子
  },
  "unit": "mm"
}

测斜仪 (inclinometer)

{
  "point_id": "point_incl_01",
  "sensor_type": "inclinometer",
  "measured_at": "2026-07-08T08:00:00+08:00",
  "values": {
    "depth": 5.0,             // 测孔深度（m）
    "a_axis": 2.5,            // A轴位移（mm）
    "b_axis": -1.8,           // B轴位移（mm）
    "cumulative_a": 12.5,     // A轴累计位移（mm）
    "cumulative_b": -8.3      // B轴累计位移（mm）
  },
  "unit": "mm"
}

2.3 数据校验规则

RAILWISE-OS 对写入数据执行以下校验：

校验规则	说明	错误码
必填字段检查	project_id, point_id, sensor_type, measured_at, values 必须存在	`400101`
时间格式校验	measured_at 必须为有效的 ISO 8601 格式	`400102`
时间范围校验	测量时间不能早于项目开始时间，不能晚于当前时间 + 1小时	`400103`
数值范围校验	坐标值在合理范围内（中国境内）	`400104`
传感器类型校验	sensor_type 必须在预定义列表中	`400105`
数值突变检查	与上次测量值相比，变化量不能超过阈值（可配置）	`400201`
重复数据检查	同一监测点同一时间点不能重复写入	`400202`
逻辑一致性	各字段之间的逻辑关系正确（如 dx/dy/dz 与坐标变化一致）	`400203`

3. REST API 批量写入

3.1 接口说明

POST /v3/data/monitoring/batch

请求限制：

单次请求最多 500 条记录
请求体大小不超过 5MB
频率限制：100 次/分钟

3.2 请求示例

curl -X POST "https://api.os.railwise.cn/v3/data/monitoring/batch" \
  -H "X-API-Key: rwsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_abc123",
    "records": [
      {
        "point_id": "point_k12_350_01",
        "sensor_type": "total_station",
        "measured_at": "2026-07-08T08:00:00+08:00",
        "values": {
          "x": 395123.456,
          "y": 2812345.678,
          "z": 15.234,
          "dx": 0.5,
          "dy": -0.3,
          "dz": 0.1
        }
      },
      {
        "point_id": "point_k12_350_02",
        "sensor_type": "total_station",
        "measured_at": "2026-07-08T08:00:00+08:00",
        "values": {
          "x": 395124.567,
          "y": 2812346.789,
          "z": 15.345,
          "dx": 0.8,
          "dy": -0.5,
          "dz": 0.2
        }
      }
    ]
  }'

3.3 TypeScript SDK 示例

import { RailWiseOSClient } from '@railwise/os-sdk';

const client = new RailWiseOSClient({
  apiKey: 'rwsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  baseURL: 'https://api.os.railwise.cn/v3',
});

// 批量写入数据
async function batchUploadData() {
  const records = [
    {
      point_id: 'point_k12_350_01',
      sensor_type: 'total_station' as const,
      measured_at: '2026-07-08T08:00:00+08:00',
      values: {
        x: 395123.456,
        y: 2812345.678,
        z: 15.234,
        dx: 0.5,
        dy: -0.3,
        dz: 0.1,
      },
    },
    // ... 更多记录
  ];

  const result = await client.data.batchUpload({
    project_id: 'proj_abc123',
    records,
  });

  console.log(`成功: ${result.success}/${result.total}`);

  // 处理失败记录
  if (result.failed > 0) {
    const failed = result.details.filter(r => r.status === 'failed');
    console.error('失败记录:', failed);
  }
}

3.4 响应说明

{
  "code": 200,
  "data": {
    "total": 500,
    "success": 498,
    "failed": 2,
    "details": [
      {
        "point_id": "point_k12_350_01",
        "status": "success",
        "data_id": "data_001"
      },
      {
        "point_id": "point_k12_350_02",
        "status": "failed",
        "error": {
          "code": "400104",
          "message": "坐标值超出合理范围"
        }
      }
    ]
  }
}

注意：批量写入采用“部分成功”策略，即单条记录失败不影响其他记录写入。

4. MQTT 实时推送

4.1 连接配置

适用于自动化监测设备（如 RAILWISE-TSM 全站仪自动化监测平台）的实时数据推送。

参数	说明
Broker 地址	`mqtts://mqtt.os.railwise.cn:8883`（生产） / `mqtts://sandbox-mqtt.os.railwise.cn:8883`（沙箱）
协议版本	MQTT 5.0
认证方式	用户名密码（由系统分配）
Client ID	`device_{device_id}_{随机后缀}`
Keep Alive	60 秒
QoS	1（至少一次）

4.2 主题规范

# 数据上报主题
railwise/{project_id}/{device_id}/data

# 设备状态上报
railwise/{project_id}/{device_id}/status

# 系统指令下发（订阅）
railwise/{project_id}/{device_id}/command

# 指令响应
railwise/{project_id}/{device_id}/command/response

4.3 数据上报格式

{
  "timestamp": "2026-07-08T08:00:00+08:00",
  "device_id": "tsm_001",
  "records": [
    {
      "point_id": "point_k12_350_01",
      "sensor_type": "total_station",
      "values": {
        "x": 395123.456,
        "y": 2812345.678,
        "z": 15.234
      }
    }
  ]
}

4.4 Python MQTT 客户端示例

import json
import paho.mqtt.client as mqtt
from datetime import datetime, timezone

# 连接配置
BROKER = "mqtts://mqtt.os.railwise.cn"
PORT = 8883
USERNAME = "device_tsm_001"
PASSWORD = "your_mqtt_password"
PROJECT_ID = "proj_abc123"
DEVICE_ID = "tsm_001"

# 主题
DATA_TOPIC = f"railwise/{PROJECT_ID}/{DEVICE_ID}/data"
STATUS_TOPIC = f"railwise/{PROJECT_ID}/{DEVICE_ID}/status"

def on_connect(client, userdata, flags, rc, properties=None):
    if rc == 0:
        print("MQTT 连接成功")
        # 订阅指令主题
        client.subscribe(f"railwise/{PROJECT_ID}/{DEVICE_ID}/command")
    else:
        print(f"MQTT 连接失败，返回码: {rc}")

def on_message(client, userdata, msg):
    print(f"收到指令: {msg.topic} - {msg.payload.decode()}")

def publish_data(client, records):
    payload = {
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "device_id": DEVICE_ID,
        "records": records
    }
    client.publish(DATA_TOPIC, json.dumps(payload), qos=1)
    print(f"已发布数据: {len(records)} 条记录")

# 初始化客户端
client = mqtt.Client(
    client_id=f"device_{DEVICE_ID}_{int(datetime.now().timestamp())}",
    protocol=mqtt.MQTTv5
)
client.username_pw_set(USERNAME, PASSWORD)
client.tls_set()  # 启用 TLS
client.on_connect = on_connect
client.on_message = on_message

# 连接并启动循环
client.connect(BROKER, PORT, keepalive=60)
client.loop_start()

# 示例：发布监测数据
records = [
    {
        "point_id": "point_k12_350_01",
        "sensor_type": "total_station",
        "values": {
            "x": 395123.456,
            "y": 2812345.678,
            "z": 15.234
        }
    }
]
publish_data(client, records)

5. 文件批量导入

5.1 支持的文件格式

格式	扩展名	说明
Excel	.xlsx, .xls	标准表格格式，支持多 Sheet
CSV	.csv	逗号分隔值，UTF-8 编码
JSON	.json	标准 JSON 数组格式
RailWise 专用	.rwd	加密二进制格式，用于大文件

5.2 Excel 导入模板

Excel 导入需使用标准模板格式：

point_id	sensor_type	measured_at	x	y	z	dx	dy	dz	remark
point_01	total_station	2026-07-08 08:00:00	395123.456	2812345.678	15.234	0.5	-0.3	0.1	正常
point_02	total_station	2026-07-08 08:00:00	395124.567	2812346.789	15.345	0.8	-0.5	0.2	正常

5.3 导入接口

POST /v3/data/import
Content-Type: multipart/form-data

请求参数：

参数	类型	必填	说明
`file`	File	是	数据文件
`project_id`	string	是	目标项目ID
`mapping`	JSON	否	字段映射配置
`skip_validation`	boolean	否	是否跳过校验

curl -X POST "https://api.os.railwise.cn/v3/data/import" \
  -H "X-API-Key: rwsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@monitoring_data.xlsx" \
  -F "project_id=proj_abc123" \
  -F "mapping={\"sheet_index\":0,\"header_row\":1}"

响应示例：

{
  "code": 200,
  "data": {
    "import_id": "imp_001",
    "status": "processing",
    "total_rows": 1000,
    "processed_rows": 0,
    "poll_url": "/data/import/imp_001/status"
  }
}

6. 数据质量与异常处理

6.1 数据质量标记

每条数据写入后，系统会自动标记质量状态：

质量标记	说明	处理建议
`valid`	数据有效	正常使用
`warning`	数据警告（如接近阈值）	关注并核实
`suspicious`	数据可疑（如突变）	人工复核
`invalid`	数据无效（校验失败）	排查原因后重新写入

6.2 异常数据处理流程

数据写入 → 自动校验 → 质量标记 → 异常通知
                ↓
         异常数据 → 人工复核 → 确认/修正/删除

6.3 获取异常数据

GET /v3/data/abnormal

查询参数：

参数	类型	必填	说明
`project_id`	string	是	项目ID
`severity`	string	否	严重程度：`warning`, `suspicious`, `invalid`
`start_time`	string	否	起始时间
`end_time`	string	否	截止时间

7. 相关文档

文档版本: v3.2.0 | 最后更新: 2026-07-08 | API版本: v3