GISBox

如何使用API接口？

GISBox（GIS 工具箱）支持使用 API 接口，打开 GISBox 软件后，我们可以在左侧工具栏中选择“API”栏目，然后点击右上角的“新增 key”按钮添加 API 接口，其中“key”和“安全密钥”作为 Auth 参数，用于验证用户身份或应用程序的合法性，点击查看相应教程 →Auth 参数。

“Key 名称”指的是用于传递特定信息的键名，它通常出现在请求参数、HTTP 头部或响应数据中，当我们新增 key 时需要填写相应的“Key 名称”，如下图所示：

在右侧的操作中，我们可以更改“Key 名称”，如下图所示：

【温馨提示】GSIBox 的 API 功能需要“集团版”套餐才能使用，如需使用，请扫码联系 GISBox 官方微信客服做进一步沟通。

1. 前置 URL

所有 API 接口请求的基础 URL 为：

1
主账号SaaS访问地址 + /api/v1

“主账号 SaaS 访问地址”可以在 GISBox 软件的“设置”→“域名端口”中进行查看，如下图所示：

例如，假设主账号 SaaS 访问地址为：

1
http://192.168.31.122:42225

那么 API 接口的前置 URL 即为：

1
http://192.168.31.122:42225/api/v1

2. Auth 参数

为确保接口访问的安全性，每个接口请求都需要拼接以下参数进行校验，包括“key”和“安全密钥（**secret**）”：

名称 类型 必选 说明
key string 是 生成的 key
timestamp string 是 当前时间戳
sign string 是 使用md5 对（key、secret、timestamp）拼接起来的字符串进行加密生成字符串

示例如下：

1
http://192.168.31.122:42225/api/v1/task/list?key=06150cad-131c-4a13-88cf-90b7c4e76056&timestamp=1736835697953&sign=1D1802A6A4BB9C8A603F696E1E0E3644

3. 响应格式

API 接口的响应数据遵循统一的格式，包含以下字段：

名称 类型 必选 说明
success boolean 是 是否成功
msg string 是 成功提示或错误描述
data object 否 响应核心数据

4. 接口说明

4.1 查询任务信息（GET）

接口地址：

1
GET task/<id>/info

4.1.1 请求参数

名称 类型 必选 说明
id string 是 任务 id

4.1.2 响应参数类型

名称 类型 必选 说明
id string true 任务 id
name string true 任务名
status string true 任务状态（“pending”、“running”、“finished”、“failed”、“canceled”）
type string true 任务类型
inputPath string true 输入路径
outputPath string true 输出路径
settings object true 转换设置项
startTime integer false 开始时间戳
progress number false 当前进度(%)
spentTime integer false 已花费的时间(ms)
remainTime integer false 预估剩余时间(ms)
endTime integer false 结束时间戳

4.1.3 响应示例

请求成功：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "success": true,
  "data": {
    "id": "ngcxb8xzf41x",
    "name": "我的倾斜模型",
    "status": "failed",
    "type": "GeneralModelSlicing",
    "inputPath": "C:\\Users\\admin\\AppData\\Local\\Temp\\6349b52ac052f1100a0099f56ae1360d",
    "outputPath": "C:\\Users\\admin\\Desktop\\rubbish\\大场景",
    "settings": {
      "fileRange": [2, 20],
      "sceneTree": true,
      "is3DTiles1_1": true,
      "enableLOD": true,
      "textureCompressionFormat": "webp",
      "vertexCompress": false,
      "vertexCompressionLevel": 5,
      "x": 120.14757537841797,
      "y": 30.274856567382812,
      "z": 0,
      "name": "西湖区建筑模型",
      "imageRatio": 0.5
    },
    "startTime": 1736838996442,
    "endTime": 1736841982291
  },
  "msg": "请求成功"
}

请求失败：

1
2
3
4
{
  "success": false,
  "msg": "Task not found"
}

4.2 查询任务列表（GET）

接口地址：

1
GET task/list

4.2.1 请求参数

无

4.2.2 响应参数类型

包含所有任务信息的数组，任务信息对象具体字段参考查询任务信息接口。

4.2.3 响应示例

请求成功：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
{
  "success": true,
  "data": [
    {
      "id": "ngcxb8xzf41x",
      "name": "我的倾斜模型",
      "status": "running",
      "type": "GeneralModelSlicing",
      "inputPath": "C:\\Users\\admin\\AppData\\Local\\Temp\\6349b52ac052f1100a0099f56ae1360d",
      "outputPath": "C:\\Users\\admin\\Desktop\\rubbish\\大场景",
      "settings": {
        "fileRange": [2, 20],
        "sceneTree": true,
        "is3DTiles1_1": true,
        "enableLOD": true,
        "textureCompressionFormat": "webp",
        "vertexCompress": false,
        "vertexCompressionLevel": 5,
        "x": 120.14757537841797,
        "y": 30.274856567382812,
        "z": 0,
        "name": "西湖区建筑模型",
        "imageRatio": 0.5
      },
      "startTime": 1736838996442,
      "progress": 0,
      "spentTime": 0,
      "remainTime": 0
    },
    {
      "id": "xoeqj7jrw9fl",
      "name": "我的倾斜模型",
      "status": "finished",
      "type": "GeneralModelSlicing",
      "inputPath": "C:\\Users\\admin\\AppData\\Local\\Temp\\c8f9e1d5c211b16dc34c5181922dc911",
      "outputPath": "C:\\Users\\admin\\Desktop\\rubbish\\新建文件夹 (2)",
      "settings": {
        "fileRange": [2, 20],
        "sceneTree": true,
        "is3DTiles1_1": true,
        "enableLOD": true,
        "textureCompressionFormat": "webp",
        "vertexCompress": false,
        "vertexCompressionLevel": 5,
        "x": 120.19058749999999,
        "y": 30.280553849999997,
        "z": 0,
        "name": "上城区建筑模型",
        "imageRatio": 0.5
      },
      "startTime": 1736838648314,
      "endTime": 1736838670124
    }
  ],
  "msg": "请求成功"
}

请求失败：

1
2
3
4
{
  "success": false,
  "msg": "Invalid signature"
}

4.3 新建任务（POST）

接口地址：

1
POST /task/create

4.3.1 请求参数

Body 类型：

1
application/json
名称 类型 必选 说明
options object 是
type string 是 “ImageSlicing”、“TerrainSlicing ”、“TiltModelSlicing”、“Tiles2OsgbSlicing”、“PointCloudSlicing”
name string 是 任务名称
inputPath string 是 输入路径
outputPath string 是 输出路径
autoStart boolean 否 是否立即开始任务（默认为 true）
settings object 否 转换选项

不同转换类型的settings 参数各不相同，下面分别介绍一下：

（1）影像切片

名称 类型 必选 说明 默认值
tilesize integer 否 瓦片大小 256
minzoom integer 否 最小级别 0
maxzoom integer 是 最大级别
toSrs integer 是 投影参数（3857、4326）
service string 是 服务类型（“TMS”、“WMTS”）
fromSrs string 否 空间参考
background string 否 背景透明（“auto”、“255,255,255”） “auto”
colorStretching object 否 颜色拉伸
type string 是 类型（“deviationAndZoom”、“theMostValuable”、“percent”）
deviation number 否 偏移量（“deviationAndZoom”类型可传该参数）
zoom number 否 缩放系数（“deviationAndZoom”类型可传该参数）
min number 否 最小值（“theMostValuable”类型可传该参数）
max number 否 最大值（“theMostValuable”类型可传该参数）
minPercent number 否 低阈值（%）（“percent”类型可传该参数）
maxPercent number 否 高阈值（%）（“percent”类型可传该参数）

（2）地形切片

无

（3）OSGB 转 3DTiles

名称 类型 必选 说明
srs string 否 空间参考
srsOrigin string 否 零点坐标（如“0，0，0”）
isRebuildTop boolean 否 是否顶层重建
maxConcurrency integer 否 顶层重建最大并发数
is3DTiles1_1 boolean 否 是否输出 3dtile1.1 规范格式
textureFormat string 否 纹理格式（“default” 、“webp”、“uastc”、“etc1s”）
vertexCompress boolean 否 是否顶点压缩
vertexCompressionLevel 0、5、10 否 顶点压缩级别
computedNormal boolean 否 是否计算法线
backFaceCulling boolean 否 是否背面裁剪
mandatoryDoubleSide boolean 否 是否强制双面
noLight boolean 否 是否无光照

（4）3DTiles 转 OSGB

名称 类型 必选 说明
srs string 否 空间参考
srsOrgin string 否 零点坐标
upAxis “Z”、“Y” 否 向上轴

（5）点云切片

名称 类型 必选 说明
srs string 否 空间参考
srsOrigin string 否 零点坐标
vertexCompress boolean 否 是否顶点压缩
vertexCompressionLevel 0、5、10 否 顶点压缩级别
colorIpt number 是 颜色计算（color + colorIpt）* colorType / dividendColor
colorType number 是
dividendColor number 是
isSaveColor boolean 否 是否存储颜色
isSelectAttribute boolean 否 是否属性拾取
isClassification boolean 否
isIntensity boolean 否

4.3.2 响应参数类型

名称 类型 必选 约束 中文名 说明
id string true none none

4.3.3 响应示例

请求成功：

1
2
3
4
5
6
7
{
  "success": true,
  "data": {
    "id": "m2iz285xzzlj"
  },
  "msg": "请求成功"
}

请求失败：

1
2
3
4
{
  "success": false,
  "msg": "Invalid task type"
}

4.4 开始任务（POST）

接口地址：

1
POST /task/<id>/start

4.4.1 请求参数

名称 类型 必选 说明
id string 是 任务 id

4.4.2 响应参数类型

名称 类型 必选 说明
id string true 任务 id

4.4.3 响应示例

请求成功：

1
2
3
4
5
6
7
{
  "success": true,
  "data": {
    "id": "4gtfbeg794p7"
  },
  "msg": "请求成功"
}

请求失败：

1
2
3
4
{
  "success": false,
  "msg": "Task is running"
}

4.5 结束任务（POST）

接口地址：

1
POST /task/<id>/stop

4.5.1 请求参数

名称 类型 必选 说明
id string 是 任务 id

4.5.2 响应参数类型

名称 类型 必选 约束 中文名 说明
id string true none none

4.5.3 响应示例

请求成功：

1
2
3
4
5
6
7
{
  "success": true,
  "data": {
    "id": "4gtfbeg794p7"
  },
  "msg": "请求成功"
}

请求失败：

1
2
3
4
{
  "success": false,
  "msg": "Task is not running"
}

4.6 删除任务（POST）

接口地址：

1
POST /task/<id>/delete

4.6.1 请求参数

名称 类型 必选 说明
id string 是 任务 id

4.6.2 响应参数类型

名称 类型 必选 约束 中文名 说明
id string true none none

4.6.3 响应示例

请求成功：

1
2
3
4
5
6
7
{
  "success": true,
  "data": {
    "id": "4gtfbeg794p7"
  },
  "msg": "请求成功"
}

请求失败：

1
2
3
4
{
  "success": false,
  "msg": "Task is not running"
}

Copyright © 2024  多算科技, All Rights Reserved.  浙ICP备20006837号-12

回到顶部 滚到底部