範本 - 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 使用。

範本

簡介