RAILWISE-TSM 数据导出与第三方系统集成

RAILWISE-TSM 数据导出与第三方系统集成

适用版本: TSM v3.2+ 阅读对象: 系统集成工程师、软件开发人员、数据分析师 接口协议: RESTful API / WebSocket / gRPC

---

1. 概述

RAILWISE-TSM 提供多层级的数据开放能力，支持与 BIM 平台、GIS 系统、企业 ERP、政府监管平台等第三方系统无缝对接。数据导出支持实时流式推送和批量历史导出两种模式。

1.1 集成架构

┌─────────────────────────────────────────────────────────────┐
│                    RAILWISE-TSM 平台                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  监测数据库   │  │  文件存储    │  │  消息队列    │      │
│  │  (PostgreSQL)│  │  (MinIO)    │  │  (Redis)    │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
│         │                 │                 │               │
│  ┌──────▼───────┐  ┌──────▼───────┐  ┌──────▼───────┐      │
│  │  REST API    │  │  WebSocket   │  │  gRPC 服务   │      │
│  │  /api/v3/    │  │  /ws/v3/     │  │  :50051      │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
└─────────┼─────────────────┼─────────────────┼──────────────┘
          │                 │                 │
    ┌─────▼─────┐     ┌─────▼─────┐     ┌─────▼─────┐
    │  BIM平台  │     │  GIS系统  │     │  监管平台  │
    │  企业ERP  │     │  大屏展示  │     │  移动端APP │
    └───────────┘     └───────────┘     └───────────┘

---

2. REST API 接口规范

2.1 认证方式

TSM API 采用 API Key + JWT 双认证机制：

# 获取访问令牌
POST /api/v3/auth/token
Content-Type: application/json

{
  "api_key": "rw_live_xxxxxxxxxxxxxxxx",
  "api_secret": "xxxxxxxxxxxxxxxxxxxxxxxx"
}

# 响应
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

后续请求在 Header 中携带：Authorization: Bearer <access_token>

• API Key 具有项目级权限，请妥善保管，勿提交至代码仓库
• 生产环境建议配置 IP 白名单
• Token 有效期默认 1 小时，支持刷新机制

2.2 测点数据查询

# 获取测点列表
GET /api/v3/projects/{project_id}/monitor-points
?status=active&category=displacement&page=1&page_size=50

# 响应示例
{
  "total": 128,
  "page": 1,
  "page_size": 50,
  "data": [
    {
      "id": "mp-20240115-001",
      "name": "SP-01",
      "category": "horizontal_displacement",
      "coordinate": {
        "x": 395123.456,
        "y": 2810456.789,
        "z": 12.345
      },
      "instrument_id": "TS-01",
      "status": "active",
      "alert_level": "normal",
      "latest_value": {
        "timestamp": "2025-01-15T08:00:00+08:00",
        "value_x": 2.34,
        "value_y": -1.56,
        "value_z": 0.12
      }
    }
  ]
}

2.3 历史数据导出

# 批量导出历史监测数据
POST /api/v3/projects/{project_id}/data/export
Content-Type: application/json
Authorization: Bearer <token>

{
  "point_ids": ["mp-20240115-001", "mp-20240115-002"],
  "start_time": "2025-01-01T00:00:00+08:00",
  "end_time": "2025-01-15T23:59:59+08:00",
  "format": "csv",           // csv / json / xlsx
  "include_raw": true,       // 是否包含原始观测值
  "include_processed": true, // 是否包含平差后值
  "coordinate_system": "project"  // project / wgs84 / cgcs2000
}

# 响应返回异步任务ID
{
  "task_id": "export_20250115_001",
  "status": "queued",
  "estimated_completion": "2025-01-15T08:05:00+08:00",
  "download_url": "/api/v3/download/export_20250115_001"
}

提示

• 单次导出时间跨度建议不超过 90 天
• 数据量超过 10 万条时自动转为异步任务
• 可通过 /api/v3/tasks/{task_id} 查询导出进度

---

3. 实时数据推送（WebSocket）

3.1 建立连接

// JavaScript 客户端示例
const ws = new WebSocket('wss://tsm.railwise.cn/ws/v3/realtime');

ws.onopen = () => {
  // 发送认证消息
  ws.send(JSON.stringify({
    type: 'auth',
    token: 'eyJhbGciOiJSUzI1NiIs...'
  }));

  // 订阅测点数据
  ws.send(JSON.stringify({
    type: 'subscribe',
    project_id: 'proj-2024-nb-001',
    point_ids: ['mp-20240115-001', 'mp-20240115-002'],
    fields: ['value', 'delta', 'rate', 'alert_level']
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('实时数据:', data);
  // { point_id, timestamp, value_x, value_y, value_z, delta, rate, alert_level }
};

3.2 订阅消息格式

字段	类型	必填	说明
type	String	是	subscribe / unsubscribe
project_id	String	是	项目唯一标识
point_ids	Array	否	指定测点，空数组表示全部
fields	Array	否	指定字段，默认全部
alert_level	String	否	仅订阅指定等级数据

3.3 心跳机制

// 客户端每 30 秒发送心跳
setInterval(() => {
  ws.send(JSON.stringify({ type: 'ping' }));
}, 30000);

// 服务端响应
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'pong') {
    console.log('连接正常');
  }
};

• 网络异常时 WebSocket 会自动断开，需实现重连逻辑
• 建议采用指数退避重连策略：1s → 2s → 4s → 8s → 最大 60s
• 重连后需重新发送订阅消息

---

4. 数据导出格式详解

4.1 CSV 格式

# 测点数据导出示例
point_id,name,timestamp,value_x_mm,value_y_mm,value_z_mm,delta_x_mm,delta_y_mm,delta_z_mm,rate_x_mm_d,rate_y_mm_d,rate_z_mm_d,alert_level,temperature_c
mp-20240115-001,SP-01,2025-01-15T08:00:00+08:00,2.34,-1.56,0.12,0.15,-0.08,0.02,0.45,-0.24,0.06,normal,18.5
mp-20240115-001,SP-01,2025-01-15T12:00:00+08:00,2.51,-1.62,0.14,0.17,-0.06,0.02,0.51,-0.18,0.06,normal,19.2
mp-20240115-002,SP-02,2025-01-15T08:00:00+08:00,5.67,3.21,-0.45,0.32,0.18,-0.03,0.96,0.54,-0.09,yellow,18.5

4.2 JSON 格式

{
  "metadata": {
    "project_id": "proj-2024-nb-001",
    "project_name": "宁波地铁3号线控制保护区监测",
    "export_time": "2025-01-15T14:30:00+08:00",
    "coordinate_system": "CGCS2000",
    "unit": "mm"
  },
  "data": [
    {
      "point_id": "mp-20240115-001",
      "name": "SP-01",
      "category": "horizontal_displacement",
      "instrument": "TS-01",
      "records": [
        {
          "timestamp": "2025-01-15T08:00:00+08:00",
          "value": { "x": 2.34, "y": -1.56, "z": 0.12 },
          "delta": { "x": 0.15, "y": -0.08, "z": 0.02 },
          "rate": { "x": 0.45, "y": -0.24, "z": 0.06 },
          "alert_level": "normal",
          "environment": { "temperature": 18.5, "humidity": 65 }
        }
      ]
    }
  ]
}

4.3 Excel 格式

Excel 导出包含多个工作表：

工作表	内容
测点信息	测点坐标、类型、仪器、报警阈值
监测数据	时间序列数据（主表）
变化量	各期变化量统计
速率	变化速率分析
报警记录	历史报警事件
元数据	导出信息、坐标系说明

---

5. 第三方系统集成方案

5.1 BIM 平台集成

与 Revit、Bentley、广联达等 BIM 平台对接，实现监测数据三维可视化：

# Python 示例：将 TSM 数据推送至 BIM 平台
import requests
import json

class TSMBIMBridge:
    def __init__(self, tsm_base_url, api_key, bim_webhook_url):
        self.tsm_url = tsm_base_url
        self.api_key = api_key
        self.bim_webhook = bim_webhook_url
        self.token = self._get_token()

    def _get_token(self):
        resp = requests.post(f"{self.tsm_url}/api/v3/auth/token", json={
            "api_key": self.api_key,
            "api_secret": "your_secret"
        })
        return resp.json()["access_token"]

    def sync_to_bim(self, project_id):
        # 获取最新监测数据
        headers = {"Authorization": f"Bearer {self.token}"}
        data = requests.get(
            f"{self.tsm_url}/api/v3/projects/{project_id}/monitor-points",
            headers=headers
        ).json()

        # 转换 BIM 平台格式
        bim_payload = {
            "project_id": project_id,
            "update_time": data["timestamp"],
            "monitor_points": [
                {
                    "bim_element_id": point.get("bim_id"),
                    "point_id": point["id"],
                    "displacement": {
                        "x": point["latest_value"]["value_x"],
                        "y": point["latest_value"]["value_y"],
                        "z": point["latest_value"]["value_z"]
                    },
                    "alert_level": point["alert_level"],
                    "color_code": self._get_color(point["alert_level"])
                }
                for point in data["data"]
            ]
        }

        # 推送至 BIM 平台
        requests.post(self.bim_webhook, json=bim_payload)

    def _get_color(self, level):
        colors = {
            "normal": "#00FF00",
            "yellow": "#FFFF00",
            "red": "#FF0000"
        }
        return colors.get(level, "#808080")

5.2 GIS 系统集成

与 ArcGIS、SuperMap、Cesium 等 GIS 平台对接：

// Cesium 实时监测点可视化
const viewer = new Cesium.Viewer('cesiumContainer');

// 连接 TSM WebSocket
const ws = new WebSocket('wss://tsm.railwise.cn/ws/v3/realtime');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  data.monitor_points.forEach(point => {
    const entity = viewer.entities.getById(point.point_id);

    if (entity) {
      // 更新位置和颜色
      entity.position = Cesium.Cartesian3.fromDegrees(
        point.coordinate.lon,
        point.coordinate.lat,
        point.coordinate.z
      );
      entity.point.color = getColorByAlertLevel(point.alert_level);

      // 更新标签显示位移值
      entity.label.text = `Δ=${point.delta.toFixed(2)}mm`;
    } else {
      // 创建新实体
      viewer.entities.add({
        id: point.point_id,
        position: Cesium.Cartesian3.fromDegrees(
          point.coordinate.lon,
          point.coordinate.lat,
          point.coordinate.z
        ),
        point: {
          pixelSize: 10,
          color: getColorByAlertLevel(point.alert_level)
        },
        label: {
          text: `Δ=${point.delta.toFixed(2)}mm`,
          font: '14px sans-serif',
          verticalOrigin: Cesium.VerticalOrigin.BOTTOM
        }
      });
    }
  });
};

5.3 政府监管平台对接

符合《城市轨道交通工程监测技术规范》GB 50911 数据上报要求：

# 定时上报任务配置（在 TSM 工作流中）
POST /api/v3/projects/{project_id}/integrations/government
{
  "enabled": true,
  "platform": "ningbo_metro_supervision",
  "upload_schedule": "0 */4 * * *",
  "data_format": "gb50911_xml",
  "fields": [
    "project_info",
    "monitor_points",
    "daily_data",
    "alert_records"
  ],
  "auth": {
    "type": "sm2_certificate",
    "cert_path": "/certs/gov_sm2.pem"
  }
}

---

6. Webhook 事件通知

6.1 配置接收端点

POST /api/v3/projects/{project_id}/webhooks
{
  "url": "https://your-system.com/tsm/webhook",
  "events": ["alert.triggered", "data.quality.failed", "instrument.offline"],
  "secret": "whsec_xxxxxxxx",  // 用于签名验证
  "retry_policy": {
    "max_retries": 3,
    "backoff": "exponential"
  }
}

6.2 Webhook 签名验证

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    """验证 Webhook 签名"""
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# 在 Flask 中使用
@app.route('/tsm/webhook', methods=['POST'])
def handle_tsm_webhook():
    signature = request.headers.get('X-TSM-Signature')
    if not verify_webhook(request.data, signature, 'whsec_xxxxxxxx'):
        return 'Unauthorized', 401

    event = request.json
    if event['type'] == 'alert.triggered':
        handle_alert(event['data'])

    return 'OK', 200

---

7. SDK 与客户端库

7.1 官方 SDK

语言	安装命令	仓库地址
Python	pip install railwise-tsm-sdk	PyPI
JavaScript	npm install @railwise/tsm-sdk	npm
Java	gradle: com.railwise:tsm-sdk:3.2.0	Maven Central
Go	go get github.com/railwise/tsm-sdk-go	GitHub

7.2 Python SDK 使用示例

from railwise_tsm import TSMClient

# 初始化客户端
client = TSMClient(
    base_url="https://tsm.railwise.cn",
    api_key="rw_live_xxxxxxxx",
    api_secret="xxxxxxxx"
)

# 获取项目列表
projects = client.projects.list()

# 查询测点数据
points = client.monitor_points.list(
    project_id="proj-2024-nb-001",
    status="active"
)

# 导出历史数据
task = client.data.export(
    project_id="proj-2024-nb-001",
    point_ids=["mp-001", "mp-002"],
    start_time="2025-01-01",
    end_time="2025-01-15",
    format="csv"
)

# 等待导出完成并下载
client.tasks.wait_for_completion(task.id)
client.download.file(task.download_url, "./export.csv")

---

8. 常见问题

问题	原因	解决方案
API 返回 401	Token 过期或无效	重新获取 access_token
WebSocket 频繁断开	心跳超时	确保每 30 秒发送 ping
导出任务失败	数据量过大	缩小时间范围或分批导出
数据时区不一致	未指定 timezone	请求中明确使用 +08:00
坐标系偏差	坐标系未统一	导出时指定目标坐标系

---

相关文档

• TSM 全站仪自动化监测平台概述
• TSM 自动化监测流程编排
• TSM 预警规则与报警管理
• TSM 测点管理与坐标系统配置

---