如何使用API接口？

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

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

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

【温馨提示】GISBox 的 API 功能需要购买“企业版”套餐才能使用，如需使用，请点击“升级”按钮购买套餐。

1. 前置 URL

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

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

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

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

1http://192.168.31.122:42225

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

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

2. Auth 参数

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

示例如下：

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

3. 响应格式

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

4. 接口说明

4.1 查询任务信息（GET）

4.1.1 接口地址

task/<id>/info

4.1.2 请求参数

4.1.3 响应参数

4.1.4 响应示例

{
  "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": "请求成功"
}

4.2 查询任务列表（GET）

4.2.1 接口地址

task/list

4.2.2 请求参数

无

4.2.3 响应参数

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

4.2.4 响应示例

{
  "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": "请求成功"
}

4.3 新建任务（POST）

4.3.1 接口地址

task/create

4.3.2 请求参数

Body 类型：

application/json

4.3.2.1 请求参数

4.3.2.2 各类型任务的settings参数

（1）影像切片

（2）DWG切片（目前仅支持Windows）

（3）地形切片

（4）倾斜摄影切片

（5）通用模型切片 （GeneralModelSlicing）

（6）RVT模型切片（目前仅支持Windows）RvtModelSlicing

无

（7）IFC模型切片（IFC23DTiles）

无

（8）3DTiles转OSGB（Tiles2OsgbSlicing）

（9）点云切片（PointCloudSlicing）

（10）高斯泼溅切片（GaussianSplattingSlicing）

（11）高斯泼溅OPGS转3DTiles（GaussianSplattingPly2Glb3dTiles）

无

（12）I3S转OSGB（I3S2OSGB）

无

（13）S3M转OSGB（S3m2OsgbSlicing）

无

（14）3DTiles再处理（TilesOptimize）

（15）散列转紧凑（Hash2Compact）

无

（16）紧凑转散列（Compact2Hash）

无

4.4 开始/重试/继续任务（POST）

4.4.1 接口地址

/task/<id>/start

4.4.2 请求参数

body参数

4.4.3 响应参数

4.4.4 响应示例

{
  "success": true,
  "data": {
    "id": "4gtfbeg794p7"
  },
  "msg": "请求成功"
}

4.5 结束任务（POST）

4.5.1 接口地址

/task/<id>/stop

4.5.2 请求参数

4.5.3 响应参数

4.5.4 响应示例

{
  "success": true,
  "data": {
    "id": "4gtfbeg794p7"
  },
  "msg": "请求成功"
}

4.6 删除任务（POST）

4.6.1 接口地址

/task/<id>/stop

4.6.2 请求参数

4.6.3 响应参数

4.6.4 响应示例

{
  "success": true,
  "data": {
    "id": "4gtfbeg794p7"
  },
  "msg": "请求成功"
}