清洁数据

V1 列出机器人任务报告

GET /v1alpha1/robots/{robotSerialNumber}/taskReports

分页查询指定机器人的任务报告列表，支持按 UTC 时间范围筛选。路径参数 robotSerialNumber 为机器人序列号。

请求参数 (Query)

响应参数

// 请求示例
GET /v1alpha1/robots/GS101-00A0-A7L-0000/taskReports?page=1&pageSize=10&startTimeUtcFloor=2026-01-01T00:00:00Z&startTimeUtcUpper=2026-01-31T23:59:59Z

// 响应示例
{
  "robotTaskReports": [
    {
      "id": "rpt-001",
      "displayName": "日常清洁任务",
      "completionPercentage": 95.5,
      "durationSeconds": 3600,
      "actualCleaningAreaSquareMeter": 120.0,
      "startBatteryPercentage": 100,
      "endBatteryPercentage": 45
    }
  ],
  "page": 1,
  "total": "1"
}

V2 列出机器人任务报告

GET /openapi/v2alpha1/robots/{robotSerialNumber}/taskReports

V2 版本在 V1 基础上进行了增强，额外支持 subTasks 子任务列表，响应中增加 taskReportPngUri 报告图片链接字段。路径参数 robotSerialNumber 为机器人序列号。

请求参数 (Query)

响应参数

// 请求示例
GET /openapi/v2alpha1/robots/GS101-00A0-A7L-0000/taskReports?page=1&pageSize=10

// 响应示例
{
  "robotTaskReports": [
    {
      "id": "rpt-001",
      "displayName": "日常清洁任务",
      "completionPercentage": 95.5,
      "durationSeconds": 3600,
      "actualCleaningAreaSquareMeter": 120.0,
      "startBatteryPercentage": 100,
      "endBatteryPercentage": 45,
      "subTasks": [],
      "taskReportPngUri": "https://openapi.gs-robot.com/reports/rpt-001.png"
    }
  ],
  "page": 1,
  "total": "1"
}

生成机器人任务报告 PNG

POST /v1alpha1/robots/{robotId}/taskReports/{reportId}:generateRobotTaskReportPng

为指定机器人的指定任务报告生成 PNG 格式的可视化图片。路径参数 robotId 为机器人 ID，reportId 为任务报告 ID。

请求参数 (Body)

响应参数

// 请求示例
POST /v1alpha1/robots/robot-123/taskReports/rpt-001:generateRobotTaskReportPng
Content-Type: application/json

{
  "languageCode": "zh"
}

// 响应示例
{
  "uri": "https://openapi.gs-robot.com/reports/rpt-001-zh.png"
}

SDK 使用示例

通过高仙开放平台 Python SDK 调用清洁数据服务：

async with GausiumSDK(client_id, client_secret, open_access_key) as sdk:
    # V1 列出任务报告
    reports = await sdk.cleaning.list_task_reports(
        robot_sn="GS101-00A0-A7L-0000",
        page=1,
        page_size=10
    )

    # V2 列出任务报告（含子任务和 PNG 链接）
    reports_v2 = await sdk.cleaning.list_task_reports_v2(
        robot_sn="GS101-00A0-A7L-0000",
        page=1,
        page_size=10
    )

    # 生成任务报告 PNG
    png = await sdk.cleaning.generate_report_png(
        robot_id="robot-123",
        report_id="rpt-001",
        language_code="zh"
    )
    print(png.uri)