观澜数据接口参考

版本 v1.4.2 · 发布 2023-11-08 · 文档编号 GL-API-1142 · 归属:观澜组 · 适用服务 guanlan-gateway 1.4.x
【归档提示】本页对应 v1 接口,查询串 token 认证已于 2026-01-15 停用;v1 写接口计划 2026-12-31 停用。现行文档见 观澜数据服务 API 参考 v2,迁移见 迁移指引。

1. 概述

观澜数据服务对外提供采集任务管理与数据集查询两类接口,统一入口为 guanlan.internal。v1 所有接口均以 /api/v1/ 开头,返回统一信封:

{"code": 0, "message": "ok", "data": { ... }}

其中 code=0 表示业务成功,非 0 时 message 给出可读描述。HTTP 状态码在 v1 中基本恒为 200(参数错误也是 200),客户端务必检查 code 字段。

2. 认证

在查询串上携带访问令牌:

POST /api/v1/collect/create?token=glk_live_xxxxxxxxxxxx
Content-Type: application/json

{"dataset_id": 10044, "src": "beichen-share", "dst": "xiran-prod", "fmt": "parquet"}
令牌由控制台“接入信息”页发放,有效期 180 天,不支持自动轮换。v1 不校验签名与时间戳。
已知问题:令牌泄露后只能在控制台手工吊销;2025 年 3 月曾有脚本把令牌写进分享链接的事件(工单 SEC-2025-0231),此后新增了“令牌不可出现在 URL 分享”的提示,但接口本身未改。

3. 接口列表

接口说明引入版本
POST /api/v1/collect/create创建采集任务1.0
GET /api/v1/collect/status?job= 查询任务状态1.0
GET /api/v1/catalog/list数据集列表,offset/limit 分页1.1
GET /api/v1/catalog/schema?dataset_id=读取 schema1.2
POST /api/v1/export/create创建导出(异步)1.3
GET /api/v1/export/list导出任务列表1.3

3.1 创建采集任务

{
  "code": 0,
  "message": "ok",
  "data": {
    "job_id": 88213,
    "state": "QUEUED",
    "est_records": 12000000
  }
}

v1 使用数字 job_id;状态为大写字符串 QUEUED/RUNNING/DONE/ERROR。v2 改为字符串 jobId 与小写状态,且取消接口独立。

3.2 数据集列表

GET /api/v1/catalog/list?offset=0&limit=50&token=...

{"code":0,"message":"ok","data":{"total":287,"items":[
  {"id":10044,"name":"相机标定数据集 2023Q3","owner":"shen.zy","records":8211903}
]}}

offset 分页在数据量增长后出现翻页重复与丢失问题(总数在不同页间变化),这是 v2 改用游标的原因之一,详见 v2 参考第 4 节。

4. 状态与错误码

code含义客户端处理
0成功—
1001令牌无效或过期重新申请令牌
1002令牌无权限联系数据集 owner
1006参数缺失或类型错误按文档检查字段
1010数据集不存在确认 dataset_id
1011重复提交(同参数 5 分钟内)幂等处理,忽略重复请求
1017存储配额不足清理旧导出或申请扩容
1025源端点不可达联系对方(北辰/云雀)确认共享端口

5. 变更记录

版本日期内容
1.4.22023-11-08修复 catalog/list 在 limit>100 时 total 错误;补充 1025 错误码。
1.4.02023-09-14新增导出任务接口;export/create 支持 fmt=parquet。
1.3.12023-06-27采集任务增加 est_records 字段。
1.2.02023-03-08数据集 schema 支持版本号序列。
1.1.02023-01-16新增 catalog/list。
1.0.02022-12-05首个公开版本。
v1.4.3 原计划增加签名校验与时间戳,最终未发布,能力合并进 v2。

6. 已知问题(历史)

以上问题不再修复,v1 只做安全维护。迁移评估请联系 zhou.qi。

GL-API-1142 · v1.4.2 · 2023-11-08 · Copyright © 2023 归藏研究所 · 归档只读