scraperapi-n8n

n8n 中的 ScraperAPI — 工作流生成器

此技能可帮助你围绕 ScraperAPI 官方社区节点 （n8n-nodes-scraperapi-official）组装 n8n 工作流。根据用户的表述，选择以下两种输出形式之一：

用户说……	生成内容
“给我工作流 JSON”、“导出”、“我要导入这个”、“搭建一个 .json 框架”	完整、可导入的工作流 JSON 文件
“一步步指导我”、“告诉我如何构建”、“在 n8n 编辑器中操作”、“分步说明”	按编号排列的构建指南，并引用准确的资源／操作／参数名称
表述模糊	默认生成 JSON。这样便于灵活处理——用户可以导入，也可以将其作为操作指南。

生成 JSON 时，将其写入工作目录中的文件（例如， scraperapi-workflow.json），并告知用户通过 n8n 界面中的 Workflows → Import from File 导入。生成构建指南时，按 n8n 编辑器中的操作格式编排步骤（资源选择器 → 操作选择器 → 字段）。

用户必须满足的前提条件

1. 拥有一个可以安装社区节点的 n8n 实例（云端、可自托管或桌面版）。对于自托管实例，必须先由实例所有者启用社区节点。
2. 已安装社区节点：Settings → Community Nodes → Install → n8n-nodes-scraperapi-official。安装后，节点选择器中会显示“ScraperAPI”。
3. 拥有 ScraperAPI API 密钥，可从 https://dashboard.scraperapi.com/ 获取。他们需要通过 Credentials → New → ScraperAPI API 创建一次凭据，并粘贴密钥。该凭据在界面中的名称为 ScraperAPI API，在工作流 JSON 中的名称为 scraperApi-Api。

如果用户使用 n8n Cloud，且工作流 JSON 引用了此节点，则必须先在其实例中安装社区节点，才能成功导入。交付 JSON 时请说明这一点。

四种资源——选择合适的一种

ScraperAPI 节点有一个操作入口（resource），包含四个分支。请根据任务选择：

任务	资源	原因
抓取任意 URL 并获取 HTML／Markdown／文本／JSON	api	通用代理。可传入任意 URL。
从受支持的网站（Amazon、Google、eBay、Walmart、Redfin）获取整洁的 JSON	sde	预先解析的结构化数据。无需使用 Set／Code 节点解析 HTML，且能更可靠地应对网站改版。
从一个起始 URL 抓取多个页面，并将结果流式发送到 webhook	crawler	可跟随链接的多页面任务。它会返回 jobId；结果会发送到你的 webhook，而不是作为节点的输出返回。
从没有 SDE 的网站上，多个结构相似的页面中提取自定义结构化 JSON	aiparser	通过示例 URL 一次构建可重复使用的 AI 解析器，然后将其应用于任何类似页面。此过程为异步：创建 → 轮询状态 → 解析。

常见模式：如果网站有结构化端点，就使用该端点；其他情况则使用 api（并设置 apiRender: true 或 apiPremium: true）；如果需要从没有 SDE 的网站重复提取自定义字段，则使用 aiparser；只有在逐个处理 URL 需要多次顺序执行节点时，才使用 crawler。

必需的 JSON 结构——最简示例

这是使用 ScraperAPI 的最简工作流。本技能中的其他内容都是在此结构基础上的变化。

{
  "name": "ScraperAPI minimal example",
  "nodes": [
    {
      "parameters": {},
      "type": "n8n-nodes-base.manualTrigger",
      "typeVersion": 1,
      "position": [240, 300],
      "id": "trigger-1",
      "name": "When clicking 'Test workflow'"
    },
    {
      "parameters": {
        "resource": "api",
        "operation": "apiRequest",
        "apiUrl": "https://example.com",
        "apiOptionalParameters": {
          "apiRender": true,
          "apiCountryCode": "us"
        }
      },
      "type": "n8n-nodes-scraperapi-official.scraperApi",
      "typeVersion": 1,
      "position": [480, 300],
      "id": "scraperapi-1",
      "name": "ScraperAPI",
      "credentials": {
        "scraperApi-Api": {
          "id": "REPLACE_WITH_CREDENTIAL_ID",
          "name": "ScraperAPI API"
        }
      }
    }
  ],
  "connections": {
    "When clicking 'Test workflow'": {
      "main": [
        [{ "node": "ScraperAPI", "type": "main", "index": 0 }]
      ]
    }
  },
  "settings": { "executionOrder": "v1" }
}

每个工作流 JSON 都必须注意的事项

1. 节点类型： n8n-nodes-scraperapi-official.scraperApi — 拼写必须完全一致，区分大小写。类型错误会导致导入时出现“无法识别的节点类型”。
2. **凭据块：**键为 scraperApi-Api（不是 scraperApiApi）。 将 id 保留为占位符，并告知用户在导入的节点中重新选择凭据。 n8n 无法跨实例查找凭据 ID。
3. ScraperAPI 节点的 typeVersion: 1。
4. 连接使用节点的 name，而非 id。如果重命名节点，也要更新连接映射。
5. Position 是编辑器中的 [x, y] 像素坐标。导入时位置任意即可；n8n 会按需重新布局。水平间距约为 240px。
6. settings 下的 executionOrder: "v1" — 这是当前默认值。 旧版 "none"／"v0" 已弃用，且与合并操作的行为不同。

节点字段中的表达式 — = 前缀

n8n 通过字段值开头的 = 字符来区分字面字符串和表达式。这适用于每个节点的每个字段，包括 ScraperAPI 的 apiUrl、sdeAsin、sdeQuery 等。

"apiUrl": "https://example.com"          // literal — always this URL
"apiUrl": "={{ $json.url }}"             // expression — URL from upstream item
"apiUrl": "{{ $json.url }}"              // ⚠ literal "{{ $json.url }}" string

以下是一些经常用到的实用模式：

"sdeAsin":  "={{ $json.asin }}"
"sdeQuery": "={{ $json.body.search_term }}"           // webhook payload
"sdeUrl":   "=https://www.redfin.com/city/{{ $json.city_id }}"

当值需要同时包含字面内容和动态内容时，只在字符串开头保留 =。{{ }} 中的所有内容都是 JS 表达式 — $json、$node['Other'].json.x、JSON.stringify(...)、内联算术等。

对于由 webhook 触发的工作流，请记住用户数据位于 body 下方（参见下文“常见错误”）。表达式应为 ={{ $json.body.x }}，而不是 ={{ $json.x }} — 漏掉 body. 是 n8n 中最常见的静默故障。

参数命名——n8n 陷阱

节点的 JSON 参数名与 ScraperAPI 的 HTTP 查询参数名并不相同。n8n 使用带资源前缀的驼峰命名法；API 使用蛇形命名法。生成 JSON 时，请使用 n8n 的字段名。

ScraperAPI HTTP 参数	n8n 字段（api 资源）	n8n 字段（crawler 资源）
url	apiUrl	crawlerStartUrl
render	apiOptionalParameters.apiRender	crawlerOptionalParameters.crawlerApiParameters.crawlerApiRender
country_code	apiOptionalParameters.apiCountryCode	crawlerOptionalParameters.crawlerApiParameters.crawlerApiCountryCode
premium	apiOptionalParameters.apiPremium	crawlerOptionalParameters.crawlerApiParameters.crawlerApiPremium
ultra_premium	apiOptionalParameters.apiUltraPremium	crawlerOptionalParameters.crawlerApiParameters.crawlerApiUltraPremium
autoparse	apiOptionalParameters.apiAutoparse	crawlerOptionalParameters.crawlerApiParameters.crawlerApiAutoparse
output_format	apiOptionalParameters.apiOutputFormat	crawlerOptionalParameters.crawlerApiParameters.crawlerApiOutputFormat
设备（桌面）	apiOptionalParameters.apiDesktopDevice（bool）	crawlerOptionalParameters.crawlerApiParameters.crawlerApiDesktopDevice
设备（移动）	apiOptionalParameters.apiMobileDevice（bool）	crawlerOptionalParameters.crawlerApiParameters.crawlerApiMobileDevice
session_number	apiOptionalParameters.apiSessionNumber	crawlerOptionalParameters.crawlerApiParameters.crawlerApiSessionNumber
keep_headers	apiOptionalParameters.apiKeepHeaders	crawlerOptionalParameters.crawlerApiParameters.crawlerApiKeepHeaders
follow_redirect	apiOptionalParameters.apiFollowRedirect	crawlerOptionalParameters.crawlerApiParameters.crawlerApiFollowRedirect
retry_404	apiOptionalParameters.apiRetry404	crawlerOptionalParameters.crawlerApiParameters.crawlerApiRetry404
zip	apiOptionalParameters.apiZipCode	（仅限 api）
custom_headers	apiOptionalParameters.apiCustomHeaders	（仅限 api）
wait_for_selector	apiOptionalParameters.apiWaitForSelector	（仅限 api）
x-sapi-instruction_set	apiOptionalParameters.apiInstructionSet	（仅限 api）

对于 SDE 平台，请参阅 references/node-reference.md——每个平台/操作都有各自的必填字段名（例如 sdeAsin、sdeQuery、sdeProductId、sdeUrl、sdeCategory）以及各自的可选参数集合（例如 sdeAmazonProductOptions、sdeGoogleSearchOptions）。

AI Parser 例外：aiparser 资源使用 aiParser* 驼峰命名字段名（aiParserName、aiParserUrls、aiParserId、aiParserUrl 等），但其 aiParserScraperParams 集合的内部键使用普通的蛇形命名法（render、premium、country_code、session_number 等）——没有前缀，这与其他所有资源都不同。请参阅 references/node-reference.md。

如果不确定准确的字段名，请在生成 JSON 前阅读参考文件。字段名错误的字段在导入时会被静默丢弃。

ScraperAPI 节点的输出

每个操作都会为每个输入项返回一个条目，结构如下：

{
  "resource": "api",
  "response": {
    "body": "...",
    "headers": { },
    "statusCode": 200,
    "statusMessage": "OK"
  }
}

对于 api 和 crawler，body 是原始文本负载（HTML、Markdown，或根据 apiOutputFormat 设置的 JSON 字符串）。对于 sde，body 是 ScraperAPI 返回的 JSON 文档字符串，后续节点需要对其进行解析。最简单的做法是使用 Code 节点：

return $input.all().map((item, i) => ({
  json: JSON.parse(item.json.response.body),
  pairedItem: { item: i },
}));

pairedItem 字段会告知 n8n 每个输出对应哪个输入项。在线性流程中，省略此字段也能正常工作；但只要工作流出现分支（Loop Over Items、Merge、重新汇合的 IF），缺少 pairedItem 就会导致下游节点的条目不匹配——批处理工作流中最常见的情况是“行与抓取结果配错”。务必设置此字段。

在此节点之后，可在下游直接通过 ={{ $json.<field> }} 访问结构化负载中的所有字段。

按使用场景划分的连接模式

用户通常会设想以下某一种结构。只要其中一种符合需求，就不要设计复杂的多节点流程。

每日监控 — 定时抓取 → 比对 → 通知

Schedule Trigger → [Sheets/DB read] → Loop Over Items
                                          ↓
                                       ScraperAPI (sde)
                                          ↓
                                       Code (parse body)
                                          ↓
                                       [Sheets/DB write history]
                                          ↓
                                       IF (changed?)
                                          ↓
                                       Email / Slack

如果用户的请求类似于价格监控或每日摘要工作流（涉及定时触发器、商品列表、ScraperAPI 查询、历史记录表、发生变化时发送邮件中的任意组合），不要手动编写这种结构的 JSON。请获取 ScraperAPI 的规范模板并进行调整：

GET https://api.n8n.io/api/templates/workflows/15609

完整的可导入工作流 JSON 位于 response.workflow.workflow（其中顶层包含 nodes 和 connections，可直接导入 n8n）。模板共有 29 个节点——Schedule Trigger、3 个 ScraperAPI 节点（Amazon / Walmart / Google Shopping）、用于保存历史记录的 Data Table、用于比对的 Code 节点、HTML 摘要，以及 Gmail 和 SMTP 两种邮件发送路径，供用户选择。

调整模板，而不是照搬：更改商品列表，移除用户不需要的零售商，替换邮件发送路径，简化摘要。引用方便用户预览的说明页面，然后再导入：

https://n8n.io/workflows/15609-send-daily-price-drop-digest-emails-for-amazon-walmart-and-google-via-scraperapi/

手动编写任何工作流之前，建议先查看 ScraperAPI 的完整模板集合：https://n8n.io/creators/scraperapi/——如果已有适用于用户场景的官方模板，就应调整该模板，而不是从头编写。

如果获取失败（离线、受到速率限制或 API 发生变化），请改用上方图示的结构，以及 references/example-workflows.md 中更简单的单个 ASIN 示例。

Webhook 丰富数据 — 按需查询

Webhook → ScraperAPI (sde or api) → Code (parse) → Respond to Webhook

适用于潜在客户数据丰富、按需查询商品，或作为 MCP 风格的工具提供给大模型。将 Webhook 的响应设置为“Using 'Respond to Webhook' node”，以便返回解析后的数据。

Crawler + webhook 回调 — 多页任务

[Trigger] → ScraperAPI (crawler / Initiate) → ... waits ...
                                                ↓
                              (results arrive at separate webhook workflow)

Webhook (the callbackUrl) → process each page → store / index

Initiate 操作会立即返回 jobId。页面抓取完成后会通过 POST 请求发送到 crawlerCallbackUrl——这必须是另一个带有 Webhook 触发器的工作流，而不是启动任务的同一个工作流。务必告知用户，在激活工作流之前，将回调工作流的 webhook URL 复制到 crawlerCallbackUrl 中。

从列表批量处理 — CSV/Sheet 扇出

[Read CSV / Sheet] → Loop Over Items (batch size 5–10) → ScraperAPI → Code → Merge → Output

使用 Loop Over Items（又称 Split In Batches），并设置较小的批次大小，以免超过 ScraperAPI 的并发限制。Free 计划支持 5 个并发请求；付费计划支持更多并发请求。如果用户知道自己使用的计划，请据此设置批次大小；否则默认设为 5。

AI Agent 工具 — 为大模型提供实时网页访问能力

ScraperAPI 节点声明了 usableAsTool: true，因此可以作为可调用工具接入 n8n AI Agent 节点。Agent 会根据用户的提示词决定何时调用它，以及使用什么 URL／查询内容。

Chat Trigger → AI Agent ─┬─ Chat Model (OpenAI / Anthropic / etc.)
                          ├─ Memory (optional)
                          └─ Tool: ScraperAPI

连接详情：

1. 将 ScraperAPI 节点添加到画布。其操作和参数相当于工具签名——Agent 会根据上下文填写动态参数。选择与希望 Agent 执行的任务匹配的操作（例如，若要“让 Agent 搜索网页”，选择 sde / googleSearch；若要“让 Agent 获取任意 URL”，选择 api / apiRequest）。
2. 对于动态字段，使用 ={{ $fromAI('parameter_name', 'description', 'string') }}。$fromAI 是 n8n 的辅助函数，可将参数公开给 Agent 的工具架构；Agent 会在运行时选择参数值。
3. 通过 Tool 输入端口将 ScraperAPI 节点连接到 AI Agent 节点（而不是主输入端口）。
4. 为节点设置清晰、以动作为导向的名称（“搜索网页”、“抓取任意 URL”）——Agent 会将节点名称作为其所见工具描述的一部分。

{
  "resource": "sde",
  "sdePlatform": "google",
  "operation": "googleSearch",
  "sdeQuery": "={{ $fromAI('query', 'The user search query', 'string') }}",
  "sdeGoogleSearchOptions": {
    "tld": "com",
    "outputFormat": "json"
  }
}

Agent 会收到解析后的 JSON 正文作为工具结果，并据此进行推理。为获得最佳效果，请在 ScraperAPI 工具和 Agent 之间添加一个 Code 节点，以精简负载——原始 SDE 响应可能很大，足以超出 Agent 的上下文预算。

额度预算 — 提醒用户

ScraperAPI 会按成功请求扣除额度。循环运行或定时运行的工作流可能会在用户不知情的情况下消耗额度。如果工作流每次运行抓取超过约 50 个 URL，或运行频率高于每小时一次，请在回复中估算每次运行和每月的费用。

设置	每次请求的额度
api 标准模式	1
api + apiRender: true	10
api + apiPremium: true	10
api + apiPremium: true + apiRender: true	25
api + apiUltraPremium: true	30
sde 结构化端点	1–10（视垂直领域而定；参见公开文档）
aiparser 生成（aiParserCreate、添加字段的 aiParserUpdate）	30,000（每增加一个解析器；每个账户的第一个解析器免费）
aiparser 解析（aiParserParse）	标准抓取费用：1，另加任何抓取器参数附加费用（例如，渲染为 10）

生成 AI Parser 的费用很高。 每个账户可免费获得一个解析器；生成每个额外解析器需花费 30,000 个额度——切勿在循环中创建解析器。每个 URL 的 aiParserParse 持续费用较低（标准抓取费率），因此应在多个页面上重复使用同一个解析器。失败请求（非 200）通常不会收费，但如果瞬时错误重试后最终成功，仍会消耗额度。

如需查看完整且最新的定价信息，请在回复中附上链接 https://docs.scraperapi.com/。

常见错误 — ❌ 错误 / ✅ 正确

缺少 = 前缀会使表达式变成纯文本

❌ "apiUrl": "{{ $json.url }}"            // n8n scrapes the literal string "{{ $json.url }}"
✅ "apiUrl": "={{ $json.url }}"           // resolved to the current item's url field

Webhook 数据位于 body 下，而不是根级别

❌ "sdeQuery": "={{ $json.search_term }}"           // undefined
✅ "sdeQuery": "={{ $json.body.search_term }}"      // works

Webhook 节点会将传入数据封装为 { headers, params, query, body }。 用户的负载位于 $json.body。接收 JSON 正文的 Chat Trigger 也一样。

Code 节点返回解析后的对象，而不是 n8n 项目格式

❌ return JSON.parse($json.response.body);
❌ return { data: parsed };
✅ return [{ json: JSON.parse($json.response.body), pairedItem: { item: 0 } }];

n8n 需要一个由 { json: {...}, pairedItem?: {...} } 组成的数组。返回原始对象会导致后续节点报错：“Cannot read properties of undefined”。

同时设置 apiPremium 和 apiUltraPremium

❌ { "apiPremium": true, "apiUltraPremium": true }
✅ { "apiUltraPremium": true }                      // pick one; ultra implies premium

它们在节点 UI 中互斥，同时设置时的行为未定义。

将爬虫回调路由回同一个工作流

❌ ScraperAPI (crawlerJobCreate) ───loops to itself───> processing nodes
✅ Workflow A:  Trigger → ScraperAPI (crawlerJobCreate, callbackUrl = "<webhook in Workflow B>")
   Workflow B:  Webhook trigger → process page → store

爬虫结果会以 HTTP POST 请求的形式从 ScraperAPI 的基础设施发送到 callbackUrl。只有带有 Webhook 触发器的工作流才能接收这些结果——切勿将它们发送回发起任务的同一个工作流。

导出的 JSON 中包含硬编码的凭据 ID

❌ "credentials": { "scraperApi-Api": { "id": "abc123", "name": "ScraperAPI API" } }
✅ "credentials": { "scraperApi-Api": { "id": "REPLACE", "name": "ScraperAPI API" } }

凭据 ID 仅在单个 n8n 实例内有效。从另一个实例导入包含实际 ID 的工作流会导致“找不到凭据”错误。请使用占位符，并让用户在导入后重新选择一次凭据。

设置 sdePlatform 却没有匹配的 operation

❌ { "sdePlatform": "amazon", "operation": "googleSearch" }   // mismatched
✅ { "sdePlatform": "amazon", "operation": "amazonProduct" }

operation 字段的取值取决于平台。对于 sdePlatform: "amazon"，有效操作为 amazonProduct、amazonSearch、amazonOffers。对于 Amazon Reviews and Prices（底层 API 支持，但尚未作为单独的节点操作提供），请改用 api + apiAutoparse: true，并指定 Amazon URL。

sde 后跳过 Code 节点解析步骤

结构化响应是 response.body 中的 JSON 字符串。在 Code（或 Set）节点解析该内容之前，下游节点引用 ={{ $json.pricing }} 时会得到 undefined。请参阅上方的解析代码片段。

节点参数中包含硬编码的 API 密钥

API 密钥应存放在凭据记录中，绝不能放在节点参数或表达式中。将密钥写入 JSON 会导致它暴露在工作流导出文件、版本历史记录和审计日志中。

何时阅读什么内容

如果你需要……	请阅读
SDE 操作的确切字段名称	references/node-reference.md
更完整的示例（价格监控器、潜在客户信息丰富器）	references/example-workflows.md
有效的 n8n 工作流 JSON 的完整结构	references/workflow-json-anatomy.md

生成工作流 JSON 后，请检查以下内容：

1. node.type 必须严格为 n8n-nodes-scraperapi-official.scraperApi
2. connections 中引用的每个节点都存在于 nodes 中
3. 字段名称符合前缀规则（api* / sde* / crawler* / aiParser*）——但 aiParserScraperParams 内部的键除外，这些键使用普通的 snake_case（render、country_code……）
4. credentials 块使用键 scraperApi-Api
5. JSON 中任何位置都没有明文 API 密钥

相关技能和生态系统

• scraperapi-mcp（此插件中的关联技能）——当用户希望 Claude 自行调用 ScraperAPI 作为工具，而不是将其接入 n8n 工作流时使用。输出形式不同：实时答案，而非可复用的 JSON。
• n8n-mcp MCP 服务（https://github.com/czlonkowski/n8n-mcp）——第三方 MCP 服务，可向 Claude 提供 n8n 的完整节点目录、验证功能和工作流增删改查功能。如果用户已安装该服务，建议通过 validate_workflow 验证生成的 JSON，并使用 n8n_create_workflow 部署，而不是让用户手动导入。这两项技能可以配合使用：本技能介绍 ScraperAPI 节点的结构；n8n-mcp 则介绍 n8n 的周边功能。

文档

• 节点列表：https://n8n.io/integrations/scraperapi/
• ScraperAPI 模板合集（所有官方工作流）：https://n8n.io/creators/scraperapi/
• 降价摘要模板（页面）：https://n8n.io/workflows/15609-send-daily-price-drop-digest-emails-for-amazon-walmart-and-google-via-scraperapi/
• 降价摘要模板（API，返回完整工作流 JSON）：https://api.n8n.io/api/templates/workflows/15609
• npm 包：https://www.npmjs.com/package/n8n-nodes-scraperapi-official
• ScraperAPI 文档：https://docs.scraperapi.com/
• 控制面板：https://dashboard.scraperapi.com/