Headless Web Scraping

単純な HTTP リクエストに抵抗するウェブページ — JS レンダリングされたコンテンツ、Cloudflare 保護されたサイト、動的 SPA — から、scrapling の 3 ティア fetcher アーキテクチャと CSS ベースのデータ抽出を使ってデータを抽出する。

使用タイミング

• ターゲットページが JavaScript レンダリング（SPA、React、Vue）を要求する
• サイトに anti-bot 保護がある（Cloudflare Turnstile、TLS フィンガープリンティング）
• CSS セレクタを介して複数要素の構造化抽出が必要
• 単純な WebFetch または requests.get() が空またはブロックされた応答を返す
• スケールでの表データ、リンクリスト、繰り返し DOM 構造の抽出

入力

• 必須: スクレイプする URL またはターゲット URL のリスト
• 必須: 抽出するデータ（CSS セレクタ、フィールド名、ターゲット要素の記述）
• 任意: Fetcher ティア上書き（既定: サイト挙動に基づく自動選択）
• 任意: 出力フォーマット（既定: JSON; 代替: CSV、Python dict）
• 任意: リクエスト間のレート制限遅延（秒）（既定: 1）

手順

ステップ1: Fetcher ティアを選ぶ

どの scrapling fetcher がターゲットサイトの防御に合うかを判定する。

# Decision matrix:
# 1. Fetcher        — static HTML, no JS, no anti-bot (fastest)
# 2. StealthyFetcher — Cloudflare/Turnstile, TLS fingerprint checks
# 3. DynamicFetcher  — JS-rendered SPAs, click/scroll interactions

# Quick probe: try Fetcher first, escalate on failure
from scrapling import Fetcher

fetcher = Fetcher()
response = fetcher.get("https://example.com/target-page")

if response.status == 200 and response.get_all_text():
    print("Fetcher tier sufficient")
else:
    print("Escalate to StealthyFetcher or DynamicFetcher")

Signal	Recommended Tier
Static HTML, no protection	Fetcher
403/503, Cloudflare challenge page	StealthyFetcher
Page loads but content area is empty	DynamicFetcher
Need to click buttons or scroll	DynamicFetcher
altcha CAPTCHA present	None (cannot be automated)

期待結果： 3 ティアのうち 1 つが特定される。ほとんどの現代サイトには、StealthyFetcher が正しい開始点。

失敗時： 3 ティアすべてがブロック応答を返すなら、サイトが altcha CAPTCHA（バイパス不能な proof-of-work チャレンジ）を使うか確認する。そうなら、制限を文書化し代わりに手動抽出指示を提供する。

ステップ2: Fetcher を設定する

選んだ fetcher を適切なオプションでセットアップする。

from scrapling import Fetcher, StealthyFetcher, DynamicFetcher

# Tier 1: Fast HTTP with TLS fingerprint impersonation
fetcher = Fetcher()
fetcher.configure(
    timeout=30,
    retries=3,
    follow_redirects=True
)

# Tier 2: Headless Chromium with anti-detection
fetcher = StealthyFetcher()
fetcher.configure(
    headless=True,
    timeout=60,
    network_idle=True  # wait for all network requests to settle
)

# Tier 3: Full browser automation
fetcher = DynamicFetcher()
fetcher.configure(
    headless=True,
    timeout=90,
    network_idle=True,
    wait_selector="div.results"  # wait for specific element before extracting
)

期待結果： Fetcher インスタンスが設定され準備できている。インスタンス化でエラーなし。StealthyFetcher と DynamicFetcher には Chromium バイナリが利用可能（scrapling が初回実行時に自動管理）。

失敗時：

• playwright またはブラウザバイナリが見つからない -- python -m playwright install chromium を実行
• configure() でのタイムアウト -- タイムアウト値を増やすかネットワーク接続を確認
• インポートエラー -- scrapling をインストール: pip install scrapling

ステップ3: データを取得し抽出する

ターゲット URL にナビゲートし、CSS セレクタを使って構造化データを抽出する。

# Fetch the page
response = fetcher.get("https://example.com/target-page")

# Single element extraction
title = response.find("h1.page-title")
if title:
    print(title.get_all_text())

# Multiple elements
items = response.find_all("div.result-item")
for item in items:
    name = item.find("span.name")
    price = item.find("span.price")
    print(f"{name.get_all_text()}: {price.get_all_text()}")

# Get attribute values
links = response.find_all("a.product-link")
urls = [link.get("href") for link in links]

# Get raw HTML content of an element
detail_html = response.find("div.description").html_content

主要 API リファレンス:

Method	Purpose
response.find("selector")	First matching element
response.find_all("selector")	All matching elements
element.get("attr")	Attribute value (href, src, data-*)
element.get_all_text()	All text content, recursively
element.html_content	Raw inner HTML

期待結果： 抽出データが可視ページコンテンツと一致する。要素は非 None で、ポピュレートされたページではテキストコンテンツが非空。

失敗時：

• find() が None を返す -- 実際の HTML を検査（response.html_content）してセレクタを検証する; ページは予想と異なるクラス名を使うかもしれない
• get_all_text() から空テキスト -- コンテンツは shadow DOM または iframe 内かもしれない; wait_selector を伴う DynamicFetcher を試す
• .css_first() を使わない -- これは scrapling API の一部ではない（他ライブラリとの一般的な混乱）

ステップ4: 失敗とエッジケースを扱う

CAPTCHA 検出、空応答、セッション要件のためのフォールバックロジックを実装する。

import time

def scrape_with_fallback(url, selector):
    """Try each fetcher tier in order, with CAPTCHA detection."""
    tiers = [
        ("Fetcher", Fetcher),
        ("StealthyFetcher", StealthyFetcher),
        ("DynamicFetcher", DynamicFetcher),
    ]

    for tier_name, tier_class in tiers:
        fetcher = tier_class()
        fetcher.configure(headless=True, timeout=60)

        try:
            response = fetcher.get(url)
        except Exception as error:
            print(f"{tier_name} failed: {error}")
            continue

        # Detect CAPTCHA / challenge pages
        page_text = response.get_all_text().lower()
        if "altcha" in page_text or "proof of work" in page_text:
            print(f"altcha CAPTCHA detected -- cannot automate")
            return None

        if response.status == 403 or response.status == 503:
            print(f"{tier_name} blocked (HTTP {response.status}), escalating")
            continue

        result = response.find(selector)
        if result and result.get_all_text().strip():
            return result.get_all_text()

        print(f"{tier_name} returned empty content, escalating")

    print("All tiers exhausted. Manual extraction required.")
    return None

期待結果： 関数は成功時に抽出テキスト、すべてのティアが失敗したときに診断メッセージと共に None を返す。CAPTCHA ページは無限にリトライではなく検出され報告される。

失敗時：

• すべてのティアが 403 を返す -- サイトはすべての自動アクセスをブロックする（WIPO、TMview、一部政府データベースで一般）; 手動アクセスを要求する URL として文書化
• タイムアウトエラー -- ページは遅い CDN 後ろにあるかもしれない; タイムアウトを 120s に増やす
• セッション/cookie エラー -- サイトはログインを要求するかもしれない; cookie 処理を加えるかまず認証する

ステップ5: レート制限と倫理的スクレイピング

スケールで実行する前に遅延を実装しサイトポリシーを尊重する。

import time
import urllib.robotparser

def check_robots_txt(base_url, target_path):
    """Check if scraping is allowed by robots.txt."""
    rp = urllib.robotparser.RobotFileParser()
    rp.set_url(f"{base_url}/robots.txt")
    rp.read()
    return rp.can_fetch("*", f"{base_url}{target_path}")

def scrape_urls(urls, selector, delay=1.0):
    """Scrape multiple URLs with rate limiting."""
    results = []
    fetcher = StealthyFetcher()
    fetcher.configure(headless=True, timeout=60)

    for url in urls:
        response = fetcher.get(url)
        data = response.find(selector)
        if data:
            results.append(data.get_all_text())

        time.sleep(delay)  # respect the server

    return results

倫理的スクレイピングチェックリスト:

1. スクレイピング前に robots.txt を確認 -- Disallow 指令を尊重
2. リクエスト間に最低 1 秒の遅延を使う
3. 可能なら記述的 User-Agent でスクレイパーを識別
4. 法的根拠なしに個人データをスクレイプしない
5. 冗長リクエストを避けるためローカルに応答をキャッシュ
6. 429（Too Many Requests）を受け取ったらすぐ停止

期待結果： スクレイピングが制御されたレートで動く。バルク操作前に robots.txt が確認される。429 応答が引き起こされない。

失敗時：

• 429 Too Many Requests -- 遅延を 3-5 秒に増やす、または停止して後で再試行
• robots.txt がパスを禁じる -- 指令を尊重; オーバーライドしない
• IP ban -- スクレイピングをすぐ停止; レート制限が不十分だった。アクセスが正当（パブリックデータ、ToS 許可、robots.txt 尊重）で続けねばならないなら、ネットワーク層エスカレーションには rotate-scraping-proxies を参照

バリデーション

• 正しい fetcher ティアが選ばれている（ターゲットに対して過剰または不足電力でない）
• configure() メソッドが使われている（非推奨コンストラクタ kwargs ではなく）
• CSS セレクタが実際のページ構造と一致する（ページソースに対して検証済み）
• .find() / .find_all() API が使われている（.css_first() または他ライブラリメソッドではなく）
• CAPTCHA 検出が整っている（altcha ページは報告され、リトライされない）
• マルチ URL スクレイピングにレート制限が実装されている
• バルク操作前に robots.txt が確認される
• 抽出データが非空で構造的に正しい

よくある落とし穴

• .find() ではなく .css_first() を使う: scrapling は要素選択に .find() と .find_all() を使う -- .css_first() は別ライブラリに属し AttributeError を発生させる
• DynamicFetcher で開始: 常にまず Fetcher を試して、それからエスカレートする -- DynamicFetcher は完全ブラウザ起動のため 10-50 倍遅い
• configure() の代わりにコンストラクタ kwargs: scrapling v0.4.x はコンストラクタへのオプション渡しを非推奨にした; 常に configure() メソッドを使う
• altcha CAPTCHA の無視: いかなる fetcher ティアも altcha proof-of-work チャレンジを解けない -- 早期に検出し手動指示にフォールバックする
• レート制限なし: サイトが 429 を返さなくても、攻撃的スクレイピングは IP ban またはサービス劣化を引き起こしうる
• 安定セレクタの仮定: ウェブサイト CSS クラスは頻繁に変わる -- 各スクレイピングキャンペーン前に現在のページソースに対してセレクタを検証する

関連スキル

• rotate-scraping-proxies -- クライアントサイドステルスが尽き、IP ban が正当な ToS 許可アクセスをブロックするときのネットワーク層エスカレーション
• use-graphql-api -- サイトが GraphQL エンドポイントを提供するときの構造化 API クエリ（スクレイピングより優先）
• serialize-data-formats -- 抽出データを JSON、CSV、または他のフォーマットに変換
• deploy-searxng -- 複数ソースから結果を集約するセルフホストサーチエンジン
• forage-solutions -- 多様なソースから情報を集めるより広いパターン