跳转到主要内容
试用验证的是数据。生产环境则要求集成在连接中断、博彩商静默或我们发布新版本时依然稳定。本页是接入真实流量之前需要逐项完成的清单,每一项都链接到对应的详细说明。

1. 状态:快照加实时流

  • 先连接 WebSocket,再拉取 REST 快照并合并。按键比较,changedAt 较新的一方胜出。
  • 以 oddsId 为键存储赔率。该键在 REST、WebSocket、历史与结算中完全一致,一份存储即可服务四处。
  • 登录时用 sportIds、tournamentIds 和 bookmakers 过滤到您实际交易的范围。数据流越小,处理越快,也越不容易触发背压。
  • 选定 receiveType。zstd 可将 odds 流量压到 JSON 的约五到六分之一,解码只需一行。
详见:核心概念、登录与过滤、压缩。

2. 重连与续传

  • 持久化 serverEpoch 以及每个频道最后处理的 entryId。
  • 重连时携带 serverEpoch 和 lastSeenId 登录,并等待 resume_complete。
  • 处理 snapshot_required:为所列频道重新拉取 REST 快照,清除其游标,继续消费。
  • 收到 reconnect 控制帧后立即重连。每次发布前我们都会发送该帧,不要等到连接被关闭。
  • 遇到关闭码 1006 和 1011 时短暂退避后重连。4002(背压)和 4003(连接数过多)是需要解决的问题,不应盲目重试。
上线前请各演练一次:断开几秒后无缺口续传;断开超过 resumeWindowMs 后以快照恢复。记录第二种情况的耗时,它就是您的最坏恢复时间。 详见:续传与重放、故障排查。

3. 博彩商数据过期

  • 在订阅 odds 的同时订阅 bookmakers 频道。
  • 按 fixtureId:bookmaker 组合保存 staleOdds,在使用价格之前先检查它。
  • 当其为 true 时,暂停该赛事上的该博彩商,或切换到其他博彩商。恢复为 false 后再继续。
  • 将它与 suspended、active、marketActive 区分开。后三者是博彩商自身的停盘,staleOdds 反映的是我们对该博彩商的可见性。
  • 博彩商整体故障会表现为每场赛事一条消息,而不是单独一条消息。
详见:可靠性与运维。

4. 速率限制与连接数

  • 赔率接口每个 apiKey 每秒 10 次请求,其余接口每分钟 200 次。
  • 读取 X-RateLimit-Remaining,遇到 429 时按 Retry-After 给出的时间退避。
  • 快照和回补用 REST,变更用实时流。循环轮询赔率是触发限流最常见的原因。
  • 每个 apiKey 组的并发 WebSocket 连接不超过 8 个。如需更多,请在设计前联系我们。
详见:速率限制、WebSocket 概览。

5. 监控

  • 跟踪传输延迟:您的接收时间减去消息的 ts。请先运行 NTP,否则 100 毫秒以下的读数意义不大。
  • 按博彩商跟踪观测延迟:changedAt − bookmakerChangedAt,并与 GET /bookmakers 中的 maxDelayLiveInSec 和 maxDelayPregameInSec 对照。
  • 对重连次数、snapshot_required 次数,以及每个博彩商被标记 staleOdds 的赛事占比设置告警。
  • 订阅状态页,获取故障与维护通知。
  • 如果延迟重要,请部署在靠近我们的位置:德国中部或美国东部。
详见:可靠性与运维、核心概念、延迟测量方法。

6. 变更与支持

  • 关注更新日志。标记为重大变更的条目需要您这边采取行动。
  • 忽略响应中的未知字段。任何一次发布都可能新增字段。
  • 用 X-API-Key 请求头而不是查询参数传递密钥,避免其出现在 URL 和日志中。
  • 向 contact@55-tech.com 报告问题时,请提供受影响的频道或接口、UTC 时间戳,以及您的 serverEpoch 和 entryId。

满足以下条件即可上线

  • 强制断线后能无缺口续传,长时间断线能通过快照恢复,且恢复耗时已经实测。
  • staleOdds 标记能自动停止该博彩商在该赛事上的交易,无需人工介入。
  • 遇到 429 时客户端会减速,而不是出错。
  • 您自己的监控面板能看到每个博彩商的传输延迟、观测延迟和过期占比。