数据下载任务

概述

下载任务将历史数据点数据导出为文件，存储在 S3（或兼容的对象存储）中。每个任务属于一个项目，但通过专用的端点命名空间进行管理。

• 基础路径: /api/v2/projects/{project_id}/data-download-tasks/
• 缓存: 任务列表按组织短暂缓存。

端点摘要

方法	路径	用途	备注
GET	/projects/{project_id}/data-download-tasks/	列出组织的下载任务	见列出任务。
POST	/projects/{project_id}/data-download-tasks/	创建新的下载任务	见创建任务。
DELETE	/projects/{project_id}/data-download-tasks/{task_id}/	删除任务	见删除任务。
GET	/projects/{project_id}/data-download-tasks/{task_id}/download/	获取预签名文件 URL	见获取下载 URL。

更新和部分更新操作返回 HTTP 405；下载任务除删除外不可变。

列出任务

GET /api/v2/projects/{project_id}/data-download-tasks/
Authorization: Bearer <token>

响应示例：

[
  {
    "id": 15,
    "name": "ColdRoom_3factors_20240201-20240203",
    "device_pk": 128,
    "factors": ["d-1000-abcd-01", "d-1000-abcd-02"],
    "start_time": 1706745600,
    "end_time": 1706918400,
    "format": "csv",
    "status": "pending",
    "file_path": "128/ColdRoom_3factors_20240201-20240203_ab12cd34.csv",
    "create_time": "2024-02-01T08:00:00Z"
  }
]

创建任务

POST /api/v2/projects/{project_id}/data-download-tasks/
Authorization: Bearer <token>
Content-Type: application/json

{
  "device_pk": 128,
  "factors": ["d-1000-abcd-01"],
  "start_time": 1706745600,
  "end_time": 1706918400,
  "format": "csv",
  "name": "可选的自定义名称"
}

验证规则

1. device_pk 必须存在且属于该组织。
2. start_time（和可选的 end_time）必须是 Unix 时间戳（秒）。
3. factors 应包含目标数据点的完整 agri_id 值；用于构建历史查询。
4. 如果省略 format，默认为 csv。
5. 如果缺少 name，后端将使用设备名称、数据点数量和时间范围生成一个。

后端工作流程

• 为历史存储构建时间范围过滤器。
• 生成安全的文件名和 UUID，存储在 file_path 中。
• 持久化任务，状态为 pending。
• 发布导出作业消息，以便异步工作程序收集数据并生成文件。
• 设置 status=pending；工作程序将状态更新为 completed 或 failed。

获取下载 URL

GET /api/v2/projects/{project_id}/data-download-tasks/{task_id}/download/
Authorization: Bearer <token>

• 要求 status=completed；否则返回 HTTP 400，错误信息为 {"error": "文件尚未生成完成"}。
• 生成有效的预签名 S3 URL，有效期 24 小时。
• 通过 head_object 验证对象存在；如果缺失则返回 404。

响应：

{
  "download_url": "https://bucket.s3.region.amazonaws.com/128/...&X-Amz-SignedHeaders=host"
}

删除任务

DELETE /api/v2/projects/{project_id}/data-download-tasks/{task_id}/
Authorization: Bearer <token>

删除任务记录。导出的文件不会自动从对象存储中删除；需要单独管理生命周期策略。

错误代码

状态	代码	描述
400	INVALID_TIME_RANGE | MISSING_DEVICE_ID	开始/结束时间无效或缺少必填字段
401	UNAUTHORIZED	缺少或无效的令牌
403	FORBIDDEN	调用者缺少 operator/manager 角色
404	DEVICE_NOT_FOUND | DOWNLOAD_TASK_NOT_FOUND	设备或任务不可访问
405	METHOD_NOT_ALLOWED	尝试更新任务
500	DOWNLOAD_LINK_FAILURE	生成预签名 URL 失败

操作说明

1. 去重: 导出队列使用任务 ID 防止重复作业。
2. 格式: 目前支持 CSV；添加新的导出格式时扩展 format 处理。
3. 字段映射: 后端使用字段名称丰富导出请求，使生成的文件具有可读的标题。
4. 生命周期: 如果导出文件较大或敏感，请实施 S3 生命周期规则，在保留期后使导出文件过期。
5. 状态轮询: 由于导出是异步的，轮询列表端点或监视 status 字段以了解何时可以下载。