快速上手（Getting Started）

在 5 分钟内用 Python 或 Node.js SDK 跑通 vjmap 的最小闭环。

1. 前置条件

• 已部署的 vjmap 服务，默认运行在 http://127.0.0.1:27660
• 一个有效 JWT Token（开发环境可直接从后端控制台获取；生产请走登录接口）
• Python ≥ 3.8 或 Node.js ≥ 18

2. 健康检查

服务是否活着：

curl -s http://127.0.0.1:27660/heart
# => {"status":"ok","timestamp":"..."}

curl -s http://127.0.0.1:27660/version
# => {"arch":"amd64","os":"windows","status":"ok","time":"...","version":"..."}

3. Python 一分钟体验

# 1. 拷贝 SDK
cp sdk/python/vjmap.py your-project/

# 2. 装依赖
pip install requests

# 3. hello world
python - <<'PY'
from vjmap import Vjmap
svc = Vjmap("http://127.0.0.1:27660/api/v1", "<paste-token>")
print("heart   ->", svc.heart())
print("version ->", svc.version())
print("status  ->", svc.run_status(detail=True)["application"])
PY

期望输出：

heart   -> {'status': 'ok', 'timestamp': '...'}
version -> {'arch': 'amd64', 'os': 'windows', 'status': 'ok', 'time': '...', 'version': '2026041001'}
status  -> {'pid': '...', 'runtime': ..., ...}

4. Node.js 一分钟体验

cp sdk/nodejs/vjmap.js your-project/
node - <<'JS'
const { Vjmap } = require('./vjmap');
(async () => {
  const svc = new Vjmap('http://127.0.0.1:27660/api/v1', '<paste-token>');
  console.log('heart   ->', await svc.heart());
  console.log('version ->', await svc.version());
  console.log('status  ->', (await svc.runStatus()).application);
})();
JS

5. 最常用的 4 步闭环

下面示例用 Python；Node 版本见 examples/nodejs/。

5.1 列出已有的图

maps = svc.list_maps()           # 对应 /api/v1/map/cmd/listmaps/_/v1
for mapid, versions in maps.items():
    print(mapid, [v["version"] for v in versions])

5.2 打开图并读元数据

svc.open_map(mapid="sys_zp", version="v1", mapopenway="GeomRender")
meta = svc.metadata()
print("layers:", [l["name"] for l in meta.get("layers", [])])
print("bounds:", meta.get("bounds"))

5.3 取栅格瓦片 URL（ XYZ source）

url = svc.raster_tile_url(mapid="sys_zp", version="v1",
                          layer="0,1,2,3,4,5,6,7,8", z="{z}", x="{x}", y="{y}")
print(url)
# => http://127.0.0.1:27660/api/v1/map/tile/sys_zp/v1/0,1,.../{z}/{x}/{y}?token=...

把 URL 直接填到 vjmap 的 raster source 就能显示。

5.4 关闭图（可选，释放 图形服务 子进程）

svc.close_map(mapid="sys_zp", version="v1")

6. 下一步

• 想系统了解参数规则？→ 02-conventions.md
• 弄清 token / secretKey？→ 03-authentication.md
• 多租户分区？→ 04-workspace.md
• 跳到接口分类索引 → api/index.md