> For the complete documentation index, see [llms.txt](https://resources.atriptech.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://resources.atriptech.com/api-wen-dang/product-guides/booking/booking-overview/l2b-yun-xing-ji-zhi-yu-ke-hu-xiang-ying-zhi-nan.md). # L2B 运行机制与客户响应指南 Atlas Look-to-Book（L2B）当前运行机制、控制结果、响应头和状态通知。 Atlas 使用 Look-to-Book（L2B）管理低效、重复或持续超限的航司请求。 系统会提前预警并持续观察。只有确认持续超限后才会进入控制。 L2B 按“客户 + 航司 + API Action”独立评估。 {% hint style="info" %} **请求兼容性**：本次升级不改变现有请求参数或调用顺序。 Atlas 会在受影响接口的响应头中增加 L2B 信息。客户端应忽略未识别的新增字段。 {% endhint %} ### 当前运行模型 系统在滑动窗口内计算有效 L2B： ``` 当前 L2B = N / (D + K) 允许请求额度 = T × (D + K) 使用率 = 当前 L2B / T × 100% ``` `N` 是符合统计口径的实时请求数。`D` 是支付成功订单数。`K` 是基础保护额度。 规则使用配置的窗口 `W` 和上限 `T`。系统通常每 5 分钟评估一次。 当前策略状态为 `NORMAL`、`WARNING` 和 `CONTROL`。 * 使用率达到 80% 时进入 `WARNING`。 * 持续达到 100% 并通过确认后进入 `CONTROL`。 * 使用率持续低于释放线后退出 `CONTROL`。 `ORDER` 参与观察和通知，但 `order.do` 不会被 L2B 降级或拒绝。 ### 控制结果与响应头 `CONTROL` 是策略状态，不会直接出现在响应头中。 受控的非 `ORDER` 请求不会实时发送至航司。Atlas 会返回以下实际结果： | `x-l2b-state` | 含义 | | ------------- | -------------- | | `NORMAL` | 本次请求未受 L2B 控制 | | `WARNING` | 请求仍实时执行 | | `DEGRADED` | 返回可用的非实时降级结果 | | `REJECTED` | 没有可用降级结果，请求被拒绝 | 每次请求都应读取以下响应头： ```http x-l2b-current x-l2b-limit x-l2b-window-minutes x-l2b-state ``` 当数值响应头均为 `unknown` 时，请求会正常放行。 这不代表系统已确认该维度的 L2B 正常。 无法提供降级结果时，Atlas 返回错误码 `907`。 ``` Request rejected by L2B control because no degraded result is available. ``` 状态变化通过 Webhook、邮件或钉钉发送。Webhook 为尽力投递。 请使用 [L2B 状态变更通知](/api-wen-dang/product-guides/extensions-and-integrations/webhook-overview/l2b-zhuang-tai-bian-geng-tong-zhi.md) 对接 Webhook，并以响应头作为实时依据。 ### 适用范围 L2B 按以下维度独立观察和决策： ``` 客户（Client）+ 航司（Carrier）+ API Action ``` 一个维度的状态不会影响其他航司或 Action。 | Action | 对应业务 | | ----------------- | ---------------------------------- | | `VERIFY` | 验价（`verify.do`） | | `GET_OFFERS` | 获取 Offer（`getOffers.do`） | | `GET_OFFER_PRICE` | 获取 Offer Price（`getOfferPrice.do`） | | `GET_SEAT` | 获取座位（`seatAvailability.do`） | | `GET_LUGGAGE` | 获取行李（`getLuggage.do`） | | `ORDER` | 下单（`order.do`），仅观察和告警 | 具体客户、航司和 Action 是否启用在线控制，以当前生效配置为准。 {% hint style="info" %} `ORDER` 会计算 L2B 并发送状态通知。 即使进入 `CONTROL`，`order.do` 仍按正常流程处理。它不会被降级或拒绝。 {% endhint %} ### L2B 如何计算 每条规则使用持续前移的滑动窗口 `W`。当前支持 6、12、24 或 48 小时。 系统通常每 5 分钟重新评估最近 `W` 时间范围内的数据。 * `N`：符合统计口径的成功实时 API 请求数。 * `D`：该客户在该航司的支付成功订单数。 * `K`：基础保护额度，避免低数据量场景过早触发控制。 控制期间被降级或拒绝的请求不会计入 `N`。 ``` 当前 L2B = N / (D + K) 允许请求额度 = T × (D + K) 使用率 = 当前 L2B / T × 100% ``` `T` 是该规则配置的 L2B 上限。`K` 不代表真实支付订单。 例如，`W` 为 24 小时、`T` 为 80、`D` 为 3、`K` 为 2、`N` 为 320： ``` 当前 L2B = 320 / (3 + 2) = 64 允许请求额度 = 80 × (3 + 2) = 400 使用率 = 320 / 400 = 80% ``` 此时系统进入 `WARNING`，但仍会实时请求航司。 ### 状态与转换规则 | 策略状态 | 含义 | 是否实时请求航司 | | --------- | ------- | ---------------------- | | `NORMAL` | 使用率正常 | 是 | | `WARNING` | 接近或达到上限 | 是 | | `CONTROL` | 已确认持续超限 | 除 `ORDER` 外，按接口能力降级或拒绝 | #### 状态转换图 ``` NORMAL │ 使用率达到 80% ▼ WARNING │ 使用率持续达到 100%，并完成确认 ▼ CONTROL │ 使用率持续低于释放线，通常为 90% ▼ WARNING │ 使用率持续低于 70% ▼ NORMAL ``` 当前策略在使用率达到 80% 时进入 `WARNING`。持续达到 100% 并完成确认后进入 `CONTROL`。 使用率持续低于释放线时，`CONTROL` 返回 `WARNING`。通常低于 90% 时开始释放判断。 `WARNING` 持续低于 70% 后返回 `NORMAL`。状态变更需要持续确认，避免短暂波动频繁切换。 实际使用的上限 `T`、窗口 `W` 和状态，以响应头、通知和生效规则为准。 ### CONTROL 对请求的影响 `CONTROL` 是策略状态。受控的非 `ORDER` 请求不会实时发送给航司。 Atlas 根据每个接口的能力，返回以下处理结果： | `x-l2b-state` | 含义 | | ------------- | -------------- | | `DEGRADED` | 返回可用的非实时降级结果 | | `REJECTED` | 没有可用降级结果，请求被拒绝 | `DEGRADED` 结果可能来自缓存。它不是实时航司结果，价格、库存或可售性可能已变化。 `REJECTED` 返回业务错误码 `907`： ``` Request rejected by L2B control because no degraded result is available. ``` 对 `907` 使用带退避的有限重试。不要立即进行高频重试。 通知中的 `CONTROL` 表示策略状态。响应头中的 `DEGRADED` 和 `REJECTED` 表示单次请求的实际结果。 ### API 响应头 | 响应头 | 含义 | 示例 | | ---------------------- | ----------- | ---------------------------------------- | | `x-l2b-current` | 当前窗口的有效 L2B | `83.25` | | `x-l2b-limit` | 当前规则上限 `T` | `80` | | `x-l2b-window-minutes` | 观察窗口，单位分钟 | `1440` | | `x-l2b-state` | 本次请求状态或处理结果 | `NORMAL`、`WARNING`、`DEGRADED`、`REJECTED` | 没有有效决策时，Atlas 按正常流程放行： ```http x-l2b-current: unknown x-l2b-limit: unknown x-l2b-window-minutes: unknown x-l2b-state: NORMAL ``` 这表示本次请求未受控制，不表示该维度已完成有效评估。 如果客户、航司或 Action 无法识别，Atlas 不会返回 L2B 响应头。请求仍会正常处理。 客户端应同时检查业务响应和 `x-l2b-state`，而非只判断 HTTP 状态。 ### 状态变化通知 Atlas 在以下策略状态变化时发送 Webhook、邮件或钉钉通知： | 状态变化 | 客户应关注的内容 | | ------------------- | ------------ | | `NORMAL → WARNING` | 使用率接近上限 | | `WARNING → CONTROL` | 实时航司请求开始受控 | | `CONTROL → WARNING` | 控制已解除，但使用率仍高 | | `WARNING → NORMAL` | L2B 已恢复正常 | 通知至少包含航司、Action、当前 L2B、上限、使用率、状态、窗口和评估时间。 Webhook 为尽力投递。它不能作为实时状态的唯一依据。 请以每次 API 响应中的 `x-l2b-current`、`x-l2b-limit`、`x-l2b-window-minutes` 和 `x-l2b-state` 为准。 ### 客户响应建议 #### 收到 WARNING API 仍实时请求航司。检查重复调用、无效轮询和未设置退避的自动重试。 优先复用仍有效的 Offer、Session 或查询结果。 #### 收到 CONTROL 记录 `DEGRADED` 和 `REJECTED` 响应。将 `DEGRADED` 视为非实时结果。 对错误码 `907` 使用退避策略。排查重复验价、重复获取 Offer 和异常重试来源。 若 `ORDER` 进入 `CONTROL`，该通知仅表示用量告警。订单请求不受影响。 #### CONTROL 恢复为 WARNING 实时航司请求已恢复。请逐步恢复流量，避免立即释放全部积压请求。 #### WARNING 恢复为 NORMAL 可以正常调用 API。请继续保留请求去重、缓存复用和退避重试机制。 ### Webhook 接收要求 | 项目 | 约定 | | ------------ | --------------------------------- | | HTTP 方法 | `POST` | | Content-Type | `application/json; charset=UTF-8` | | 成功响应 | 精确的 HTTP `200 OK` | | 幂等键 | `notificationId` | 使用 `notificationId` 去重，并按 `clientCode + carrier + action` 保存状态。 使用 `windowEnd` 判断事件新旧。较早事件不得覆盖较新状态。 接收端应兼容未知新增字段。先可靠入队或持久化，再返回 `200`。 有关事件字段，请参阅 [L2B 状态变更通知](/api-wen-dang/product-guides/extensions-and-integrations/webhook-overview/l2b-zhuang-tai-bian-geng-tong-zhi.md)。 ### 常见问题 #### 为什么达到 100% 后不会立刻进入 CONTROL？ 系统要求持续超限并完成确认。单次短暂高峰不会直接触发控制。 #### 为什么支付订单增加后没有立即恢复？ 系统使用滑动窗口，并要求持续满足释放条件。状态会在后续评估周期更新。 #### 为什么通知显示 CONTROL，响应头显示 DEGRADED？ `CONTROL` 是策略状态。`DEGRADED` 是本次请求获得非实时结果的处理结果。 #### 没有收到通知，是否代表没有被控制？ 不代表。通知是辅助渠道。请始终使用 API 响应头判断当前请求的实时状态。 ### 使用边界 * L2B 是 API 请求与支付转化关系的管理指标。 * 不同客户、航司和 Action 独立计算。 * 降级结果不是实时航司结果。 * 状态变化存在正常统计和确认周期。