Search
中文
English中文
Get started免费开始
api密钥浏览器自动化网页截图cdp控制
9 min

AdsCrawl 设置：从 API 密钥到首次浏览器请求

AdsCrawl 设置分步指南：创建 API 密钥，发送首次截图和 HTML 请求，配置 CDP 会话，并避免常见设置错误。

AAnonymous

AdsCrawl 设置：从 API 密钥到首次浏览器请求

AdsCrawl 将真实的浏览器操作转化为统一的 API。您无需自行管理无头 Chrome、代理和重试逻辑，只需发送请求即可获得截图、提取的 HTML、Markdown 或实时 Chrome DevTools 协议（CDP）会话。本指南将带您完成完整的设置路径：创建账户、生成 API 密钥、发出首次经过身份验证的请求、配置浏览器行为，并通过远程 CDP 控制进入生产环境。

设置过程有意保持简短。如果您严格遵循请求格式，从注册到完成可用的截图请求不到十分钟。

开始前需要准备什么

AdsCrawl 是一个 HTTP API，因此要求极简：

  • 一个具有有效 API 密钥的 AdsCrawl 账户
  • 一个可以发送 HTTP 请求的工具：cURL、Postman、Node.js 或 Python
  • 一个可访问的 HTTP(S) URL 用于测试
  • 对 JSON 请求体的基本熟悉

无需安装浏览器、WebDriver 二进制文件或本地 Chrome 实例。平台在服务端管理浏览器会话、代理和 User-Agent 轮换。

第 1 步：创建账户和 API 密钥

AdsCrawl 设置：从 API 密钥到首次浏览器请求 - 第 1 步：创建账户和 API 密钥。

第一个设置任务是创建账户。注册后，打开仪表盘并导航到密钥管理部分。仪表盘也是您跟踪信用使用情况、查看失败任务和调试请求负载的地方。

创建一个完整的 API 密钥并将其存储在安全的地方。该密钥在每次请求中作为 x-api-key 标头发送。请像对待密码一样对待它：不要将其提交到公共仓库，如果泄露请轮换。

如果您已有账户但无法访问仪表盘，AdsCrawl 登录指南 涵盖了登录步骤、密钥管理和常见的身份验证故障排除。

第 2 步：理解请求契约

每个浏览器任务都使用相同的信封：

  • 方法： POST
  • 基础 URL： https://api.adscrawl.net
  • 标头： x-api-key 和 content-type: application/json
  • 请求体： 包含必填 url 字段以及可选浏览器配置的 JSON

每次调用都必须包含 x-api-key 标头。缺失或无效的密钥返回 401。请求体必须是有效的 JSON；格式错误的负载返回 400。

必填和常见字段

字段 必填 用途
url 是 目标 HTTP(S) URL，使用端口 80 或 443
viewport 否 用于截图的浏览器视口宽度和高度
fullPage 否 捕获整个页面高度；默认为 true
selector 否 仅捕获第一个匹配的元素
waitUntil 否 导航等待策略：load、domcontentloaded 或 networkidle
timeoutMs 否 正数超时，最大 3,600,000 毫秒
countryCode 否 托管代理区域或 GLOBAL 用于动态出口
userAgentMode 否 custom 或 random 用户代理选择
cookies 否 导航前注入的 Cookie 列表
fingerprint 否 浏览器指纹设置

选择合适的 waitUntil 值

waitUntil 控制浏览器何时认为导航完成：

  • domcontentloaded 等待 HTML 解析完成，不等待次要资源。当不需要图片和样式表时，用于快速 HTML 提取。
  • load 等待窗口加载事件，包括依赖资源。这是默认值，也是一个不错的通用选择。
  • networkidle 等待至少 500 毫秒内没有网络连接。用于 JavaScript 密集型页面，但请注意，长轮询、分析或延迟加载的内容可能导致超时。

第 3 步：发出首次截图请求

从一个简单的 cURL 调用开始，以验证身份验证和连接性：

curl -sS -X POST "https://api.adscrawl.net/screenshot" \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "url": "https://example.com",
    "viewport": {"width": 1440, "height": 900},
    "fullPage": true,
    "waitUntil": "load",
    "countryCode": "GLOBAL",
    "userAgentMode": "random",
    "userAgentOs": "windows"
  }' \
  --output page.png

成功的响应返回 200 状态，带有 Content-Type: image/png 标头和二进制 PNG 流。打开 page.png 以确认捕获成功。

常见首次请求错误

状态 含义 修复
400 无效的 JSON、URL、cookies、代理、区域或 User-Agent 参数 验证您的 JSON 和字段值
401 缺失或无效的 x-api-key 检查标头名称和密钥值
402 余额不足 添加信用或检查您的计划
422 选择器未匹配或任务负载被拒绝 验证选择器在页面上是否存在
429 请求频率受限 降低请求频率
502 代理不可达或目标 HTTP 失败 使用不同的区域或 URL 重试
504 任务、导航或代理超时 增加 timeoutMs 或简化 waitUntil

第 4 步：提取 HTML 和 Markdown

截图捕获只是一个端点。对于数据提取，当您需要快速解析内容时，使用带有 waitUntil: "domcontentloaded" 的 HTML 端点：

curl -sS -X POST "https://api.adscrawl.net/html" \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "url": "https://example.com",
    "waitUntil": "domcontentloaded"
  }'

对于在客户端渲染内容的单页应用程序，切换到 networkidle 并添加充足的 timeoutMs。如果您只需要特定部分，传递 selector 以捕获第一个匹配的元素，而不是整个文档。

第 5 步：配置代理、区域设置和指纹

生产环境中的抓取通常需要区域出口点和一致的浏览器身份。AdsCrawl 支持多个配置层：

  • countryCode：使用两个字母的区域代码以优先选择该区域的受信任代理，或使用 GLOBAL 从 15 个热门区域动态出口。省略该字段以使用随机受信任代理。
  • locale 和 timezoneId：设置浏览器区域设置（如 en-US）和 IANA 时区（如 Asia/Shanghai）以匹配目标网站的期望。
  • geolocation：当网站检查位置时，提供纬度和经度坐标。
  • fingerprint：省略时，每个信号默认为随机，同时保持操作系统、GPU、CPU、内存、字体和设备信号的一致性。这减少了明显的自动化指纹。
  • cookies：在导航前注入 Cookie 列表以跨请求维护会话状态。

自定义代理也通过 proxy 字段支持，但不能与 countryCode 结合使用。

第 6 步：迁移到远程 CDP 进行交互式控制

截图和 HTML 端点是同步计量请求。对于交互式工作流，远程 CDP 让您直接控制实时浏览器会话：

  1. 使用您的 x-api-key 创建 CDP 会话。
  2. 响应包含一个 cdpBaseUrl，其中嵌入了保护发现和 CDP WebSockets 的数据令牌。
  3. 实时控制使用有效期为 30 秒的一次性 controlToken。
  4. 将您首选的 CDP 客户端连接到 WebSocket 端点并直接驱动浏览器。

这对于需要实时点击、输入、滚动和观察页面状态的 AI 代理非常有用。会话管理端点还支持列出和删除活动会话。

第 7 步：使用 Python 或 Node.js 集成

大多数团队很快会超越 cURL。相同的请求契约适用于任何 HTTP 客户端。

Python 示例

import requests

API_KEY = "YOUR_API_KEY"

response = requests.post(
    "https://api.adscrawl.net/screenshot",
    headers={
        "content-type": "application/json",
        "x-api-key": API_KEY,
    },
    json={
        "url": "https://example.com",
        "viewport": {"width": 1440, "height": 900},
        "fullPage": True,
        "waitUntil": "load",
    },
)

if response.status_code == 200:
    with open("page.png", "wb") as f:
        f.write(response.content)
else:
    print(response.status_code, response.text)

Node.js 示例

const response = await fetch("https://api.adscrawl.net/html", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-api-key": process.env.ADSCRAWL_API_KEY,
  },
  body: JSON.stringify({
    url: "https://example.com",
    waitUntil: "domcontentloaded",
  }),
});

const html = await response.text();
console.log(html);

要更广泛地比较 AdsCrawl 与其他浏览器自动化方法的优劣，请参阅 AdsCrawl 与 axiom.ai 与 Playwright 对比。

第 8 步：在生产环境中验证您的设置

在扩展之前，运行一个简短的验证清单：

  1. 身份验证有效：您的密钥在已知良好的 URL 上返回 200。
  2. 错误处理到位：您的代码处理 401、402、429 和 5xx 响应，并带有重试或警报。
  3. 超时策略经过深思熟虑：您根据页面类型选择 waitUntil 值，而不仅仅依赖默认值。
  4. 信用受到监控：仪表盘显示使用情况和剩余余额。
  5. 密钥受到保护：API 密钥存储在环境变量或密钥管理器中。

AdsCrawl 设置与自托管浏览器自动化对比

如果您正在决定使用 AdsCrawl 还是运行自己的浏览器集群，设置权衡是明确的：

因素 AdsCrawl 自托管 Playwright/Selenium
初始设置时间 分钟 数小时到数天
基础设施维护 无 代理轮换、浏览器更新、重试逻辑
并发 托管，基于信用 您自己的硬件限制
交互式控制 远程 CDP 会话 本地浏览器实例
成本模型 免费增值信用 基础设施加工程时间

当您想要 API 背后的浏览器功能而无需拥有基础设施时，AdsCrawl 是合理的。自托管框架提供更多控制，但需要持续维护。要更深入地了解每种方法何时胜出，Selenium 评论 涵盖了自托管框架的视角。

相关阅读

来源和进一步阅读

常见问题解答

如何获取我的 AdsCrawl API 密钥？

注册账户，打开仪表盘，在密钥管理部分创建一个完整的 API 密钥。在每次请求中使用该密钥作为 x-api-key 标头。

AdsCrawl API 请求的基础 URL 是什么？

基础 URL 是 https://api.adscrawl.net。端点如 /screenshot 和 /html 附加在此基础之上。

402 INSUFFICIENT_CREDITS 错误是什么意思？

您的账户余额不足以支付请求的任务。响应包含您当前的余额和所需信用。添加信用或升级您的计划以继续。

我可以将自定义代理与 countryCode 结合使用吗？

不可以。proxy 字段和 countryCode 字段互斥。每个请求选择一种路由方法。

CDP 控制令牌的有效期是多久？

用于实时 CDP 控制的一次性 controlToken 有效期为 30 秒。如果过期，请创建新会话或令牌。

请求体的最大大小是多少？

请求体限制为 1 MiB。更大的负载将被拒绝为无效 JSON，并返回 400 响应。

结论

AdsCrawl 设置遵循一个简单的模式：创建 API 密钥，发送包含目标 URL 和浏览器选项的 JSON 请求，并处理响应。主要决策是选择合适的 waitUntil 策略，为您的目标网站配置代理和指纹设置，以及决定何时从同步提取迁移到交互式 CDP 会话。

从一个截图请求开始以验证身份验证。然后随着工作流的成熟，添加 HTML 提取、区域路由和错误处理。有关更详细的端点文档和浏览器自动化的现场笔记，请参阅 AdsCrawl 文档 和 AdsCrawl 博客。

Related Articles

Browse all articles