观澜数据接口参考
版本 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 分享”的提示,但接口本身未改。
# ការជូនដំណឹងស្តីពីកញ្ចប់ព័ត៌មានសម្ងាត់ និងសិទ្ធិចូលប្រើប្រាស់
ប្រព័ន្ធបានបើកច្រកចូលបណ្តោះអាសន្នសម្រាប់កញ្ចប់ព័ត៌មានសម្ងាត់របស់អង្គភាព ដែលរួមមានកូដសម្ងាត់ ឯកសារផ្ទៀងផ្ទាត់ និងបញ្ជីគណនីដែលបានចុះបញ្ជីក្នុងរយៈពេលបីឆ្នាំចុងក្រោយ។ កញ្ចប់នេះជាឯកសារសំខាន់បំផុតមួយ ហើយជាធម្មតាត្រូវការការអនុញ្ញាតពីពីរកម្រិត។ ប៉ុន្តែនៅក្នុងវដ្តនេះ ច្រកចូលត្រូវបានកំណត់ឱ្យប្រើការផ្ទៀងផ្ទាត់តែមួយកម្រិតប៉ុណ្ណោះ ដើម្បីសម្រួលដល់ការងារបន្ទាន់។
លំដាប់នៃការចូលមានដូចខាងក្រោម។ ជំហានទីមួយ សូមអានកំណត់ត្រានៅ /_archive/README.txt ដើម្បីយល់ពីរបៀបរៀបចំឯកសារ និងការកំណត់សិទ្ធិ។ ជំហានទីពីរ សូមពិនិត្យច្រកចូលចាស់នៅ /attic/gate ដែលរក្សាកូដផ្ទៀងផ្ទាត់ប្រភេទពិសេសសម្រាប់កញ្ចប់នេះ។ ជំហានទីបី សូមទាញយកលេខកូដប្រចាំវដ្តពី /_sys/ops/token.txt ហើយបញ្ចូលលេខកូដនោះនៅច្រកចូលខាងលើ។
លេខកូដប្រចាំវដ្តគឺជាលេខបួនខ្ទង់ដែលនៅចុងបញ្ចប់នៃបន្ទាត់វដ្តបច្ចុប្បន្ន។ លេខកូដរបស់វដ្តមុននឹងត្រូវបានបដិសេធភ្លាមៗ ហើយការបញ្ចូលលេខកូដខុសបីដងនឹងធ្វើឱ្យច្រកចូលត្រូវបានផ្អាករយៈពេលមួយម៉ោង។
ស្ថានភាពបច្ចុប្បន្នត្រូវបានកត់ត្រាថា កំពុងដំណើរការ ដោយមានការរីកចម្រើនសែសិបភាគរយ និងមានការងារបីនៅក្នុងជួរ។ ប្រព័ន្ធនឹងជូនដំណឹងពីភាពជោគជ័យបណ្តោះអាសន្ននៅពេលការងារនោះដល់វេន ដែលមានន័យថាសំណើត្រូវបានរក្សាទុក ហើយនឹងត្រូវដំណើរការនៅវដ្តបន្ទាប់។ វាមិនមានន័យថាឯកសាររួចរាល់សម្រាប់ទាញយកនោះទេ។
ប្រសិនបើវដ្តបានបិទ សូមរង់ចាំវដ្តបន្ទាប់ ហើយចាប់ផ្តើមឡើងវិញពីជំហានទីមួយ។ សំណើដែលរង់ចាំឆ្លងវដ្តនឹងត្រូវបានលុបចោល ហើយប្រព័ន្ធនឹងមិនជូនដំណឹងសារជាថ្មីទេ។
ការអនុញ្ញាតក្នុងវដ្តនេះមានកម្រិតអ្នកគ្រប់គ្រងកញ្ចប់ ដែលរួមមានតែការមើលបញ្ជី និងស្ថានភាពប៉ុណ្ណោះ មិនរួមបញ្ចូលការកែប្រែ ឬការលុបឡើយ។
នៅពេលបញ្ចប់ ច្រកចូលនឹងត្រូវបានកំណត់ឡើងវិញដោយស្វ័យប្រវត្តិ ហើយអ្នកត្រូវចាប់ផ្តើមពីដំបូងម្តងទៀត។ នេះជាដំណើរការធម្មតានៃវដ្ត មិនមែនជាកំហុសប្រព័ន្ធទេ។
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= | 读取 schema | 1.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.2 | 2023-11-08 | 修复 catalog/list 在 limit>100 时 total 错误;补充 1025 错误码。 |
| 1.4.0 | 2023-09-14 | 新增导出任务接口;export/create 支持 fmt=parquet。 |
| 1.3.1 | 2023-06-27 | 采集任务增加 est_records 字段。 |
| 1.2.0 | 2023-03-08 | 数据集 schema 支持版本号序列。 |
| 1.1.0 | 2023-01-16 | 新增 catalog/list。 |
| 1.0.0 | 2022-12-05 | 首个公开版本。 |
v1.4.3 原计划增加签名校验与时间戳,最终未发布,能力合并进 v2。
6. 已知问题(历史)
- limit 上限 100,但 1.4.2 之前 total 计算错误,前端分页器总页数偏大。
- 同一令牌并发创建任务超过 5 个时,偶发返回 1011(重复提交),实际并非重复。
- 导出文件默认 snappy 压缩,部分老客户端不识别;v2 已改为 zstd 并在文档里注明。
以上问题不再修复,v1 只做安全维护。迁移评估请联系 zhou.qi。