观澜 v1 → v2 迁移指引

DOC-GL-MIG-2X · 面向已接入 v1 的租户与内部调用方 · 修订 2026-01-06 · 维护 zhou.qi / xu.mo
1 冻结通告2 双跑3 切换4 下线检查
冻结通告:v1 已于 2025-12-31 冻结,不再接受功能变更;查询串令牌(?token=)已于 2026-01-15 关闭。全部 v1 写接口计划在 2026-12-31 停用,只保留只读查询。仍未迁移的调用方请按本页第 3 节登记。

1. 变更总览

项v1(2023–2025)v2(2.5+)影响
认证查询串 ?token=glk_... 或 Authorization: Bearer三头签名:X-GL-Key / X-GL-Ts / X-GL-Sign必须改代码
路径前缀/api/v1/*/v2/*机械替换
响应信封{"code":0,"data":{...}}直接返回资源对象 + HTTP 状态码解析逻辑需调整
分页offset/limit不透明游标 cursor(2h 有效)需改循环
时间格式yyyy-MM-dd HH:mm:ss(无时区)RFC 3339 带偏移低
错误码GL-E-1001 起,含义部分不同沿用编号区间,新增 1044/1052/1060对照 §4
数据集 ID数字内部 ID字符串 slug(camera-calib-2026q3)需映射表

2. 认证改造示例

# v1(已停用,勿再使用)
POST /api/v1/collect/create?token=glk_live_xxxxxxxx
{"dataset_id": 10044, "source": {...}}

# v2 伪代码
ts = str(int(time.time()))
body = json.dumps(payload, separators=(",", ":"), ensure_ascii=False)
canonical = "POST\n/v2/collect/jobs\n" + ts + "\n" + sha256_hex(body)
sign = hmac_sha256(tenant_secret, canonical)     # 小写 hex
headers = {
  "X-GL-Key": tenant_key,
  "X-GL-Ts": ts,
  "X-GL-Sign": sign,
  "Idempotency-Key": str(uuid.uuid4()),
  "Content-Type": "application/json",
}
注意:签名串里的 path 必须与请求行完全一致,包含 /v2 前缀与查询串(若有)。v2 不接受 X-GL-Client 头,多传会被忽略而不报错,迁移时直接删掉。

3. 迁移登记与双跑

迁移分两个阶段:双跑期(最长 60 天)与切换期。双跑期建议 v1 只读、v2 读写,通过比对任务结果确认一致性;切换前需在内部工单登记,标签 guanlan-migrate。

  1. 登记调用方信息:系统名、负责人 handle、当前 v1 调用量、数据范围。
  2. 开通 v2 租户 Key 与配额(默认 60 QPS,如需更高走 配额申请)。
  3. 双跑比对:同一份源数据分别建任务,比对目标桶对象数与 checksum。差异率应低于 0.1%。
  4. 切换并观察 7 天;然后关闭 v1 调用。
阶段时间窗验收口径
登记T-14 天工单通过,Key 与配额就绪
双跑T-14 ~ T-3连续 3 天 checksum 一致率 ≥ 99.9%
切换T-1 天夜间旧调用量归零,错误率回落至基线
下线检查T+7 天v1 仅剩只读查询,无写调用

已完成迁移的调用方:星槎数据回灌(2026-02)、北辰智能图像标注回流(2026-03)、云雀数据清洗队列(2026-04)、内部实验追踪(2026-05)。名单中最后接入的 北辰 S3 兼容层 仍有 2 个字段使用 v1 语法,见兼容层笔记的“遗留差异”一节。

4. 错误码对照(易混淆项)

v1v2说明
GL-E-1001(token 无效)GL-E-1001(Key 无效)编号不变但检查对象变了;v2 无查询串令牌
GL-E-1006(参数缺失)GL-E-1060(schema 校验失败)v2 把字段级校验单独拆出
GL-E-1011(重复提交)GL-E-1013(幂等键冲突)由 Idempotency-Key 自动处理
无GL-E-1044(游标过期)新增;v2 分页游标 2h 失效
无GL-E-1052(限流)新增;v1 超限直接连接重置

5. 常见坑

6. 回退方案

2026-12-31 前若切换失败,可临时回退 v1 只读查询(写接口不回退)。回退需在工单注明原因,并在 3 个工作日内提交修正计划。2026 年内出现的两次回退均发生在自研脚本(实验追踪、清洗队列)上,原因分别是时间戳单位写错与游标未处理 GL-E-1044。

← 文档中心 v2 · API 参考 v2.6.3 · v1 归档参考