作业系统对接指导手册
目录

位置数据HTTP上报

# 位置数据HTTP上报接口对接指导

# 一、概述

本文档详细介绍如何对接位置数据上报接口，包括接口信息、请求格式、认证方式及测试示例。 该接口支持单条和批量上报位置数据，适用于各类需要上报位置信息的应用场景。

# 二、环境准备

# 1. 添加依赖

在项目中添加Hutool工具库依赖：

<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-all</artifactId>
    <version>5.8.16</version>
</dependency>

# 2. 服务地址配置

修改测试客户端中的服务基础URL：

private static final String BASE_URL = "http://127.0.0.1:4100/position-server/pos/location/rec/v1/report";

# 三、接口信息

# 1. 单条上报接口

  • URL：/report
  • 请求方式：POST
  • 请求头：Content-Type: application/json
  • 请求体：

# 2. 批量上报接口

  • URL：/reportBatch
  • 请求方式：POST
  • 请求头：
    • Content-Type: application/json
    • appId: 应用ID
    • appSecret: 应用密钥
  • 请求体：位置数据JSON数组

# 四、请求数据格式

# 1. 单条数据结构

{
  "deviceId": "设备ID（标识一类设备。由图创指定）",
  "locationString": "位置信息字符串",
  "appId": "应用ID",
  "appSecret": "应用密钥",
  "props": {  // 这部分由图创指定参数，如果第三方没有，可以就传一个 {}
    "fieldName1" : "fieldValue1",
    "fieldName2": "fieldValue2",
    "fieldName3": "fieldValue3"
  }
}

{
  "deviceId": "d_19275337619XXX",
  "locationString": "d_19275337619XXX,00000000000000000000000000888888,GPS,116.407400,39.904200,0.000000,0.000000,0.000000,1752040194220,1752040194220",
  "appId": "001",
  "appSecret": "123456",
  "props": {
    "fieldName1" : "fieldValue1",
    "fieldName2": "fieldValue2",
    "fieldName3": "fieldValue3"
  }
}

# 2. locationString格式

deviceId,terminalId,locationType,longitude,latitude,altitude,speed,direction,timestamp,createTime
  • deviceId：设备ID（标识一类设备）
  • terminalId：终端ID（唯一标识）
  • locationType：设备类型（GPS/BD/NETWORK）
  • longitude：经度
  • latitude：纬度
  • altitude：海拔（如果没有，传0.0）
  • speed：速度（如果没有，传0.0）
  • direction：方向（如果没有，传0.0）
  • timestamp：时间戳（终端上报时间）
  • createTime：创建时间（第三方服务端上报图创的时间）

# 六、测试示例代码

# 1. 完整测试客户端

package com.gtc.gishubteam.position.rec.client.http;

import cn.hutool.core.util.IdUtil;
import cn.hutool.http.HttpRequest;
import cn.hutool.http.HttpResponse;
import cn.hutool.json.JSONObject;
import cn.hutool.json.JSONUtil;

import java.util.HashMap;
import java.util.Map;

public class LocationReportTestClient {

    // 服务基础URL，替换为实际地址
    private static final String BASE_URL = "http://127.0.0.1:4100/position-server/pos/location/rec/v1/report";

    public static void main(String[] args) {
        // 测试单条上报
        testReportSingle();

        // 测试批量上报
        testReportBatch();
    }

    /**
     * 测试单条位置上报
     */
    public static void testReportSingle() {
        String url = BASE_URL + "/report";

        // 构建请求数据
        JSONObject requestData = new JSONObject();
        requestData.put("deviceId", "d_19275337619991XXX");
        requestData.put("locationString", "d_19275337619991XXX,00000000000000000000000000888888,GPS,116.407400,39.904200,0.000000,0.000000,0.000000,1748568580708,1748568580708");
        requestData.put("appId", "001");
        requestData.put("appSecret", "abcd");

        // 构建props参数   这部分由图创指定参数，如果第三方没有，可以就传一个空map
        Map<String, Object> props = new HashMap<>();
 
        props.put("fieldName1", "fieldValue1");
        props.put("fieldName2", "fieldValue2");
        props.put("fieldName3", "fieldValue3");
 

        requestData.put("props", props);

        // 发送请求
        HttpResponse response = HttpRequest.post(url)
                .header("Content-Type", "application/json")
                .body(requestData.toString())
                .execute();

        // 处理响应
        printResponse(response, "单条上报");
    }

    /**
     * 测试批量位置上报
     */
    public static void testReportBatch() {
        String url = BASE_URL + "/reportBatch";

        // 构建多条请求数据
        JSONObject data1 = createReportData("d_1927533761999151104", "GPS", "测试终端1");
        JSONObject data2 = createReportData("d_1927533761999151104", "BD", "测试终端2");
        JSONObject data3 = createReportData("d_1927533761999151104", "NETWORK", "测试终端3");
        JSONObject data4 = createReportData("d_1927533761999151XXX", "NETWORK", "这是一条错误的插入");

        // 构建请求体
        String requestBody = JSONUtil.createArray()
                .put(data1)
                .put(data2)
                .put(data3)
                .put(data4)
                .toString();

        // 发送请求
        HttpResponse response = HttpRequest.post(url)
                .header("Content-Type", "application/json")
                .header("appId", "001")
                .header("appSecret", "abcd")
                .body(requestBody)
                .execute();

        // 处理响应
        printResponse(response, "批量上报");
    }

    /**
     * 创建上报数据对象
     */
    private static JSONObject createReportData(String deviceId, String locationType, String terminalName) {
        JSONObject data = new JSONObject();
        data.put("deviceId", deviceId);  // 这个Id由位置平台指定给你，可以理解成表示一种类型的设备的设备编码

       //locationString 格式： deviceId ,terminalId,locationType, longitude ,latitude ,altitude,speed ,direction, timestamp ,createTime

        data.put("locationString", String.format("%s,%s,%s,116.407400,39.904200,0.000000,0.000000,0.000000,%s,%s",
                deviceId, IdUtil.getSnowflakeNextIdStr(),locationType, System.currentTimeMillis(), System.currentTimeMillis()));

        // 构建props参数 该部分参数是由位置平台指定给你的。位置平台指定需要哪些字段，你这里就需要进行配置哪些字段进行传入
        Map<String, Object> props = new HashMap<>();
        props.put("fieldName1", "fieldValue1");
        props.put("fieldName2", "fieldValue2");
        props.put("fieldName3", "fieldValue3");

        data.put("props", props);
        return data;
    }

    /**
     * 打印响应结果
     */
    private static void printResponse(HttpResponse response, String testType) {
        System.out.println("=====================" + testType + "测试结果=====================");
        System.out.println("状态码: " + response.getStatus());
        System.out.println("响应内容: " + response.body());
        System.out.println("=====================================================");
    }
}

# 2. 关键方法说明

# 创建上报数据

private static JSONObject createReportData(String deviceId, String locationType, String terminalName) {
    JSONObject data = new JSONObject();
    data.put("deviceId", deviceId);
    
    // locationString格式
    data.put("locationString", String.format("%s,%s,%s,116.407400,39.904200,0.000000,0.000000,0.000000,%s,%s",
            deviceId, IdUtil.getSnowflakeNextIdStr(), locationType, System.currentTimeMillis(), System.currentTimeMillis()));

    // 构建props参数
    Map<String, Object> props = new HashMap<>();
    props.put("locationType", locationType);
    props.put("终端名称", terminalName);
    props.put("remark", "批量测试数据");
    props.put("用户名称", "批量测试用户");

    data.put("props", props);
    return data;
}

# 发送单条上报请求

public static void testReportSingle() {
    String url = BASE_URL + "/report";
    
    // 构建请求数据
    JSONObject requestData = new JSONObject();
    requestData.put("deviceId", "d_1927533761999151104");
    requestData.put("locationString", "d_1927533761999151104,GPS,116.407400,39.904200,...");
    requestData.put("appId", "001");
    requestData.put("appSecret", "abcd");
    
    // 发送请求
    HttpResponse response = HttpRequest.post(url)
            .header("Content-Type", "application/json")
            .body(requestData.toString())
            .execute();
    
    // 处理响应
    printResponse(response, "单条上报");
}

# 发送批量上报请求

public static void testReportBatch() {
    String url = BASE_URL + "/reportBatch";
    
    // 构建多条请求数据
    JSONObject data1 = createReportData("d_1927533761999151101", "GPS", "测试终端1");
    JSONObject data2 = createReportData("d_1927533761999151102", "BD", "测试终端2");
    
    // 构建请求体
    String requestBody = JSONUtil.createArray()
            .put(data1)
            .put(data2)
            .toString();
    
    // 发送请求
    HttpResponse response = HttpRequest.post(url)
            .header("Content-Type", "application/json")
            .header("appId", "001")
            .header("appSecret", "abcd")
            .body(requestBody)
            .execute();
    
    // 处理响应
    printResponse(response, "批量上报");
}

# 七、响应结果示例

# 1. 单条上报响应

=====================单条上报测试结果=====================
状态码: 200
响应内容: {"code":200,"message":"成功","data":null}
=====================================================

# 2. 批量上报响应

=====================批量上报测试结果=====================
状态码: 200
响应内容: {
  "code": 200,
  "message": "成功",
  "data": {
    "totalCount": 4,
    "successCount": 3,
    "failureCount": 1,
    "failureDetails": [
      {
        "terminalId": "XXXXXXX",
        "errorMessage": "设备ID不存在"
      }
    ]
  }
}
=====================================================

# 八、注意事项

  1. 设备ID有效性：确保使用的deviceId是平台分配的有效ID
  2. locationString格式：严格按照指定格式构造，字段顺序和类型不能错误
  3. 批量处理机制：批量上报会返回每条数据的处理结果，需检查失败详情
上次更新: 2025/07/11, 16:39:07
前言
位置数据TCP上报

← 位置数据TCP上报→

Theme by Vdoing | Copyright © 2023-2026 北京图创时代科技有限公司版权所有