地图管理

V2 查询地图列表

GET /openapi/v1/map/robotMap/list

根据机器人序列号查询该机器人关联的所有地图信息，返回地图 ID、名称和版本号。

请求参数

响应参数

// 请求示例
GET /openapi/v1/map/robotMap/list
Content-Type: application/json

{
  "robotSn": "GS101-00A0-A7L-0000"
}

// 响应示例
{
  "code": 0,
  "data": [
    {
      "mapId": "map-001",
      "mapName": "一楼大厅",
      "mapVersion": "1.0.0"
    }
  ]
}

V2 查询地图分区

GET /openapi/v1/map/subareas/get

根据地图 ID 和机器人序列号查询该地图的分区信息，返回分区 ID 和名称列表。

请求参数

响应参数

// 请求示例
GET /openapi/v1/map/subareas/get
Content-Type: application/json

{
  "mapId": "map-001",
  "robotSn": "GS101-00A0-A7L-0000"
}

// 响应示例
{
  "code": 0,
  "data": {
    "subareas": [
      { "id": 1, "name": "A 区" },
      { "id": 2, "name": "B 区" }
    ]
  }
}

V1 获取地图下载地址

GET /v1alpha1/robots/{robotId}/maps/{mapId}

通过机器人 ID 和地图 ID 获取地图文件的带签名下载链接。该接口为 V1 版本，无需额外请求参数。

响应参数

// 请求示例
GET /v1alpha1/robots/robot-001/maps/map-001

// 响应示例
{
  "downloadUri": "https://oss.gs-robot.com/maps/map-001.tar.gz?sign=abc123&expires=1700000000"
}

V2 获取地图下载地址

GET /openapi/v2alpha1/robots/{robotId}/map

V2 版本的地图下载接口，支持通过 Query 参数指定地图 ID 和可选的地图版本号。

请求参数

响应参数

// 请求示例
GET /openapi/v2alpha1/robots/robot-001/map?mapId=map-001&mapVersion=1.0.0

// 响应示例
{
  "downloadUri": "https://oss.gs-robot.com/maps/map-001-v1.0.0.tar.gz"
}

V1 上传机器人地图

POST /v1alpha1/robots/{robotId}/maps/-:uploadRobotMap

向指定机器人上传地图文件，上传成功后返回上传记录 ID，可通过记录查询接口追踪上传状态。

请求参数

响应参数

// 请求示例
POST /v1alpha1/robots/robot-001/maps/-:uploadRobotMap
Content-Type: application/json

{
  "mapFile": "map-upload-20260604.tar.gz"
}

// 响应示例
{
  "recordId": "rec-abc-123"
}

V1 获取机器人记录

GET /v1alpha1/robots/{robotId}/records/{recordId}

查询指定机器人的操作记录状态，通常用于追踪地图上传等异步操作的执行进度。

响应参数

// 请求示例
GET /v1alpha1/robots/robot-001/records/rec-abc-123

// 响应示例
{
  "id": "rec-abc-123",
  "recordStatus": "AVAILABLE"
}

SDK 调用示例

通过 Gausium SDK 可以便捷地调用上述地图管理接口，以下为典型使用场景。

async with GausiumSDK(client_id, client_secret, open_access_key) as sdk:
    # 查询地图列表
    maps = await sdk.map.list(robot_sn="GS101-00A0-A7L-0000")

    # 查询地图分区
    subareas = await sdk.map.get_subareas(
        map_id="map-001",
        robot_sn="GS101-00A0-A7L-0000"
    )

    # 获取地图下载地址
    download = await sdk.map.get_download_url(
        robot_id="robot-001",
        map_id="map-001"
    )