模板 - AnyCrawl Docs

简介

模板是用于抓取、爬取或搜索的可重用配置。你无需在每次 API 调用中重复相同的选项，只需在模板中定义一次（或从 AnyCrawl 模板商店获取模板），然后通过 template_id 引用即可。

优势：

简洁：仅需 template_id + 最少输入即可调用 API
一致性：在团队或项目中标准化行为
安全性：模板可限制允许的域名，仅暴露必要的变量
强大：可选的自定义处理器，用于高级转换

支持的类型：

scrape：通过 /v1/scrape 进行单页面提取
crawl：通过 /v1/crawl 进行多页面爬取
search：通过 /v1/search 获取搜索引擎结果

模板市场

在 anycrawl.dev/template 浏览即用模板。

使用方法：

浏览市场，找到符合需求的模板
从模板详情页复制 template_id
使用该 template_id 和所需输入调用 API

示例：

curl -X POST "https://api.anycrawl.dev/v1/scrape" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "content-extractor",
    "url": "https://example.com"
  }'

在 API 调用中使用模板

请求参数

使用 template_id 时，仅允许以下最少字段：

Endpoint	Required Field	Optional Fields
`/v1/scrape`	`template_id`	`url`, `variables`
`/v1/crawl`	`template_id`	`url`, `variables`
`/v1/search`	`template_id`	`query`, `variables`

重要说明：

如果模板已预定义 url 或 query，则它们可能是可选的。请查看模板描述。
variables 用于传递模板期望的动态输入（参见下方变量部分）。
其他字段（如 engine、formats、timeout 等）来自模板，不可覆盖。
提供不允许的字段将返回 400 验证错误。

使用模板抓取

curl -X POST "https://api.anycrawl.dev/v1/scrape" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "my-scrape-template",
    "url": "https://example.com",
    "variables": { "category": "tech" }
  }'

使用模板爬取

curl -X POST "https://api.anycrawl.dev/v1/crawl" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "my-crawl-template",
    "url": "https://docs.example.com",
    "variables": { "maxPages": 50 }
  }'

使用模板搜索

curl -X POST "https://api.anycrawl.dev/v1/search" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "my-search-template",
    "query": "machine learning tutorials",
    "variables": { "lang": "en" }
  }'

变量

模板可声明变量，在调用时接受动态输入。

每个变量有一个 type：string、number、boolean 或 url
变量可以是 required（必填）或带有 defaultValue（默认值）的可选变量
查看模板描述以了解它期望的变量

带变量的请求示例：

{
    "template_id": "blog-scraper",
    "url": "https://example.com/blog/post-123",
    "variables": {
        "author": "john-doe",
        "includeComments": true,
        "maxComments": 50
    }
}

如果你遗漏了必填变量或提供了错误的类型，将收到 400 验证错误。

响应格式

模板响应遵循与标准 API 调用相同的格式：

{
    "success": true,
    "data": {
        "url": "https://example.com",
        "markdown": "# Page Title\n\nContent...",
        "metadata": { ... },
        // Additional fields from custom handlers (if any)
        "extractedData": { ... }
    }
}

带有自定义处理器的模板可能会在响应中添加额外字段。

错误处理

使用模板时的常见错误：

Error	HTTP Status	描述
Template not found	404	`template_id` 不存在或你没有访问权限
Validation error	400	缺少必填变量或类型错误
Domain restriction violation	403	URL 不在模板的域名策略允许范围内
Invalid fields	400	使用模板时不允许的额外顶层字段

错误响应示例：

{
    "success": false,
    "error": "Validation error",
    "message": "When using template_id, only template_id, url, variables are allowed. Invalid fields: engine, formats",
    "data": {
        "type": "validation_error",
        "issues": [
            {
                "field": "engine",
                "message": "Field 'engine' is not allowed when using template_id",
                "code": "invalid_field"
            }
        ],
        "status": "failed"
    }
}

最佳实践

对于 API 调用者

始终查看模板描述以了解必填变量和允许的域名/关键词
尽可能使用市场模板以节省时间
处理 404 错误（模板可能已被删除或归档）
不要尝试覆盖模板设置（engine、formats 等）— 会失败

对于模板作者

保持模板专注于单一用例
清晰记录所有变量及其描述
使用域名限制防止滥用
根据复杂度设置合适的定价
发布前彻底测试模板

创建模板（高级）

如果你正在创建自己的模板，可以配置以下内容：

域名限制

限制模板可在哪些域名上使用：

{
    "allowedDomains": {
        "type": "glob",
        "patterns": ["*.example.com", "docs.mysite.com"]
    }
}

type："exact"（精确匹配）或 "glob"（模式匹配）
patterns：允许的域名或模式数组

关键词限制（搜索模板）

限制搜索模板可使用的查询：

{
    "allowedKeywords": {
        "type": "glob",
        "patterns": ["*tutorial*", "*documentation*"]
    }
}

allowedKeywords 在查询执行前进行验证。
type："exact" 或 "glob"
patterns：允许的关键词值/模式
查询验证在 queryTransform 应用之前执行。

定价

设置每次调用的积分成本：

{
    "pricing": {
        "perCall": 10,
        "currency": "credits"
    }
}

自定义处理器

编写 JavaScript/TypeScript 代码来：

requestHandler：后处理抓取结果并添加自定义字段
failedRequestHandler：使用自定义重试逻辑处理失败
queryTransform（仅搜索）：在搜索前转换查询
urlTransform（仅抓取/爬取）：在处理前转换 URL

两种转换均支持：

带占位符的模板模式（query: {{query}}，url: {{url}}）
带 prefix 和 suffix 的追加模式
可选的 regexExtract，在应用模式前预提取子字符串

TikTok 个人主页的正则提取示例：

{
    "customHandlers": {
        "urlTransform": {
            "enabled": true,
            "mode": "append",
            "prefix": "",
            "suffix": "",
            "regexExtract": {
                "pattern": "^(https?:\\/\\/www\\.tiktok\\.com\\/@[^\\/?#]+)",
                "flags": "i",
                "group": 1
            }
        }
    }
}

此配置从如下输入中提取 https://www.tiktok.com/@piperrockelle：

https://www.tiktok.com/@piperrockelle?abb=ccc
https://www.tiktok.com/@piperrockelle

requestHandler 示例：

// Extract structured data from page context
const title = context.data.title;
const content = context.data.markdown;

return {
    extractedTitle: title,
    wordCount: content.split(/\s+/).length,
    customMetric: calculateMetric(content),
};

安全模型

非受信模板：在强化的虚拟机沙箱中运行，有严格限制
受信模板：可使用异步函数并受控访问浏览器页面

只有经过 AnyCrawl 审核和批准的模板才能标记为受信。

常见问题

我可以覆盖模板设置（如 engine 或 formats）吗？

不可以。模板被设计为不可变的配置。你只能提供 url/query 和 variables。

使用市场中的模板会怎样？

市场模板是公开可用的。你需要支付模板作者设定的积分费用。

模板能看到我的 API 密钥吗？

不能。模板在隔离的沙箱中运行，无法访问你的凭据。

如何创建自己的模板？

访问 AnyCrawl playground 来创建和测试模板。发布后即可通过 API 使用。

模板

简介