ScrapeGraphAI 智能网页抓取与内容提取 Piece 集成指南（Activepieces）-开发者社区

ScrapeGraphAI 智能网页抓取与内容提取 Piece 集成指南（Activepieces）

【免费下载链接】activepiecesAI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces

导读

本文围绕 Activepieces 开源仓库中的scrapegrapghai官方 Piece，系统讲解如何将 ScrapeGraphAI 的 AI 网页抓取与内容提取能力接入你的自动化工作流。你将掌握 API Key 认证配置、Smart Scraper / Local Scraper / Markdownify 三大动作的参数含义与底层调用原理，以及如何用输出 Schema 将非结构化网页内容转成结构化数据供下游步骤使用。

一、Piece 概述：AI 驱动的网页抓取与内容提取

scrapegrapghai是 Activepieces 官方仓库中位于 packages/pieces/community/scrapegrapghai 的社区 Piece，它封装了 ScrapeGraphAI 的云 API（基础地址为https://api.scrapegraphai.com/v1），将"AI 抓取网页并提取信息"的能力以 Activepieces 标准动作（Action）的形式暴露给流程构建者。

从 src/index.ts 可以看到该 Piece 的完整定义：

export const scrapegraphai = createPiece({ displayName: 'ScrapeGraphAI', description: 'AI-powered web scraping and content extraction.', minimumSupportedRelease: '0.30.0', logoUrl: 'https://cdn.activepieces.com/pieces/scrapegraphai.jpg', categories: [PieceCategory.ARTIFICIAL_INTELLIGENCE], authors: ["OsamaHaikal"], auth: scrapegraphaiAuth, actions: [ smartScraper, localScraper, markdownify, createCustomApiCallAction({ baseUrl: () => 'https://api.scrapegraphai.com/v1', auth: scrapegraphaiAuth, authMapping: async (auth) => ({ 'SGAI-APIKEY': `${auth.secret_text}`, }), }), ], triggers: [], });

需要重点关注的几个设计事实：

动作全集：Piece 内置 3 个 AI 抓取动作（Smart Scraper、Local Scraper、Markdownify），同时通过createCustomApiCallAction额外暴露了一个Custom API Call动作，允许你对 ScrapeGraphAI API 发起任意自定义 HTTP 请求。i18n 资源文件（translation.json）中也包含"Custom API Call"、HTTP 方法、Headers、Query Parameters、Body 等字段，印证了这一动作的存在。
认证方式：所有动作共用同一个scrapegraphaiAuth密钥认证，请求时通过SGAI-APIKEY请求头注入（见下文"认证"章节）。
分类与兼容：该 Piece 被归类为PieceCategory.ARTIFICIAL_INTELLIGENCE（人工智能类），声明的最低支持版本为0.30.0，即需要 Activepieces0.30.0及以上版本才能加载。
无触发器：triggers: []，说明它只用于流程中主动发起抓取，不提供监听型触发器。
包信息：npm 包名为@activepieces/piece-scrapegrapghai（当前仓库版本 0.1.7），依赖@activepieces/pieces-common、@activepieces/pieces-framework、@activepieces/core-piece-types与@activepieces/core-utils（见 package.json）。

二、认证：获取并配置 ScrapeGraphAI API Key

该 Piece 使用SecretText 密钥认证（PieceAuth.SecretText），这是整个接入过程唯一的前置条件。认证逻辑定义在 src/lib/auth.ts：

export const scrapegraphaiAuth = PieceAuth.SecretText({ description: markdownDescription, displayName: 'API Key', required: true, validate: async ({ auth }) => { try { await httpClient.sendRequest({ method: HttpMethod.POST, url: 'https://api.scrapegraphai.com/v1/smartscraper', headers: { 'Content-Type': 'application/json', 'SGAI-APIKEY': auth, }, body: { user_prompt: 'test', website_url: 'https://www.example.com', }, }); return { valid: true }; } catch (e) { return { valid: false, error: 'Invalid API Key' }; } }, });

获取 API Key 的步骤

访问 ScrapeGraphAI 官网并注册账号；
登录后进入你的控制台（Dashboard）；
在控制台中找到并复制你的 API Key。

该说明同时以 Markdown 形式内嵌在认证字段的描述中（markdownDescription），在 Activepieces 构建器的连接配置界面中会直接展示给用户。

认证的两个关键技术细节

请求头格式：实际请求使用SGAI-APIKEY请求头携带密钥（而非常见的Authorization: Bearer）。三个动作与 Custom API Call 的authMapping均使用此约定。
内置校验：validate函数在保存连接时会向POST https://api.scrapegraphai.com/v1/smartscraper发送一个最小测试请求（user_prompt: 'test'+website_url: 'https://www.example.com'）。若请求失败则校验不通过并提示Invalid API Key，从而在连接建立阶段就拦截错误密钥，避免流程运行到一半才发现认证失败。

注意：由于密钥以明文文本形式存储并用于请求头，建议在 Activepieces 中妥善保管该连接，不要将密钥写死在流程的普通文本字段中。

三、Smart Scraper：用自然语言提示词定向抓取网页

Smart Scraper 是最核心的动作：给定一个公开网页 URL 和一段自然语言提示词，由 AI 服务端抓取页面并只提取你关心的内容。实现在 src/lib/actions/smart-scraper.ts。

参数说明

参数	类型	必填	说明
`website_url`	ShortText	是	要抓取的网页 URL
`user_prompt`	LongText	是	用自然语言描述你想提取的信息，例如"提取所有产品名称和价格"
`output_schema`	Json	否	可选的输出结构定义，用于将结果整理为结构化字段

底层实现

async run({ auth, propsValue }) { const response = await httpClient.sendRequest({ method: HttpMethod.POST, url: 'https://api.scrapegraphai.com/v1/smartscraper', headers: { 'Content-Type': 'application/json', 'SGAI-APIKEY': auth.secret_text, }, body: { website_url: propsValue.website_url, user_prompt: propsValue.user_prompt, output_schema: propsValue.output_schema, }, }); return response.body; }

实现上就是一次标准的 POST 调用：请求体携带website_url、user_prompt与可选的output_schema，响应体（response.body）原样返回给流程，供后续步骤（如写入表格、发送消息）引用。

适用场景

动态网站：AI 服务端负责渲染与内容识别，适合 JavaScript 渲染的页面（原 README 提到的"Support for dynamic websites"）；
定向提取：只需要页面中一小部分信息（如商品价格、文章作者、联系方式），而不是整页内容；
结构化输出：配合output_schema，将半结构化的网页内容整理成固定字段的 JSON，便于下游直接使用。

该动作的aiMetadata中明确标注了idempotent: true且"Read-only and safe to retry"，即它是只读且幂等的——抓取过程不产生副作用，流程失败重试是安全的。同时它指明"页面由服务端从 URL 抓取；如果 HTML 已在手边，应使用 Local Scraper 代替"，帮助 Agent 或 AI 流程正确选型。

四、Local Scraper：直接处理手头的 HTML 内容

Local Scraper 与 Smart Scraper 的差异在于输入来源：它不通过 URL 抓取页面，而是直接接收你已经拿到的 HTML 原始内容，由 AI 从中提取信息。实现在 src/lib/actions/local-scraper.ts。

参数说明

参数	类型	必填	说明
`website_html`	LongText	是	要处理的 HTML 内容，上限 2MB
`user_prompt`	LongText	是	自然语言提取提示词
`output_schema`	Json	否	可选的结构化输出定义

底层实现

async run({ auth, propsValue }) { const response = await httpClient.sendRequest({ method: HttpMethod.POST, url: 'https://api.scrapegraphai.com/v1/localscraper', headers: { 'Content-Type': 'application/json', 'SGAI-APIKEY': auth.secret_text, }, body: { website_html: propsValue.website_html, user_prompt: propsValue.user_prompt, output_schema: propsValue.output_schema, }, }); return response.body; }

适用场景与注意点

HTML 已在流程中：例如先用 HTTP 请求动作或文件读取动作拿到 HTML，再交给 Local Scraper 提取，避免二次抓取；
静态页面：适合内容已包含在 HTML 中的静态网页（原 README 提到的"Static website support"）；
资源开销低：由于不发起额外页面抓取，适合对已获取内容做轻量提取（"Resource-efficient"）；
大小限制：输入 HTML 不得超过 2MB，超限会失败，这是实现中明确标注的约束。

同样地，该动作被标注为idempotent: true、只读且可安全重试；aiMetadata也提示"已有页面 HTML 时选择此动作，活 URL 请用 Smart Scraper"，与 README 的定位描述相互印证。

五、Markdownify：把网页转成干净的 Markdown

Markdownify 用于将任意公开网页整体转换为干净、可读的 Markdown 文本，适合"整页转文本"场景（如喂给 LLM、归档为文档）。实现在 src/lib/actions/markdownify.ts。

参数说明

参数	类型	必填	说明
`website_url`	ShortText	是	要转换为 Markdown 的网页 URL

底层实现

async run({ auth, propsValue }) { const response = await httpClient.sendRequest({ method: HttpMethod.POST, url: 'https://api.scrapegraphai.com/v1/markdownify', headers: { 'Content-Type': 'application/json', 'SGAI-APIKEY': auth.secret_text, }, body: { website_url: propsValue.website_url, }, }); return response.body; }

适用场景

整页内容提取：当你需要页面的全部正文而非特定字段时使用（原 README 中的"Clean and formatted markdown output"、"Preserves content structure"）；
LLM 输入预处理：将 HTML 转成 Markdown 后再作为上下文喂给 AI 模型，比原始 HTML 更省 token、更易解析；
文档归档：将在线文档、博客文章转成 Markdown 存档。

aiMetadata明确建议："需要整页文本给 LLM 或文档时用 Markdownify；需要按提示词提取特定字段时用 Smart Scraper"。三个动作形成清晰的分工：

动作	输入	输出	典型场景
Smart Scraper	URL + 提示词（+Schema）	结构化提取结果	从动态/静态页面定向提取字段
Local Scraper	HTML + 提示词（+Schema）	结构化提取结果	对已有 HTML 内容做提取
Markdownify	URL	整页 Markdown	整页转文本供 LLM/文档使用

六、Custom API Call：直连 ScrapeGraphAI API

除了三个封装好的动作，Piece 还通过createCustomApiCallAction提供了一个自定义 API 调用动作。其关键配置如下（src/index.ts）：

createCustomApiCallAction({ baseUrl: () => 'https://api.scrapegraphai.com/v1', auth: scrapegraphaiAuth, authMapping: async (auth) => ({ 'SGAI-APIKEY': `${auth.secret_text}`, }), })

这意味着你可以在构建器中自由指定路径（相对https://api.scrapegraphai.com/v1）、HTTP 方法、请求头、查询参数和请求体，且认证头会自动注入SGAI-APIKEY: <你的密钥>（i18n 文件中"Authorization headers are injected automatically from your connection."即描述该行为）。

典型用途：

调用 ScrapeGraphAI API 中尚未被封装成独立动作的端点；
微调请求体以满足特定业务参数；
快速验证某个 API 行为，无需等待官方 Piece 更新。

七、在 Activepieces 流程中组合使用：实战编排

基于以上实现细节，下面给出一个可落地的组合思路（以构建器中操作即可，无需修改仓库代码）：

场景示例：监控产品页面价格并写入表格

触发：使用定时触发器，每天运行一次；
Smart Scraper：website_url填产品页 URL，user_prompt填"提取商品名称、当前价格、库存状态"，output_schema填入结构化定义（如{"product_name": "string", "price": "number", "stock": "string"}），使输出变为固定字段的 JSON；
后续动作：将提取结果写入 Google Sheets / Airtable / 数据库等存储动作，或触发通知。

场景示例：抓取 HTML 后本地提取

先用 HTTP 请求动作获取目标页面的 HTML（注意控制在 2MB 以内）；
Local Scraper：将上一步 HTML 传入website_html，user_prompt写"提取所有链接的 URL 和锚文本"；
将结果整理后交给下游处理。

场景示例：整页转文档

Markdownify：website_url填博客文章 URL；
将返回的 Markdown 存入知识库、发送到邮箱或作为 AI 模型的上下文输入。

三个动作的aiMetadata均标注为只读、幂等、可安全重试，因此在编排时可以放心加入失败重试逻辑，不必担心重复执行产生副作用。

八、约束与前提

必须持有 ScrapeGraphAI API Key，且保存连接时会被在线校验（请求示例域https://www.example.com的 smartscraper 端点）；
API 为云端服务，所有动作都依赖https://api.scrapegraphai.com/v1的可用性与网络连通性；
Local Scraper 输入上限 2MB，超大 HTML 需要先截断或拆分；
需要 Activepieces 0.30.0 及以上版本（minimumSupportedRelease: '0.30.0'）；
该 Piece 无触发器，只能作为流程中的动作步骤使用；
抓取目标的网站需允许被访问，公开 URL 是 Smart Scraper 与 Markdownify 的前提。