5.8 KiB
5.8 KiB
地图转换API接口使用说明
接口地址
POST /api/map-converter/process-json-list
请求格式
请求体应为一个JSON数组，每个数组元素代表一个楼层的地图信息：
[
{
"floors": 1, // 楼层 (int, 必填, 不可重复)
"type": "smap", // 地图类型 (string, 必填, smap或scene)
"placeholder1": "...", // 地图文件内容 (string, 必填)
"placeholder2": "...", // 地图文件内容 (string, 选填)
"OriginalProperties": "...." // 原始地图内容 (string, 必填)
}
]
字段说明
| 字段名 | 说明 | 类型 | 是否必填 | 其他要求 |
|---|---|---|---|---|
| floors | 楼层 | int | 必填 | 不可重复，必须连续 |
| type | 地图类型 | string | 必填 | 可填smap或scene，在一层楼中placeholder有多个时，type必须为smap |
| placeholder1 | 上传的地图文件内容 | string | 必填 | 在一层楼中placeholder所加载的地图类型必须与type一致 |
| placeholder2 | 上传的地图文件内容 | string | 选填 | 在一层楼中placeholder所加载的地图类型必须与type一致 |
| placeholderX | 上传的地图文件内容 | string | 选填 | 在一层楼中placeholder所加载的地图类型必须与type一致 |
| OriginalProperties | 原始地图内容 | string | 必填 | 可以为空，用于保留原场景属性 |
请求验证规则
-
楼层验证：
- 楼层编号必须唯一且连续
- 如果存在楼层1、2、4，则缺少楼层3，请求将被拒绝
-
机器人组验证：
- 同一机器人ID不能出现在不同组中（包括跨楼层情况）
- 如果发现重复，将返回错误信息
-
地图类型验证：
- 当一层楼有多个placeholder时，type必须为"smap"
- 所有placeholder的内容类型必须与type一致
响应格式
成功响应可能有两种形式：
1. ZIP文件流响应（主要响应形式）
API处理成功后，默认返回ZIP文件流，包含处理后的地图文件：
Content-Type: application/zip
Content-Disposition: attachment; filename=converted_map.zip
2. JSON格式响应（仅在特定情况下）
{
"success": true,
"message": "请求处理成功",
"timestamp": "2023-05-15T10:30:45.123456",
"data": {
// 处理结果数据
}
}
错误响应
{
"success": false,
"message": "错误描述",
"timestamp": "2023-05-15T10:30:45.123456",
"error": "详细错误信息"
}
处理逻辑
单楼层处理
-
单个placeholder：
- 如果type为"scene"且OriginalProperties有值，将执行场景丰富化
- 最终返回包含处理后scene文件的ZIP
-
多个placeholder：
- 如果type为"smap"，将执行地图拼接
- 最终返回包含拼接后scene文件的ZIP
多楼层处理
- 所有楼层必须连续
- 每个楼层按照单楼层逻辑处理
- 最终返回包含所有处理后文件的ZIP
使用示例
Python requests示例
import requests
import json
# 准备请求数据
data = [
{
"floors": 1,
"type": "smap",
"placeholder1": '{"version": "1.0", "mapData": "..."}',
"OriginalProperties": ""
}
]
# 发送请求
response = requests.post(
"http://localhost:8000/api/map-converter/process-json-list",
json=data
)
# 处理响应
if response.headers.get('content-type', '').startswith('application/json'):
# JSON响应
result = response.json()
print(json.dumps(result, indent=2, ensure_ascii=False))
else:
# ZIP文件流响应
with open('result.zip', 'wb') as f:
f.write(response.content)
print("文件已保存为 result.zip")
# 解压ZIP文件（可选）
import zipfile
import os
output_dir = "outputmap"
os.makedirs(output_dir, exist_ok=True)
with zipfile.ZipFile('result.zip', 'r') as zip_ref:
zip_ref.extractall(output_dir)
print(f"ZIP文件已解压到 {output_dir} 目录")
cURL示例
curl -X POST "http://localhost:8000/api/map-converter/process-json-list" \
-H "Content-Type: application/json" \
-d '[
{
"floors": 1,
"type": "scene",
"placeholder1": "{\"version\": \"1.0\", \"mapData\": \"...\"}",
"OriginalProperties": "{\"robotGroups\": [...]}"
}
]' \
--output result.zip
启动服务
基本启动
cd d:\CodeProject\map-converter
python start_map_service.py
高级启动选项
# 指定主机和端口
python start_map_service.py --host 0.0.0.0 --port 8080
# 开发模式（启用热重载）
python start_map_service.py --reload
服务状态检查
# 检查服务是否运行
curl http://localhost:8000/
服务默认运行在 http://127.0.0.1:8000
测试工具
项目提供了模拟API请求的脚本，可用于测试：
python simulate_api_request.py
该脚本会：
- 检查服务状态
- 读取intput.json文件中的测试数据
- 发送API请求
- 处理并保存响应结果
注意事项
- 文件大小限制：大文件可能需要调整服务器配置
- 超时设置：复杂地图处理可能需要较长时间，建议设置适当的客户端超时
- 编码格式：所有文本内容应使用UTF-8编码
- JSON格式：确保所有JSON内容格式正确，特别注意尾随逗号问题
- 临时文件：处理过程中会创建临时文件，系统会自动清理
错误排查
- 楼层不连续错误：检查floors字段是否连续
- 机器人组重复错误：检查OriginalProperties中的robotGroups配置
- 地图类型不匹配错误：确保placeholder内容与type字段一致
- JSON解析错误：验证所有JSON内容格式正确
日志查看
服务运行日志会输出到控制台，包含详细的处理信息和错误堆栈，可用于问题排查。