API Schema 参考：所有端点共享的类型

这些 schema 出现在多个 AdsCrawl 端点中。本页面将每个 schema 集中定义一次，避免在每个端点参考中重复。在开始构建之前理解 browserSettings、fingerprint、proxy、cookies、waitFor、field 和 actions，可以让你一致且正确地配置浏览器任务、CDP 会话和云浏览器。

`browserSettings`

在 CDP 会话和云浏览器之间共享的浏览器配置。省略地区时会使用随机可信代理；如果需要确定性路由，请显式传入 GLOBAL、地区代码或自定义 proxy 对象。

object

浏览器窗口大小。

显示 viewport 字段

number

必填

视口宽度，单位为像素。

number

必填

视口高度，单位为像素。

string

浏览器语言环境，例如 "en-US"。

string

IANA 时区标识符，例如 "Asia/Shanghai"。

object

注入浏览器的可选地理位置坐标。

显示 geolocation 字段

number

必填

纬度，以十进制度数表示。

number

必填

经度，以十进制度数表示。

object

自定义代理配置。不能与 countryCode 同时使用。请参阅下方的 proxy schema。

string

托管代理地区。使用 "GLOBAL" 可自动选择热门地区，或使用两位国家代码（例如 "FR"）以优先选择该地区的可信代理并支持动态回退。不能与 proxy 同时使用。

string

覆盖默认的 User-Agent 字符串。

"custom" | "random"

设置为 "random" 可让服务器从其库中选择 User-Agent。未提供 User-Agent 的请求默认使用 "random"。

"windows" | "macos"

随机 User-Agent 模式使用的操作系统。默认为 "windows"。

object

浏览器指纹设置。在 CDP 上下文中省略时，canvas 和 webGlImage 默认为 "real"，其他信号使用一致的随机化配置。请参阅下方的 fingerprint schema。

cookies[]

在会话启动前注入浏览器上下文的 Cookie。请参阅下方的 cookies[] schema。

示例

{
  "viewport": { "width": 1440, "height": 900 },
  "locale": "en-US",
  "timezoneId": "America/New_York",
  "countryCode": "US",
  "userAgentMode": "random",
  "userAgentOs": "macos",
  "fingerprint": {
    "canvas": "random",
    "webRtc": "forward"
  }
}

`fingerprint`

控制浏览器指纹信号以降低被检测的风险。每个字段都是可选的。浏览器任务中省略的字段默认使用 "random"。CDP browserSettings 中省略时，canvas 和 webGlImage 设置为 "real"，其他信号从一致的随机化配置生成。

当 webGl 为 "real" 时，不能将 webGpu 或 hardware 设置为 "random"。这三个信号必须保持一致。

字段	可接受的值	说明
`webRtc`	`"forward" \| "real" \| "disabled"`	`"forward"` 使用代理出口地址。旧值 `"random"` 被接受为 `"forward"` 的别名。
`webGl`	`"random" \| "real"`	伪造或保留 WebGL 供应商和渲染器元数据。
`webGpu`	`"random" \| "real" \| "disabled"`	`"random"` 模式下，遵循 WebGL GPU 配置。
`webGlImage`	`"random" \| "real"`	控制 WebGL 图像渲染噪声。
`canvas`	`"random" \| "real"`	添加或抑制 canvas 指纹噪声。
`audioContext`	`"random" \| "real"`	添加或抑制 audio context 指纹噪声。
`clientRects`	`"random" \| "real"`	添加或抑制布局测量噪声。
`speechVoices`	`"random" \| "real"`	返回与操作系统匹配或真实的语音列表。
`fonts`	`"random" \| "real"`	返回与操作系统匹配或真实的已安装字体列表。
`hardware`	`"random" \| "real"`	将 CPU 线程数和设备内存作为匹配对生成。
`doNotTrack`	`"random" \| "enabled" \| "disabled"`	控制 DNT 请求头偏好。

示例

{
  "webRtc": "forward",
  "webGl": "random",
  "webGpu": "random",
  "canvas": "random",
  "audioContext": "random",
  "fonts": "random",
  "hardware": "random",
  "doNotTrack": "disabled"
}

`proxy`

用于路由浏览器流量的自定义代理配置。提供 server URL 形式或拆分形式（protocol + host + port），切勿同时使用两者。

username 和 password 必须同时提供。对于无需认证的代理，请同时省略两者。切勿将凭据嵌入 server URL 中。

string

完整的代理 URL，例如 "http://host:port" 或 "socks5://host:port"。必须包含显式端口。不能与 host 同时使用。请勿嵌入凭据、路径、查询字符串或片段。

"http" | "socks5"

拆分形式的代理协议。

string

拆分形式的代理主机名。不能与 server 同时使用。

number | string

拆分形式的代理端口。接受从 1 到 65535 的整数或数字字符串。

string

代理认证用户名。必须与 password 同时提供。

string

代理认证密码。必须与 username 同时提供。

示例

{
  "server": "http://proxy.example.com:8080",
  "username": "<proxy-user>",
  "password": "<proxy-password>"
}

{
  "protocol": "socks5",
  "host": "proxy.example.com",
  "port": 1080,
  "username": "<proxy-user>",
  "password": "<proxy-password>"
}

{
  "server": "http://proxy.example.com:8080"
}

`cookies[]`

在导航开始前注入浏览器上下文的 Cookie 数组。每个条目都是一个具有以下字段的对象。

string

必填

Cookie 名称。

string

必填

Cookie 值。

string

必填

目标域名，例如 ".example.com"。包含前导点以匹配子域名。

string

Cookie 路径。默认为 "/"。

boolean

当为 true 时，Cookie 仅通过 HTTPS 发送。

boolean

当为 true 时，Cookie 对客户端 JavaScript 不可访问。

boolean

当为 true 时，Cookie 绑定到确切主机而非子域名。

string

SameSite 属性。可接受的值："Strict"、"Lax"、"None"。

boolean

当为 true 时，Cookie 随会话过期，没有持久性过期时间。

number

以 Unix 时间戳（秒）表示的持久性过期时间。这三个字段名称可以互换使用。

示例

[
  {
    "name": "sid",
    "value": "<session-token>",
    "domain": ".example.com",
    "path": "/",
    "secure": true,
    "httpOnly": true,
    "sameSite": "Lax",
    "expirationDate": 1893456000
  }
]

`waitFor`

指示浏览器在导航后或执行 actions 后暂停，直到页面上出现特定元素或文本。你可以在同一个对象中组合使用 selector 和 text。

string

CSS 选择器。浏览器等待第一个匹配的元素变为可见。

string

文本内容。浏览器等待第一个包含此文本的元素变为可见。

number

最长等待时间，单位为毫秒。默认为 15000。无论提供什么值，都不会超过剩余的任务超时时间。

示例

{
  "selector": "#search-results",
  "timeoutMs": 10000
}

`field`（SPA 提取字段定义）

定义 POST /spa-extract 请求中要提取的单个字段。DOM 字段读取元素内容；网络字段从拦截到的 JSON 响应中捕获数据。

"dom" | "network"

必填

此字段的数据源。使用 "dom" 从页面 DOM 中读取，或使用 "network" 从网络请求中捕获匹配的 JSON 响应。

string

标识目标元素的 CSS 选择器。source: "dom" 字段必填。

"text" | "html" | "attribute"

DOM 读取模式。默认为 "text"。使用 "html" 获取元素内部 HTML，或使用 "attribute" 读取特定属性。

string

当 value 为 "attribute" 时要读取的属性名称。例如 "href" 或 "data-id"。

string

用于匹配 source: "network" 字段响应 URL 的子字符串。使用最近匹配的响应。

string

从匹配的网络响应体中提取值的 JSONPath 表达式。例如 "$.data.metrics[0].value"。

boolean

当为 true 时，字段返回所有匹配 DOM 元素的数组，而不仅仅是第一个。

"string" | "number" | "integer" | "boolean" | "json"

在返回之前，将提取的原始值强制转换为指定类型。

string

应用于提取值的正则表达式。当模式包含捕获组时，组 1 将作为字段值返回。

boolean

当为 true 时，缺失或不匹配的字段会导致端点返回 422 SPA_REQUIRED_FIELDS_MISSING，而不是返回 null。

示例

{
  "source": "dom",
  "selector": "h1.product-title",
  "value": "text",
  "required": true
}

{
  "source": "dom",
  "selector": "meta[name='description']",
  "value": "attribute",
  "attribute": "content"
}

{
  "source": "network",
  "urlIncludes": "/api/v2/metrics",
  "path": "$.data.metrics[0].value",
  "parse": "number",
  "required": true
}

{
  "source": "dom",
  "selector": "ul.results li",
  "value": "text",
  "multiple": true
}

`actions[]`

在 POST /spa-extract 中提取开始前执行的有序页面交互数组。每个元素都是一个带有 type 字段的对象，决定执行哪个操作。每个交互步骤的上限为 30 秒。

wait — 暂停执行

暂停执行固定毫秒数。

{ "type": "wait", "milliseconds": 2000 }

string

必填

必须为 "wait"。

number

必填

暂停时长。可接受范围：0 到 30000。

waitForSelector — 等待元素

暂停直到第一个匹配 CSS 选择器的元素变为可见。

{ "type": "waitForSelector", "selector": "#content", "timeoutMs": 8000 }

string

必填

必须为 "waitForSelector"。

string

必填

要等待的 CSS 选择器。

number

最长等待时间，单位为毫秒。省略时默认为该步骤的 30 秒上限。

click — 点击元素

点击第一个匹配 CSS 选择器的元素。

{ "type": "click", "selector": "button.load-more" }

string

必填

必须为 "click"。

string

必填

要点击元素的 CSS 选择器。

fill — 填充输入框

清除目标输入元素并输入给定值。

{ "type": "fill", "selector": "input[name='q']", "value": "browser automation" }

string

必填

必须为 "fill"。

string

必填

要填充的输入元素的 CSS 选择器。

string

必填

要输入到输入框的文本。

press — 按键

向第一个匹配 CSS 选择器的元素发送键盘按键。

{ "type": "press", "selector": "input[name='q']", "key": "Enter" }

string

必填

必须为 "press"。

string

必填

目标元素的 CSS 选择器。

string

必填

要按的键，例如 "Enter"、"Tab" 或 "ArrowDown"。

scroll — 滚动页面或元素

将元素滚动到视图中，或按给定的像素偏移量滚动页面。

{ "type": "scroll", "y": 1200 }

{ "type": "scroll", "selector": ".lazy-section" }

string

必填

必须为 "scroll"。

string

CSS 选择器。提供时，匹配的元素将被滚动到视图中。

number

水平滚动偏移量，单位为像素。默认为 0。

number

垂直滚动偏移量，单位为像素。未提供 selector 时默认为 800。

完整的 actions 示例

[
  { "type": "waitForSelector", "selector": "#cookie-banner button", "timeoutMs": 5000 },
  { "type": "click", "selector": "#cookie-banner button" },
  { "type": "fill", "selector": "input[name='q']", "value": "adscrawl api" },
  { "type": "press", "selector": "input[name='q']", "key": "Enter" },
  { "type": "waitForSelector", "selector": "#results", "timeoutMs": 10000 },
  { "type": "scroll", "y": 1600 }
]

`cloudBrowser.runtime`

云浏览器端点返回的运行时状态对象。它描述了运行中或已停止的浏览器会话的当前生命周期状态。

切勿自行构造 connectUrl 或 cdpBaseUrl，也不要将 API 密钥、Cookie 或代理凭据附加到这些 URL。始终使用 API 返回的确切 URL。如果响应中缺少 URL，请在继续之前查询当前状态。

"neko" | "worker_cdp"

支撑此浏览器会话的运行时类型。"neko" 提供交互式浏览器并省略 cdpBaseUrl。"worker_cdp" 暴露 CDP 端点并可能包含 cdpBaseUrl。

"starting" | "running" | "stopping" | "stopped"

必填

会话的当前生命周期状态。

显示状态值

值	含义
`starting`	会话正在配置中。运行配额已预留。
`running`	会话处于活动状态。`connectUrl` 可能存在。
`stopping`	已请求停止但尚未确认。运行配额仍被预留。
`stopped`	会话已结束。运行配额已释放。

string

活动会话标识符。在 starting、running 和 stopping 状态下存在。

string (RFC3339)

活动会话的过期时间。

string

打开交互式浏览器的直接 URL。仅当 status 为 "running" 且 runtimeKind 为 "neko" 时存在。需要配置文件所有者的登录会话，授权使用会话 Cookie，而非查看者的 usr/pwd URL 参数。

string

带有临时令牌的 CDP 基础 URL。仅由 worker_cdp 运行时返回。

"starting" 和 "stopping" 状态都计入用户的并发运行配额。"stopping" 会话尚未释放其槽位，请轮询 GET /cloud-browsers/{id} 直到返回 "stopped" 后再假设容量可用。

响应示例

{
  "runtimeKind": "neko",
  "status": "running",
  "sessionId": "<session-id>",
  "expiresAt": "2026-09-07T09:00:00.000Z",
  "connectUrl": "https://api.adscrawl.net/cloud-browser-runtime/<session-id>/?usr=adscrawl&pwd=adscrawl"
}

{
  "runtimeKind": "neko",
  "status": "stopped"
}

{
  "runtimeKind": "neko",
  "status": "stopping",
  "sessionId": "<session-id>",
  "expiresAt": "2026-09-07T09:00:00.000Z"
}

Google Trends 结果元数据

成功的 google-trends-explore 响应在标准 SPA 结果之外返回的额外顶级字段。这些字段描述结果是从实时浏览器会话收集的，还是从服务器缓存提供的。

"sunbrowser" | "cache"

必填

指示结果是从实时浏览器会话（"sunbrowser"）收集的，还是从服务器端缓存（"cache"）提供的。

boolean

必填

当此响应从缓存提供时为 true。

boolean

必填

当缓存结果已过期时为 true。响应已从缓存提供，但数据可能已过时。

string (RFC3339Nano)

必填

结果实际收集的时间戳，格式为 RFC3339Nano。

integer

必填

返回结果前进行的收集尝试次数。缓存命中响应始终报告 0。过期响应报告结果报告时已进行的尝试次数。

示例

{
  "source": "sunbrowser",
  "cached": false,
  "stale": false,
  "collectedAt": "2026-09-07T08:42:11.348291200Z",
  "attempts": 1
}

概览

浏览器任务

远程 CDP

云浏览器

API Schema 参考：所有端点共享的类型

`browserSettings`

示例

`fingerprint`

示例

`proxy`

示例

`cookies[]`

示例

`waitFor`

示例

`field`（SPA 提取字段定义）

示例

`actions[]`

完整的 actions 示例

`cloudBrowser.runtime`

响应示例

Google Trends 结果元数据

示例

​browserSettings

​示例

​fingerprint

​示例

​proxy

​示例

​cookies[]

​示例

​waitFor

​示例

​field（SPA 提取字段定义）

​示例

​actions[]

​完整的 actions 示例

​cloudBrowser.runtime

​响应示例

​Google Trends 结果元数据

​示例

`browserSettings`

示例

`fingerprint`

示例

`proxy`

示例

`cookies[]`

示例

`waitFor`

示例

`field`（SPA 提取字段定义）

示例

`actions[]`

完整的 actions 示例

`cloudBrowser.runtime`

响应示例

Google Trends 结果元数据

示例