地图管理（Map Management）

分类 1 / 13 · 接口 15 个 ·

快速目录

共性约定（重要）

• 所有 cmd/* 路径：GET 不需要 body，POST 要求 body 至少一个字段，否则后端回 500 param error。SDK 对无 body 的 cmd 统一走 GET。
• openmap 通过 POST body 传 mapid/version/fileid/uploadname/mapopenway；fileid 必须来自 upload_map 的返回，不要自己拼 md5。
• 所有路径都带 ?token=<JWT>（SDK 自动加）。

---

1. 秒传检测 check_map_file

URL：GET /api/v1/map/mapfile?md5={md5}
用途：客户端上传前先算文件 md5，若 result:true 则复用已有文件，跳过上传。

入参（Query）

出参

{"result": false}

• result=true：已有同 md5 文件；可直接跳过上传用 fileid = md5[:12]
• result=false：需要走 upload_map

示例

curl -s "http://127.0.0.1:27660/api/v1/map/mapfile?token=$T&md5=caf27de8a2259b2c4e04f2afde2f5c42"

svc.check_map_file("caf27de8a2259b2c4e04f2afde2f5c42")

await svc.checkMapFile('caf27de8a2259b2c4e04f2afde2f5c42');

---

2. 上传源文件 upload_map

URL：POST /api/v1/map/uploads
Content-Type：multipart/form-data

入参（Form）

出参

{"fileid":"caf27de8a225","mapid":"caf27de8a225","uploadname":"caf27de8a225.dwg"}

• fileid：生成的12 位十六进制（= md5 前 12 位）
• mapid：默认等于 fileid；后续 open_map 可以给另一个业务名
• uploadname：服务端实际落盘的文件名

示例

curl -s -X POST "http://127.0.0.1:27660/api/v1/map/uploads?token=$T" \
  -F "file=@./my.dwg" \
  -F "md5=$(md5sum my.dwg | awk '{print $1}')"

up = svc.upload_map("./my.dwg")
fileid, uploadname = up["fileid"], up["uploadname"]

const up = await svc.uploadMap('./my.dwg');
const { fileid, uploadname } = up;

---

3. 打开/创建地图 open_map

URL：POST /api/v1/map/openmap/{mapid}?version={version} （SDK 默认走 POST；GET 等价）

这是整套 API 的中心接口。它同时承担：

• 首次创建：mapid 未存在时结合 fileid + uploadname 新建
• 再次打开：mapid 已存在时忽略 fileid/uploadname
• 切换模式：mapopenway 决定是否拉起 渲染子进程

入参（JSON body）

出参（节选，完整见 snapshot）

真实响应片段

{
  "mapid": "nb_roundtrip_1776829368",
  "version": "v1",
  "fileid": "caf27de8a225",
  "uploadname": "caf27de8a225.dwg",
  "filename": "caf27de8a225.dwg",
  "mapopenway": "Memory",
  "bounds": "[67108.08576259,-10253.62403246,73355.58576721,-4006.12402784]",
  "isnewmap": true,
  "format": "png",
  "layers": "[{\"color\":\"#ffffff\",\"index\":0,...}]",
  "styles": "[{\"backcolor\":0,\"isgeom\":false,...}]"
}

示例

svc.open_map(
    mapid="demo_dwg", version="v1",
    mapopenway="Memory",
    fileid=up["fileid"], uploadname=up["uploadname"],
)

await svc.openMap({
  mapid: 'demo_dwg', version: 'v1',
  mapopenway: 'Memory',
  fileid: up.fileid, uploadname: up.uploadname,
});

---

4. 修改地图 update_map

URL：POST /api/v1/map/updatemap/{mapid}?version={version}

用法：修改 已存在图的属性（描述、可见性、部分字段等）。实现上等价于"带新参数再打开一次"，因此 body 通常和 open_map 类似，加上要改的字段。

入参（JSON body）

出参

结构与 open_map 返回一致。

示例

svc.update_map("demo_dwg", "v1", body={
    "mapid": "demo_dwg",
    "fileid": up["fileid"],
    "uploadname": up["uploadname"],
    "mapopenway": "Memory",
    "description": "添加二次开发示例描述",
})

---

5. 关闭地图 close_map

URL：GET /api/v1/map/cmd/closemap/{mapid}/{version}

仅断开 图形服务 中的内存/渲染引用；不删除数据库文件，也不删图。

出参

{"status": true}

注意：POST 无 body 会 500

# ✗ 500 param error
curl -X POST ".../closemap/sys_zp/v1?token=$T"
# ✓ 200
curl ".../closemap/sys_zp/v1?token=$T"
# ✓ 200（POST 可以，但 body 必须有至少一个字段）
curl -X POST ".../closemap/sys_zp/v1?token=$T" -d '{"fileid":"caf27de8a225"}' -H 'content-type: application/json'

SDK 内部统一使用 GET 规避该陷阱。

---

6. 删除地图 delete_map

URL：GET /api/v1/map/cmd/deletemap/{mapid}/{version}?keepSource={bool}

出参

{"status": true}

示例

svc.delete_map("demo_dwg", "v1", keep_source=True)

---

7. 重命名地图 rename_map（已知不稳定）

URL：GET /api/v1/map/cmd/renamemap/{old}/_?newmapid={new}

响应样例（实测）

{
  "status": false,
  "error": true,
  "reason": "mapid is empty",
  "newmapid": "xxx_new",
  "AuthorityId": "root"
}

---

8. 删除源文件 delete_map_file

URL：GET /api/v1/map/cmd/deletemapfile/_/v1?files=a.dwg;b.dwg

删除上传到 data/mapfiles/ 目录下的物理文件。被删的文件必须没有图在引用。

出参（实测）

{
  "deleted": [],
  "deletedCount": 0,
  "notFound": ["__nb_nonexistent__.dwg"],
  "status": false
}

示例

svc.delete_map_file(["caf27de8a225.dwg"])
# 或字符串
svc.delete_map_file("a.dwg;b.dwg")

---

9. 列出地图 list_maps

URL：GET /api/v1/map/cmd/listmaps/_/v1

入参

出参（实测）

{
  "sys_zp": [
    {
      "db": "c47be46a2ad2.db",
      "filename": "c47be46a2ad2.dwg",
      "geom": true,
      "mtime": "2026-04-10 11:31:00",
      "status": "finish",
      "uploadname": "sys_zp.dwg",
      "version": "v1"
    }
  ]
}

• 顶层 key 是 mapid，value 是该图所有版本的数组
• geom:true 表示该图已有切片缓存
• status:"finish" 表示打开流程完成

示例

maps = svc.list_maps()
for mapid, versions in maps.items():
    print(mapid, [v["version"] for v in versions])

const maps = await svc.listMaps();

---

10. 读元数据 metadata

URL：GET /api/v1/map/cmd/metadata/{mapid}/{version}

图必须先 open_map 打开才能读到完整元数据。

入参（Query）

出参（节选）

字段非常多，以下是二次开发最常用的子集：

⚠ 注意：layers / styles / findFonts 等被序列化成字符串存在顶层；SDK 不会自动解嵌套 JSON，请按需 json.loads()。

示例

svc.open_map("sys_zp", "v1", mapopenway="Memory",
             fileid="c47be46a2ad2", uploadname="sys_zp.dwg")
meta = svc.metadata("sys_zp", "v1")
layers = json.loads(meta["layers"])

---

11. 修改元数据 update_metadata

URL：POST /api/v1/map/cmd/updateMetadata/{mapid}/{version}

通过 POST body 修改图的"用户可编辑字段"（通常是 description、layerOn 状态、业务标签等）。

入参（JSON body）

{
  "fields": [
    { "name": "description", "value": "我是新的描述" },
    { "name": "tags",        "value": "building,sample" }
  ]
}

具体可编辑字段清单取决于后端版本；二次开发前可用 metadata?enableEditMeta=true 先探测。

出参

{"status": true}

示例

svc.update_metadata("demo_dwg", "v1", body={
    "fields": [{"name": "description", "value": "hello"}]
})

---

12. 缩略图 thumbnail

URL：GET /api/v1/map/cmd/thumbnail/{mapid}/{version}?width=W&height=H[&layers=...][&backcolor=...]

返回 PNG 图片字节流。

常用参数

SDK

svc.open_map("sys_zp", "v1", mapopenway="GeomRender",
             fileid="c47be46a2ad2", uploadname="sys_zp.dwg")
png = svc.thumbnail_bytes("sys_zp", "v1", width=256, height=160)
open("thumb.png","wb").write(png)

const buf = await svc.thumbnailBytes('sys_zp', 'v1', { width: 256, height: 160 });
fs.writeFileSync('thumb.png', buf);

也可以只构造 URL 直接嵌到 <img src>：

url = svc.thumbnail_url("sys_zp", "v1", width=128, height=96)
# => http://127.0.0.1:27660/api/v1/map/cmd/thumbnail/sys_zp/v1?width=128&height=96&token=...

---

13. 支持的格式 support_format

URL：GET /api/v1/map/cmd/supportFormat/_/v1

实测响应

{
  "cad": "dwg;dxf",
  "image": "webp;heic;zip;png;pdf;jpg;jpe;jpc;heif;exif;avif;bmp;dib;tiff;hif;hdr;jfif;gif;tif;jpeg"
}

---

14. 系统常量 const_data

URL：GET /api/v1/map/cmd/constData/_/v1

返回系统级字典，最常用的是 CAD 实体类型号 → AcDb 类名 的映射。

实测响应（节选）

{
  "entTypeIdMap": {
    "1":  "AcDbLine",
    "2":  "AcDbPolyline",
    "5":  "AcDbSpline",
    "6":  "AcDbArc",
    "7":  "AcDbCircle",
    "10": "AcDbBlockReference",
    "11": "AcDbHatch",
    "12": "AcDbMText",
    "13": "AcDbText",
    "34": "AcDb3dSolid"
  }
}

搭配 query_features 的 entType 过滤参数使用。

---

15. 数据范围 get_data_bounds

URL：GET /api/v1/map/cmd/getDataBounds/{mapid}/{version}

返回图上所有 几何实体的紧凑包围盒，比 metadata.bounds（可能含空图框）更贴合可见数据。

实测响应

{
  "bounds": [
    587464241.0047014,
    3103794303.1750364,
    587769759.9828022,
    3104004303.209077
  ],
  "status": true
}

示例

b = svc.get_data_bounds("sys_zp", "v1")["bounds"]
# 用来设置 vjmap 初始 fitBounds

---

下一分类：02-tiles-and-styles.md