---
title: 快速上手（Getting Started）
source: https://vjmap.com/guide/service/01-getting-started.html
---

# 快速上手（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. 健康检查

服务是否活着：

```bash
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 一分钟体验

```bash
# 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
```

期望输出：

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

## 4. Node.js 一分钟体验

```bash
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 列出已有的图

```python
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 打开图并读元数据

```python
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）

```python
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 关闭图（可选，释放 图形服务 子进程）

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

## 6. 下一步

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