智能获取 (Auto)

您向 FourA 提供一个 URL 以及关于真实页面应包含内容的 validate 规则。FourA 会处理剩下的工作：它会遍历一个考虑成本的阶梯策略，在返回符合您规则的 response 的第一个层级停止，并按主机记录成功的方法，以便下次在同一站点的调用成本更低。

本指南说明了 auto 的底层原理、使用时机以及如何读取其 response。有关参数参考，请参阅 API Endpoints。

核心理念

大多数抓取设置要求您提前选择引擎。Single 速度最快，Proxy 增加轮换，Browser 处理 JavaScript。如果猜错了，就会浪费额度或被拦截。

Auto 改变了这一做法。您只需声明成功条件 (validate)，而不是方法。FourA 会逐步提升层级直到成功：

廉价探测 (single，直接来自 FourA 自有网络)
轮换 proxy single
Browser，带有 JavaScript，如遇站点质询则包含求解器
通过 proxy 的 Browser，用于最难的目标

一旦某个层级返回您的 validate 规则接受的 response，Auto 就会停止。

forceProxy 默认为 true，因此会跳过层级 1，目标永远不会看到 FourA 自己的地址。大多数调用随后会在层级 2 或重放的热会话上完成。当您知道目标对干净地址的处理优于轮换地址时，请设置 forceProxy: false，这样层级 1 就会恢复。

发送内容

最基本的要求是一个 URL 加上 validate 子字符串。如果没有 validate.data.accept，auto 无法区分真实页面与返回 HTTP 200 的质询插页，它可能会将质询作为成功返回。

curl -X POST https://eu.api.foura.ai/api/auto/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}}
  }'

可选设置(有关完整详细信息,请参阅endpoint参考):

returnSession (默认 true): 返回胜出的 { proxy, cookies, userAgent } 以便您重放它。
forceProxy (默认 true): 跳过直连层。仅当您知道该站点对干净 IP 比对免费轮换 proxy 更友好时,才设置 false。
timeout_ms (默认 120000): 整个调用的总预算。阶梯策略会将其分配到各个层。
ignoreProxies: 在每次子尝试中要避免使用的 proxy ID。
followRedirects (默认 5): 在低成本层上的最大重定向次数。

返回结果

{
  "status": 200,
  "data": "<!doctype html>...",
  "headers": [{"content-type": "text/html"}],
  "meta": {
    "rung": "cache",
    "solved": false,
    "attempts": 1,
    "credits": 2
  },
  "session": {
    "proxy": "A1B2C3",
    "cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
    "userAgent": "Mozilla/5.0..."
  }
}

需要读取的三项内容：

status 和 data：与底层引擎返回的结构相同。status 是目标的 HTTP 状态，而非您向 FourA 发起调用的传输状态。对于 single 和 proxy rung，headers 是逐跳(per-hop)数组。对于 browser rung，headers 是扁平对象。
meta：ladder 执行过程的追踪信息，存在于每个 response 中。meta.rung 标识返回该 response 的步骤，meta.attempts 记录子调用的重试次数，meta.solved 标记是否解除了 bot challenge，meta.credits 是该调用的总花费（与 X-FourA-Credits header 中的数值相同）。
session：成功破解该目标的 { proxy, cookies, userAgent } 三元组。使用它通过 /api/single/ 或 /api/browser/ 针对同一主机进行重放(replay)。

只要 ladder 运行，Auto 始终返回 HTTP 200，即使所有 rung 均失败也是如此。请读取 body 中的 status 和 error 来确认实际情况，而不要依赖传输状态码。/api/auto/ 返回非 200 状态码意味着 FourA 在 ladder 启动前就拒绝了该调用：401 表示 key 错误，400 表示 body 无效或目标私有，429 或 503 表示触发了 rate limit。

使用 Session 进行重放

在 Auto 返回 session 后，您可以直接进入 Single 或 Browser 访问同一主机上的后续页面。无需新的 ladder 攀爬，也无需新的 probe。

import requests

API = "https://eu.api.foura.ai"
KEY = "YOUR_API_KEY"
H = {"X-API-Key": KEY, "Content-Type": "application/json"}

# 1) First call: let auto figure it out.
r = requests.post(f"{API}/api/auto/", headers=H, json={
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}},
}).json()

session = r["session"]
proxy = session["proxy"]
user_agent = session["userAgent"]

# 2) Follow-up pages: replay through single with the same proxy + UA.
for sku in ("43", "44", "45"):
    r = requests.post(f"{API}/api/single/", headers=H, json={
        "method": "GET",
        "url": f"https://example.com/product/{sku}",
        "proxy": proxy,
        "headers": [["User-Agent", user_agent]],
    }).json()
    print(sku, r["status"])

会话的持久性完全取决于目标站点。有些网站将通行凭证绑定在 cookie jar 中长达数小时；而有些网站每几分钟就会轮换一次。如果重放请求再次开始返回质询(challenge)，请再次调用 /api/auto/ 进行刷新。

何时使用 Auto

使用 Auto	手动使用 Single、Proxy 或 Browser
面向新目标站点且未知其需求	已经知道哪个引擎有效
希望通过一次调用自动处理 direct、proxy 和 browser 降级(fallback)	希望完全控制每次调用的重试和超时
可以接受首次调用有几秒钟的探测时间	首次调用的延迟比探索阶段更重要
希望获得可低成本重放的学习会话(learned session)	正在针对已知有效的目标优化紧密循环(tight loop)

Auto 并不总是最便宜的选择。如果您知道某个目标使用 single + unblocker 即可成功，那么直接调用 Single 只需 2 个点数(credits)，且延迟可预测。在同一目标上使用 Auto 会消耗其执行阶梯(ladder)所花费的全部成本，如果站点需要升级策略，这可能会花费更多。

Validate 告诉 Auto 什么是“成功”

最重要的单一参数是 validate。如果没有它，Auto 无法区分真正的 200 页面和伪装成内容的 200 质询插页(challenge interstitial)。

将 validate.data.accept 与仅真实页面包含的子字符串结合使用：

{
  "validate": {
    "data": {
      "accept": ["sku-42-add-to-cart", "Customer reviews"]
    }
  }
}

对于 JSON API，请接受您预期的字段名称：

{
  "validate": {
    "data": { "accept": ["\"products\":["] },
    "status": { "accept": [200] }
  }
}

对于合理返回非 200 状态码的站点（您希望忽略的地理封锁、未登录 endpoint 上的有意 403），请通过 validate.status.accept 允许它们：

{
  "validate": {
    "status": { "accept": [200, 451] }
  }
}

如果没有 validate，auto 将回退到 "HTTP 200 = success"，并且无法捕获 WAF 返回 200 状态码的 Cloudflare 质询插页。

读取 `meta.rung` 以了解执行情况

meta.rung 是最有用的调试信号。有效值：

probe - 通过廉价的 direct request 解决。成本最低的路径。
proxy - 需要 proxy 轮换才能通过。
browser - 需要完整的浏览器渲染，可能包含质询求解。
cache - 从之前的 auto 调用中重放了预热会话。重复调用时成本最低的路径。
fail - 没有层级能生成被您的规则接受的 response。

meta.solved: true 表示在调用期间检测到并清除了机器人质询。meta.attempts 是成功前子调用尝试的次数。有关求解背后的供应商详情，请读取 single 和 proxy 层级返回的 defense 字段：参阅反机器人防御。

如果网站一直以 browser 结束而您期望的是 probe，请考虑更严格的 validate 规则（或不那么严格的规则）是否能让成本更低的层级通过。请记住 forceProxy 默认为 true，因此除非将其关闭，否则将跳过 direct-egress 探测。

错误与边缘情况

当 auto 失败时，response 会携带 status（通常是最后一个失败层级的状态）和 error 字符串：

{
  "status": 0,
  "error": "all attempts failed",
  "attempts": 7,
  "meta": {
    "rung": "fail",
    "solved": false,
    "attempts": 7,
    "credits": 47
  }
}

status: 0 意味着没有任何层级产生响应（所有尝试均已超时或被拒绝）。非零的 status 加上 error 意味着最后一次尝试得到了响应，但被 auto 拒绝（验证或其他原因）。

检查 meta.attempts 和 meta.credits 以查看预算去向。如果 meta.attempts 很高，且在 browser 层级之后 meta.rung 为 fail，则目标可能需要更长的 timeout_ms，更严格的 validate 规则，或者目前根本无法通过旋转 proxy 访问。

Auto 不做的事情

不会绕过法律限制。如果网站有地理封锁并拒绝 FourA 能访问的所有出口，auto 将返回该封锁。
不会缓存内容。每次调用仍会到达目标。“预热会话”指的是 proxy 和 cookie，而不是 response。
不会作为独立于子调用的行写入 Activity Log。代表您自动发起的 Single / Proxy / Browser 子调用会显示在活动日志中；外部的 /api/auto/ 调用是一个协调器。