scrapfly-sdk-typescript

Scrapfly TypeScript SDK

scrapfly-sdk パッケージを使用すると、プロキシローテーション、ボット対策の回避（Unblocker）、JavaScript のレンダリング、スクリーンショットの取得、AI 抽出を利用して、TypeScript/JavaScript からウェブページをスクレイピングできます。Node.js、Deno、Bun、エッジランタイム（Cloudflare Workers、AWS Lambda）で動作します。

使用する場面

• TS/JS コードベースからウェブページ（HTML、JSON、テキスト、Markdown）をスクレイピングする場合
• ボット対策（Cloudflare、DataDome、PerimeterX、Kasada）を回避する場合
• ヘッドレスブラウザーで JavaScript を多用するページをレンダリングする場合
• スクリーンショットを取得したり、構造化データを抽出したりする場合
• 多数の URL を並行してスクレイピングする場合

セットアップ

npm install scrapfly-sdk
# Deno / JSR: import from 'jsr:@scrapfly/scrapfly-sdk'
export SCRAPFLY_API_KEY="your-api-key"

API キーは scrapfly.io で取得してください。

基本的なスクレイピング

import { ScrapflyClient, ScrapeConfig } from 'scrapfly-sdk';

const client = new ScrapflyClient({ key: process.env.SCRAPFLY_API_KEY });

const result = await client.scrape(
    new ScrapeConfig({ url: 'https://web-scraping.dev/products' }),
);

console.log(result.result.content);

ボット対策の回避、地域ターゲティング、JavaScript レンダリング

ScrapeConfig では、API に合わせてオプションキーにスネークケースを使用します。

const result = await client.scrape(
    new ScrapeConfig({
        url: 'https://web-scraping.dev/products',
        proxy_pool: 'unblocker',            // residential proxies + the Unblocker (anti-bot bypass)
        country: 'us',                      // proxy country (ISO 3166-1 alpha-2)
        render_js: true,                    // headless browser rendering
        wait_for_selector: 'div.product',   // requires render_js
        rendering_wait: 5000,               // ms, requires render_js
        format: 'markdown',                 // raw | clean_html | json | markdown | text
    }),
);

スクリーンショットと抽出

import { ScreenshotConfig, ExtractionConfig } from 'scrapfly-sdk';

const shot = await client.screenshot(
    new ScreenshotConfig({ url: 'https://web-scraping.dev/products' }),
);
// shot.image is the binary image data

const html = (await client.scrape(
    new ScrapeConfig({ url: 'https://web-scraping.dev/reviews' }),
)).result.content;

const data = await client.extract(
    new ExtractionConfig({
        body: html,
        content_type: 'text/html',
        extraction_prompt: 'extract the reviews as JSON with fields: review, date, rating, author',
    }),
);
console.log(data.data);

並行スクレイピング

const configs = [
    new ScrapeConfig({ url: 'https://web-scraping.dev/products?page=1' }),
    new ScrapeConfig({ url: 'https://web-scraping.dev/products?page=2' }),
];

for await (const result of client.concurrentScrape(configs)) {
    console.log(result.result.content.slice(0, 100));
}

重要な注意事項

• rendering_wait、wait_for_selector、スクリーンショットには render_js: true が必要です
• proxy_pool はプロキシプールを選択します。'basic'（データセンタープロキシ、Unblocker は無効）、'unblocker'（レジデンシャルプロキシと Unblocker）、'unblocker_ultra'（同じ構成で、ターゲットまたは独自の料金が設定されたボット対策が受け付ける唯一のプール）、または 'auto'（API がリクエスト前にターゲットのプロファイルに基づいてプールを選択します。データセンタープロキシ上の Unblocker、またはターゲットが必要とするプールのいずれかを使用します。unblocker_ultra が必要なターゲットを含め、すべてのターゲットで受け付けられ、その場合はターゲットの料金が加算されます。実際に使用されるプールの料金が適用されます）。各プールで Unblocker の有効・無効が設定されます。独自の料金が設定されたターゲットまたはボット対策に対して basic と unblocker を指定すると、ERR::PROXY::UNBLOCKER_ULTRA_REQUIRED（HTTP 422、課金なし）が返されます。その場合は proxy_pool: 'unblocker_ultra' を指定して再送してください。0.12.0 より後のリリースでは、ScreenshotConfig にも同じ proxy_pool を指定できます
• unblocker: true とその別名 asp は非推奨です。proxy_pool（Unblocker には 'unblocker_ultra'）を使用してください。移行ガイドでは、プロキシプール導入前に記述されたリクエストと、プール名 'public_datacenter_pool' および 'public_residential_pool' について説明しています。asp が明示的に指定されている場合は、unblocker より優先されます
• クリーンで LLM に適したコンテンツには format: 'markdown' を使用してください
• API キーはコンストラクターの key オプションから読み込まれます（process.env.SCRAPFLY_API_KEY を渡してください）
• result.result.content からページ本文を読み取ってください