智能获取 (Auto)

你向 FourA 提供一个 URL 和一条关于真实页面应包含内容的 validate 规则。其余工作由 FourA 完成:它按成本效益阶梯逐步尝试,停在首个返回满足你规则的响应阶梯上,并按主机记录有效策略,使同一站点的下一次调用成本更低。

本指南介绍 auto 的底层运行机制、适用场景以及如何解析其响应。有关参数参考,请参阅 API Endpoints。

核心概念

大多数抓取方案要求你预先指定引擎。Single 最快,Proxy 提供轮换,Browser 负责处理 JavaScript。一旦预判错误,就会浪费积分或遭遇拦截。

Auto 改变了这种模式。你只需定义成功标准(validate),无需指定实现方式。FourA 依次尝试不同阶梯,直到某一阶梯成功:

  1. 低成本探测(single,直接来自 FourA 自有网络)
  2. Browser,直接来自 FourA 自有网络,支持 JavaScript,并在站点发起质询时调用求解器
  3. 轮换 proxy single
  4. 通过 proxy 运行 Browser,用于处理最严格的目标

一旦某个阶梯返回符合你 validate 规则的响应,Auto 就会立即停止。

还有一个阶梯独立于该顺序之外。当某个出口成功连接站点但站点拒绝你请求的深层 URL 时,auto 会通过同一出口抓取站点的入口页面,保留入口页面分配的 cookie,并携带这些 cookie 再次请求你的目标 URL。这就是 warmup 阶梯。它仅在 URL 深于站点根目录且直接尝试已失败时触发,并且只会增加成功机会,绝不会导致现有结果失效。

forceProxy 默认为 true,因此阶梯 1 和 2 会被跳过,目标站点永远不会看到 FourA 的自有地址。多数调用随后会在阶梯 3 完成,或通过重放已建立的预热会话完成。当你明确知道目标站点对纯净地址的接纳度优于轮换地址时,可设置 forceProxy: false,阶梯 1 和 2 便会重新启用。

请求参数

最基本的要求是提供一个 URL 以及一个 validate 子字符串。Auto 本身能识别常见的质询页面,但如果没有 validate.data.accept,它无法区分真实页面与未知的校验页面,也无法识别未加载目标内容的页面,并可能将两者误判为成功。

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 比对轮换出口更友好时,才设为 false。
  • timeout_ms(默认 120000):整个调用的总预算时间。阶梯策略会将其分配到各个阶段。
  • ignoreProxies:在每次子尝试中需避开的 proxy ID。
  • followRedirects(默认 5):低成本阶梯上的最大重定向次数。
  • headers:发送给站点的 headers,格式为 [name, value] 键值对。它们会在 Single 和 Proxy request 中发出(包括寻找有效出口的过程),浏览器阶梯则不会发送。您自带的 Cookie 会原样传达至站点,预热 session 的 cookies 仅会在您未发送同名 cookie 时补充添加。当预热 session 包含 userAgent 时,它会替换您的 User-Agent。诸如 If-None-Match 和 If-Modified-Since 等条件 header 在出口搜索阶段会被忽略,除非您的 validate.status.accept 包含 304。
  • exitClass:premium 允许 Auto 在标准池无法访问页面时升级至高级出口;standard 则表示绝不升级。需要包含高级出口的套餐支持。请参阅 Smart Fetch 中的 exitClass。

返回结果

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

需要阅读的三个部分:

  • status 与 data:目标的响应内容。无论由哪一阶梯层提供页面,data 均为文本,因此 JSON 页面会以 JSON 文本形式返回,需自行解析。status 是目标的 HTTP 状态码,而非调用 FourA 的传输层状态。对于 single 和 proxy 阶梯层,headers 是逐跳数组。对于 browser 阶梯层,headers 是扁平对象。
  • meta:阶梯运行追踪信息,阶梯启动后的每个响应中都会包含。meta.rung 指明交付响应的步骤,meta.attempts 统计子调用重试次数,meta.solved 标记是否完成了验证页面,meta.credits 是该次调用的总消耗(与 X-FourA-Credits 响应头数值相同)。meta.attemptsByEngine 与 meta.browserRequests 说明了该调用消耗的项目:参见 调用消耗说明。当请求指定了 exitClass 时,meta.exitClass 会指明实际交付的出口类别。
  • session:成功破解目标的 { proxy, cookies, userAgent } 三元组。可用于通过 /api/single/ 或 /api/browser/ 对同一主机重放请求。字段可能会缺失:通过普通 proxy 抓取获得的会话包含 proxy 但没有 userAgent,且其 cookies 列表仅包含站点在提供页面前由验证页设置的 cookie,因此通常为空。仅当此类验证页设置了 cookie 时,来自低成本 direct 探测的响应才会携带 session,且此时仅包含 cookies。由出口返回且属于 validate.status.accept 列表中的状态码(例如已删除页面的 404)完全不会包含 session。

只要阶梯运行过,即使所有阶梯层均失败,Auto 也会返回 HTTP 200。请查看响应体中的 status 和 error 以获取实际执行情况,而不是查看传输层状态码。/api/auto/ 返回非 200 意味着调用根本未到达阶梯:401 表示密钥无效;400 表示请求体不是合法 JSON、目标处于专用网络、目标属于 FourA 自身的 API 主机,或 URL 中包含未编码的空格;403 带有 X-FourA-Limit: plan_limit_premium 表示套餐不支持高级出口却使用了 exitClass: premium;502、503 或 504 表示服务无法接收调用或已超时。Auto 在网关处不占用槽位,因此平台的共享限制不会拒绝调用本身:当共享限制拒绝阶梯发起的调用时,响应为 HTTP 200,且响应体中包含 status: 429 或 503 以及 retryAfter。验证失败的字段也会以 HTTP 200 返回,并带有 status: 400。在阶梯内部触发套餐限制同样返回 HTTP 200,拒绝原因包含在响应体中(参见 套餐限制与阶梯冲突说明)。

使用会话重放

Auto 返回会话后,针对同一主机的后续页面,可以直接进入 Single 或 Browser。无需重新爬升阶梯,无需重新探测。

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.get("session") or {}
proxy = session.get("proxy")
user_agent = session.get("userAgent")

# 2) Follow-up pages: replay through single with the same proxy, UA and cookies.
for sku in ("43", "44", "45"):
    body = {"method": "GET", "url": f"https://example.com/product/{sku}"}
    if proxy:
        body["proxy"] = proxy
    headers = []
    if user_agent:
        headers.append(["User-Agent", user_agent])
    if session.get("cookies"):
        headers.append(["Cookie", "; ".join(f"{c['name']}={c['value']}" for c in session["cookies"])])
    if headers:
        body["headers"] = headers
    r = requests.post(f"{API}/api/single/", headers=H, json=body).json()
    print(sku, r["status"])

会话的有效时长完全取决于目标网站的设置。某些网站的通行凭证在 cookie jar 中可持续数小时,而另一些网站每隔几分钟就会轮换一次。如果重放请求再次开始返回质询,请再次调用 /api/auto/ 进行刷新。

何时使用 Auto

使用 auto 手动使用 single、proxy 或 browser
目标是新网站,尚不清楚其具体要求 已经明确可行的执行引擎
希望通过单次调用自动处理 proxy 和 browser 回退 需要完全控制每次调用的重试和超时配置
可以接受首次调用耗费数秒进行探测 首次调用延迟比自动探测更重要
需要获取可低成本重放的学习会话 正在针对已知可行的目标优化高频循环

Auto 并不总是成本最低的选择。如果已知目标支持 single + unblocker,直接调用 Single 只需 2 个点数且延迟可控。针对同一目标使用 Auto 则会消耗其梯度探测所需的点数,若目标网站需要逐步提权,成本可能会更高。

Validate 告知 Auto 何为“成功”

最重要的参数是 validate。若未配置该参数,auto 仅会拒绝其能够识别的质询页面,导致未知的检测页面或带有 HTTP 200 状态码的空外壳被误判为有效内容。

配合 validate.data.accept 使用仅在真实页面中存在的子字符串:

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

对于 JSON API,接收预期的字段名称:

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

对于合理返回非 200 的站点(您希望忽略的地区限制、已删除页面的 404 或 410),可以通过 validate.status.accept 允许它们:

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

一旦某个出口返回了您在 validate.status.accept 中列出的状态码,并且该结果通过了您规则中的其余检查,Auto 就会立即返回该状态码。但有四个状态码例外:202、403、429 和 503。Auto 会将这些状态码视作目标站点正在校验请求者身份,因此返回这些状态码的出口不会终止搜索,阶梯会继续向上攀升。

如果没有配置 validate,对于所有未识别为质询的页面,Auto 会默认回退至“HTTP 200 = 成功”逻辑,因此无法捕获站点以 200 状态码返回的不熟悉检测页面。

读取 meta.rung 以了解具体发生的情况

meta.rung 是最有价值的调试信号。具体取值如下:

  • probe:通过低成本的 direct 请求解决。成本最低的路径。
  • proxy:需要通过 proxy 轮换才能通过。
  • browser:需要完整的浏览器渲染,可能还包含质询破解。
  • cache:复用了之前 auto 调用的预热 session。重复调用时的最低成本路径。
  • warmup:站点正常提供了入口页面,但对深层 URL 进行了拦截,因此 auto 先获取了入口页面,保留其下发的 cookie,并携带这些 cookie 重新发起请求。此阶梯保存的 session 不与单个出口绑定,因此后续调用可直接命中低成本阶梯。
  • fail:没有阶梯生成符合您规则的响应。

meta.solved: true 表示调用期间遇到并完成了质询页面。meta.attempts 是成功前子调用的重试次数。如需了解其背后的详细信息,请查看 single 和 proxy 阶梯返回的 defense 字段:参见 站点检查。

如果您预期应命中 probe,但站点始终停留在 browser,请考虑调整 validate 规则(调严格或放宽),以允许更低成本的阶梯通过。请注意,forceProxy 默认为 true,因此除非您手动将其关闭,否则将跳过直连出口探测。

调用消耗明细

meta.attemptsByEngine 统计了本次调用向各个引擎发送的 request 数量,这与 Overview 页面中 Auto attempts 面板显示的数据一致。meta.browserRequests 统计了消耗每日浏览器配额的请求数量。

"meta": {
  "rung": "browser",
  "solved": true,
  "attempts": 7,
  "credits": 47,
  "attemptsByEngine": {"single": 1, "proxy": 4, "browser": 3},
  "browserRequests": 2
}
字段 类型 说明
meta.attemptsByEngine object 发送到 single、proxy 和 browser 的 request。因计划限制而被拒绝的浏览器 request 也会计入此处,因为该 request 已发出。
meta.browserRequests number 消耗了每日配额槽位的浏览器 request。因计划限制而被拒绝的浏览器 request 不消耗配额。

meta.attempts 统计的是梯级步骤数,因此并不总是等于 meta.attemptsByEngine 的总和。一个步骤可能会先后发送一个 Single request 和一个 Proxy request,而若某一步骤的浏览器当天配额已耗尽关闭,则不会发送任何内容。

当天的累计计数通过 X-FourA-Browser-Used-Today 和 X-FourA-Browser-Limit-Per-Day header 传递:参见 Response Headers。

错误与边缘情况

当 auto 失败时,response 会携带 status(通常是最后一个失败阶梯的状态)和一个 error 字符串:

{
  "status": 502,
  "error": "could not find a working exit for the target",
  "attempts": 7,
  "attemptReport": {
    "total": 7,
    "noResponse": 5,
    "defense": 2,
    "contentRejected": 0,
    "statusRejected": 0,
    "other": 0,
    "vendors": ["datadome"],
    "summary": "7 attempt(s): 5 got no answer from the site; 2 refused by the site (datadome)"
  },
  "meta": {
    "rung": "fail",
    "solved": false,
    "attempts": 7,
    "credits": 47,
    "attemptsByEngine": {"single": 0, "proxy": 4, "browser": 3},
    "browserRequests": 3
  }
}

status 是目标站点在最后一次尝试中被 Auto 拒绝时的响应,例如 403。当所有尝试均未从站点获取任何响应时,通常返回 502 或 504,并且 error 会指明是未找到可用出口还是耗尽了 timeout_ms 预算。status: 0 仅表示目标主机名无法解析,该响应不包含 meta,因为梯级尝试从未启动。

当浏览器持续遇到无法完成的验证时,Auto 也会提前终止。在两个出口均以该方式拒绝浏览器,且搜索通过 validate 规则的普通抓取出口无结果后,或者累计出现三次此类出口拒绝后,调用即告结束。status 包含站点的最后一次响应,error 以 the browser was refused by 开头,后跟验证系统的名称。

当站点本身表明页面不存在时,Auto 也会停止尝试。当两个出口返回相同的 404 或 410 且您的规则不接受该状态时,调用以该 status 结束,且 error 以 the site answered 开头。如果您需要已被移除页面的响应,请在 validate.status.accept 中列出 404 或 410:这样只要出口返回该状态,Auto 就会直接将其作为交付结果返回。

在使用您的 API key 连续 4 次 Auto 调用因站点持续拒绝而未能获取页面后,Auto 将暂停该 key 对该站点的请求 120 秒。在此期间发起的调用会立即返回 status: 503、error: "target temporarily unservable, retry later" 以及以秒为单位的 retryAfter,且不产生任何费用。该计数按 API key 单独计算:调用同一站点的其他 key 不受影响,且任何成功获取页面的调用都会重置计数。带有 exitClass: premium 的调用不受此限制。

检查 attemptReport、meta.attemptsByEngine 和 meta.credits 可查看预算消耗情况。如果 meta.attempts 较高,且浏览器梯级后 meta.rung 为 fail,则目标可能需要更长的 timeout_ms、更严格的 validate 规则,或者当前根本无法通过轮换代理访问。

Auto 调用失败的原因

已运行梯级返回的每个失败响应均包含 attemptReport。它会根据所遇到的情况,对未成功返回页面的引擎请求进行单次分类计数。

字段 类型 说明
total integer 未返回页面的 request 数量。至多为 meta.attemptsByEngine 的总和,因为因套餐配额限制而拒绝的 browser request 从未尝试请求目标网站。
noResponse integer 未收到目标网站的响应
defense integer 目标网站拒绝了 request:识别出 Bot 验证、页面包含质询,或目标网站返回了 401、403、429 或 503
contentRejected integer 页面已成功抓取,仅因触发了您的 validate 规则而被拒绝
statusRejected integer 目标网站返回了您的 request 不接受的状态码,例如页面已删除返回的 404
other integer 因其他原因失败,例如服务器错误
vendors string[] 调用过程中遇到的拒绝响应里所识别出的 Bot 验证供应商
summary string 根据各项计数生成的一句话摘要,适合直接记录到日志中。如果未识别出任何供应商,它会指明目标网站返回的 HTTP 状态码;同时在每日 browser 配额耗尽导致无法启动 browser 时给出提示。

这些字段与失败的 Proxy 调用报告一致,只是不包含 profilesTried。两者的区别有两点:Proxy 统计其尝试过的每个出口节点数量,上限为您设置的 maxTries;而 Auto 统计的是其自身发起的 request 数量。此外,Auto 还会解析页面内容及其状态码,因此即使未识别出具体供应商,拒绝行为也会计入 defense。contentRejected 中的计数项是您可以自行修复的:页面已成功返回,但未能匹配您预设的规则。

当套餐限制遇到梯度回退机制时

Auto 的子调用是在您的 API key 下发起的普通 Single、Proxy 和 Browser request,因此受您的 套餐限制约束。梯度回退机制会读取拒绝响应中的 X-FourA-Limit 代码,并将这两类情况区别对待。

某个梯度层级关闭后,其余层级仍可继续使用。 plan_limit_browser_daily(当天 Browser request 配额已用尽)和 plan_limit_concurrency(该 endpoint 当前并发运行的 request 已达到套餐上限)只会关闭单个层级。Auto 会继续在其​​余层级上执行,因此只要轮换出口节点或预热 session 能够提供内容,您仍然可以获取页面;系统也不会把因自身套餐限制导致的拒绝归咎于已尝试的出口节点。任何节点都不会被封禁,session 也不会被废弃。

账户耗尽则直接终止梯度回退。 plan_limit_credits、plan_limit_bandwidth、plan_limit_rate、plan_limit_feature 和 plan_limit_premium 无法通过切换其他层级来解决,因此 Auto 会立即返回,而不会继续消耗您的点数去重复验证。拒绝详情将在 body 中返回,包含子调用的状态码以及直接调用 endpoint 时返回的相同 reason 字段:

{
  "status": 429,
  "error": "Credit limit reached: 300,000 of 300,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 300000,
  "hard_stop": 300000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z",
  "meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}

来自子调用的完整拒绝 body 会透传返回,外加 status、attemptReport 和 meta。请从 body 中读取 status,而不是从传输层状态中读取:此处 auto 仍会返回 HTTP 200,因为阶梯回退已执行。plan_limit_feature 或 plan_limit_premium 的拒绝也会以相同方式伴随 status: 403 返回。被拒绝的子调用不会消耗任何费用,因此 meta.credits 仅计算实际到达目标的阶梯层级。

单个 auto 调用在阶梯爬升时可能会占用多个槽位,因此并发的一批 auto 调用达到并发上限所需的调用量会比你预期的更少。并行运行请求介绍了批次大小的调整方法。

Auto 不具备的功能

  • 它不会改变法律限制。如果某个网站拒绝了 FourA 能访问的所有出口,auto 会直接返回该拒绝。
  • 它不缓存内容。每次调用仍会直接请求目标。所谓“预热会话”指的是 proxy 和 cookie,而非 response。
  • 它在 活动日志中表现为单行记录,归于你收到的 request ID 下,并汇总其子调用的 credit 消耗。展开该记录后,auto 代你发起的 Single、Proxy、Browser 子调用会作为尝试次数列出,每项均有各自的处理结果。它们计入你的 Single、Proxy 和 Browser 配额限制,绝不会计入你的 request 计数或成功率统计。
更新于: 2026年11月13日