web-scraping

インテリジェントな戦略選択によるウェブスクレイピング

このスキルが有効になる場合

ユーザーが次のように依頼したときに自動的に有効になります。

• 「[website] をスクレイピングして」
• 「[site] からデータを抽出して」
• 「[URL] から製品情報を取得して」
• 「[site] のすべてのリンク／ページを探して」
• 「ブロックされています」または「403 エラーが発生しています」（strategies/anti-blocking.md を読み込みます）
• 「これを Apify Actor にして」（apify/ サブディレクトリを読み込みます）
• 「このスクレイパーを本番環境向けにして」

入力の解析

ユーザーの依頼から調査の深さを判断します。

ユーザーの発言	モード	実行するフェーズ
「簡易調査」「ちょっと確認して」「どのフレームワークか」	Quick	Phase 0 のみ
「X をスクレイピングして」「X からデータを抽出して」（デフォルト）	Standard	Phase 0～3 と 5。保護の兆候を検知した場合に限り Phase 4
「完全な調査」「詳細スキャン」「本番スクレイピング」	Full	保護テストを含むすべてのフェーズ（0～5）

デフォルトは Standard モードです。いずれかのフェーズで保護の兆候が見られた場合は、Full に切り替えます。

適応型調査ワークフロー

このスキルでは、品質ゲートを備えた適応型の段階的ワークフローを使用します。各ゲートでは 「十分な情報が得られていますか？」 と確認します。回答が「いいえ」の場合にのみ続行します。

参照先：全体を通して参照するフレームワーク検出テーブルについては、strategies/framework-signatures.md を参照してください。

Phase 0: 簡易評価（curl、ブラウザーなし）

最小限のコストで最大限の情報を収集します。HTTP リクエストは 1 回だけです。

Step 0a: 生の HTML とヘッダーを取得

curl -s -D- -L "https://target.com/page" -o response.html

Step 0b: レスポンスヘッダーを確認

• strategies/framework-signatures.md の「Response Header Signatures」テーブルとヘッダーを照合します
• Server、X-Powered-By、X-Shopify-Stage、Set-Cookie（保護を示すマーカー）を確認します
• HTTP ステータスコードを確認します（200 = アクセス可能、403 = 保護されている、3xx = リダイレクト）

Step 0c: 既知の主要サイトのテーブルを確認

• ドメインを strategies/framework-signatures.md の「Known Major Sites」と照合します
• 一致した場合は、指定されたデータ戦略を使用し、一般的なパターンのスキャンをスキップします

Step 0d: HTML からフレームワークを検出

• 生の HTML を検索し、strategies/framework-signatures.md の「HTML Signatures」テーブルにあるシグネチャを確認します
• __NEXT_DATA__、__NUXT__、ld+json、/wp-content/、data-reactroot を探します

Step 0e: 対象のデータポイントを検索

• ユーザーが求める各データポイントについて、その内容を生の HTML から検索します
• 見つかったデータポイントと見つからなかったデータポイントを記録します
• サイトマップを確認します：curl -s https://[site]/robots.txt | grep -i Sitemap

Step 0f: 保護の兆候を記録

• 403／503 ステータス、Cloudflare のチャレンジ HTML、CAPTCHA 要素、cf-ray ヘッダーを確認します
• Phase 4 に進むかどうかの判断材料として記録します

参照先：Cheerio の利用可能性評価については、strategies/cheerio-vs-browser-test.md を参照してください

品質ゲート A：対象のデータポイントがすべて生の HTML にあり、保護の兆候もありませんか？ → はい：Phase 3（調査結果の検証）に進みます。ブラウザーは不要です。 → いいえ：Phase 1 に進みます。

フェーズ 1：ブラウザーによる偵察（フェーズ 0 で必要な場合のみ）

生の HTML に含まれていないデータポイントを確認する場合、または JavaScript のレンダリングが必要な場合にのみブラウザーを起動します。

ステップ 1a：ブラウザーセッションを初期化する

• proxy_start() → トラフィック傍受プロキシを起動します
• interceptor_chrome_launch(url, stealthMode: true) → 検出回避機能を有効にして Chrome を起動します
• interceptor_chrome_devtools_attach(target_id) → DevTools ブリッジに接続します
• interceptor_chrome_devtools_screenshot() → 視覚的な状態をキャプチャします

ステップ 1b：トラフィックとレンダリング済み DOM をキャプチャする

• proxy_list_traffic() → ページ読み込み後のすべてのトラフィックを確認します
• proxy_search_traffic(query: "application/json") → JSON レスポンスを検索します
• interceptor_chrome_devtools_list_network(resource_types: ["xhr", "fetch"]) → XHR／fetch の呼び出しを確認します
• interceptor_chrome_devtools_snapshot() → アクセシビリティツリー（レンダリング済み DOM）を取得します

ステップ 1c：レンダリング済み DOM で不足しているデータポイントを検索する

• フェーズ 0 で見つからなかった各データポイントを、レンダリング済み DOM で検索します
• strategies/framework-signatures.md の「Framework → Search Strategy」テーブルに記載された、フレームワーク固有の検索方法を使用します
• 検出されたフレームワークに関連するパターンのみを検索します

ステップ 1d：見つかったエンドポイントを調査する

• proxy_get_exchange(exchange_id) → 有望なエンドポイントのリクエスト／レスポンス全体を取得します
• メソッド、ヘッダー、認証、レスポンス構造、ページネーションを記録します

品質ゲート B：対象のすべてのデータポイントを確認できましたか（生の HTML ＋ レンダリング済み DOM ＋ トラフィック）？ → はい：フェーズ 3（調査結果の検証）に進みます。詳細なスキャンは不要です。 → いいえ：不足しているデータポイントのみを対象に、フェーズ 2 に進みます。

フェーズ 2：詳細スキャン（不足しているデータポイントがある場合のみ）

まだ見つかっていないデータポイントを対象に調査します。不足しているもののみを検索します。

ステップ 2a：不足しているデータを探すために操作をテストする

• 各操作の前に proxy_clear_traffic() → API 呼び出しを個別に確認します
• humanizer_click(target_id, selector) → 動的コンテンツの読み込みを実行します
• humanizer_scroll(target_id, direction, amount) → 遅延読み込み／無限スクロールを実行します
• humanizer_idle(target_id, duration_ms) → 遅れて表示されるコンテンツを待ちます
• 各操作の後に proxy_list_traffic() → 新しい API 呼び出しを確認します

ステップ 2b：API を検出する（フレームワークを考慮）

• 検出されたフレームワークに関連するパターンのみを検索します：
  • Next.js → proxy_list_traffic(url_filter: "/_next/data/")
  • WordPress → proxy_list_traffic(url_filter: "/wp-json/")
  • GraphQL → proxy_search_traffic(query: "graphql")
  • 汎用 → proxy_list_traffic(url_filter: "/api/") ＋ proxy_search_traffic(query: "application/json")
• 検出されたフレームワークに該当しないパターンはスキップします

ステップ 2c：ページネーションとフィルタリングをテストする

• ページネーションのデータが不足している場合、または網羅性の評価に必要な場合のみ実施します
• proxy_clear_traffic() → 次のページをクリック → proxy_list_traffic(url_filter: "page=")
• ページネーションの種類（URL ベース、API オフセット、カーソル、無限スクロール）を記録します

品質ゲート C：有用なレポートを作成するのに十分なデータポイントを確認できましたか？ → はい：フェーズ 3 に進みます。 → いいえ：不足分を記録し、フェーズ 3 に進みます（レポートの自己評価で不足しているデータを記載します）。

フェーズ 3：調査結果の検証

主張する抽出方法はすべて検証する必要があります。抽出経路を明示してテストするまでは、データポイントを「発見した」とは言えません。

参照先：検証方法については strategies/cheerio-vs-browser-test.md を参照してください。

ステップ 3a：CSS セレクターを検証する

• Cheerio／セレクターを使った方法ごとに、セレクターが実際の HTML に一致することを確認します
• 生の HTML（curl の出力）またはレンダリング済み DOM（スナップショット）でテストします
• セレクターが別の要素ではなく、正しい値を抽出することを確認します

ステップ 3b：JSON パスを検証する

• JSON からの各抽出（例：__NEXT_DATA__、API レスポンス）について、パスが解決されることを確認します
• JSON を解析し、パスをたどって、期待するデータ型と値が返されることを検証します

ステップ 3c：API エンドポイントを検証する

• 発見した API ごとに、リクエストを再実行します（curl または proxy_get_exchange）
• レスポンスのステータスが 200 であること、期待するデータ構造と正しい値が返されることを確認します
• ページネーションを主張する場合はテストします（少なくともページ 1 とページ 2）

ステップ 3d：失敗した場合は確度を下げるか、再調査する

• セレクターが一致しない場合：別のセレクターを試すか、確度を PARTIAL に下げます
• API が 403 を返す場合：保護要件を記録し、フェーズ 4 で確認する対象としてフラグを立てます
• JSON パスが誤っている場合：JSON 構造を再確認し、パスを修正します

フェーズ 4：保護機能のテスト（条件付き）

参照先：フェーズをスキップするか実行するかの判断ロジック全体については strategies/proxy-escalation.md を参照してください。

次のすべてに該当する場合はフェーズ 4 をスキップします：

• フェーズ 0～2 で保護機能の兆候が検出されていない
• すべてのデータポイントで、抽出方法が検証済みである
• ユーザーが「full recon」を依頼していない

次のいずれかに該当する場合はフェーズ 4 を実行します：

• いずれかのフェーズで 403／チャレンジページが確認された
• 保護機能が強力であることが知られているドメイン
• 大量アクセスまたは本番環境での利用が目的である
• ユーザーが明示的に依頼した

実行する場合：

ステップ 4a：生の HTTP アクセスをテストする

curl -s -o /dev/null -w "%{http_code}" "https://target.com/page"

• 200 → Cheerio が利用可能です。アクセス可能なエンドポイントにブラウザーは不要です
• 403／503 → ステルスブラウザーに切り替えます

ステップ 4b：ステルスブラウザーでテストする（必要な場合）

• フェーズ 1 からすでに実行中です。チャレンジページなしでページが読み込まれたか確認します
• interceptor_chrome_devtools_list_cookies(domain_filter: "cloudflare") → 保護用 Cookie
• interceptor_chrome_devtools_list_storage_keys(storage_type: "local") → フィンガープリントのマーカー
• proxy_get_tls_fingerprints() → TLS フィンガープリントの分析

ステップ 4c：上流プロキシでテストする（必要な場合）

• proxy_set_upstream("http://user:pass@proxy-provider:port")
• プロキシ経由でブロックされたエンドポイントを再テストします
• 各データポイントへのアクセスに必要な最低限のレベルを記録します

ステップ 4d：保護プロファイルを記録する

• どのような保護機能が存在するか、回避に有効だった方法、本番環境のスクレイパーに必要となるもの

フェーズ 5：レポート＋自己批評

インテリジェンスレポートを作成し、不足がないか批判的に確認します。

参照：完全なレポート形式については reference/report-schema.md を参照してください。

ステップ 5a：レポートを作成

• reference/report-schema.md のスキーマ（セクション 1～6）に従います
• すべての戦略に Validated? のステータス（YES / PARTIAL / NO）を記載します
• 発見したすべてのエンドポイントを完全な仕様とともに記載します

ステップ 5b：自己批評

• reference/report-schema.md に従い、セクション 7（Self-Critique）を作成します：
  • 不足事項：見つからなかったデータポイント、その理由、および特定する方法
  • 省略した手順：省略したフェーズと、その品質ゲート上の理由
  • 未検証の主張：PARTIAL または NO としたすべての項目
  • 前提：検証していない事項（例：「カテゴリ間でレイアウトが一貫している」）
  • 陳腐化リスク：地域依存の価格、A/B テストによるレイアウト、セッション固有のコンテンツ
  • 推奨事項：対象を絞った次のステップ（「すべてを再実行する」ではありません）

ステップ 5c：対象を絞った再調査で不足を解消

• 自己批評で解消可能な不足が見つかった場合は、全体を再実行せず、該当するフェーズ／ステップに戻ります
• 例：「価格セレクター未テスト」→ curl を 1 回実行して解析し、ブラウザーを再起動しない
• 結果をレポートに反映します

ステップ 5d：セッションを記録（ブラウザーを使用した場合）

• proxy_session_start(name) → proxy_session_stop(session_id) → proxy_export_har(session_id, path)
• HAR ファイルには、再生用のすべてのトラフィックが記録されます。strategies/session-workflows.md を参照してください

---

実装（偵察後）

偵察レポートが承認されたら、スクレーパーを反復的に実装します。

基本パターン：

1. 推奨されたアプローチを実装します（最小限のコード）
2. 小規模なバッチ（5～10 項目）でテストします
3. データ品質を検証します
4. 全データセットに拡張するか、代替手段に切り替えます
5. ブロックが発生した場合は対処します
6. 堅牢性を高めます（エラー処理、再試行、ログ記録）

参照：実装パターンとコード例については workflows/implementation.md を参照してください

本番環境対応（依頼があった場合）

スクレーパーを本番環境対応の Apify Actor に変換します。

開始のきっかけ：「これを Apify Actor にして」「本番環境対応にして」「Apify にデプロイして」

基本パターン：

1. TypeScript を使用するか確認します（強く推奨）
2. apify create コマンドで初期化します（必須）
3. スクレイピングのロジックを Actor 形式に移植します
4. ローカルでテストしてデプロイします

注：開発中は、proxy-mcp が偵察とトラフィック分析を提供します。本番環境の Actor では、Apify インフラストラクチャ上で Crawlee クローラー（CheerioCrawler／PlaywrightCrawler）を使用してください。

参照：完全なワークフローについては workflows/productionization.md を、Actor 開発ガイドについては apify/ を参照してください

クイックリファレンス

タスク	パターン／コマンド	ドキュメント
偵察	適応型フェーズ 0～5	workflows/reconnaissance.md
フレームワークの検出	ヘッダーと HTML シグネチャの照合	strategies/framework-signatures.md
Cheerio とブラウザーの比較	3 段階テストと早期終了	strategies/cheerio-vs-browser-test.md
トラフィック分析	proxy_list_traffic() + proxy_get_exchange()	strategies/traffic-interception.md
保護機能のテスト	条件に応じたエスカレーション	strategies/proxy-escalation.md
レポート形式	自己批評を含むセクション 1～7	reference/report-schema.md
サイトマップの検索	RobotsFile.find(url)	strategies/sitemap-discovery.md
サイトマップ URL のフィルタリング	RequestList + regex	reference/regex-patterns.md
API の検出	トラフィックのキャプチャ（自動）	strategies/api-discovery.md
DOM スクレイピング	DevTools ブリッジ + 人間化ツール	strategies/dom-scraping.md
HTTP スクレイピング	CheerioCrawler	strategies/cheerio-scraping.md
ハイブリッド方式	サイトマップ + API	strategies/hybrid-approaches.md
ブロックへの対処	ステルスモード + アップストリームプロキシ	strategies/anti-blocking.md
セッションの記録	proxy_session_start() / proxy_export_har()	strategies/session-workflows.md
Proxy-MCP ツール	完全なリファレンス	reference/proxy-tool-reference.md
フィンガープリント設定	ステルス + TLS プリセット	reference/fingerprint-patterns.md
Apify Actor の作成	apify create	apify/cli-workflow.md
テンプレートの選択	Cheerio と Playwright の比較	workflows/productionization.md
入力スキーマ	.actor/input_schema.json	apify/input-schemas.md
Actor のデプロイ	apify push	apify/deployment.md

よく使うパターン

パターン 1：サイトマップベースのスクレイピング

import { RobotsFile, CheerioCrawler, Dataset } from 'crawlee';

// Auto-discover and parse sitemaps
const robots = await RobotsFile.find('https://example.com');
const urls = await robots.parseUrlsFromSitemaps();

const crawler = new CheerioCrawler({
    async requestHandler({ $, request }) {
        const data = {
            title: $('h1').text().trim(),
            // ... extract data
        };
        await Dataset.pushData(data);
    },
});

await crawler.addRequests(urls);
await crawler.run();

完全な例については、examples/sitemap-basic.js を参照してください。

パターン 2：API ベースのスクレイピング

import { gotScraping } from 'got-scraping';

const productIds = [123, 456, 789];

for (const id of productIds) {
    const response = await gotScraping({
        url: `https://api.example.com/products/${id}`,
        responseType: 'json',
    });

    console.log(response.body);
}

完全な例については、examples/api-scraper.js を参照してください。

パターン 3：ハイブリッド（サイトマップ + API）

// Get URLs from sitemap
const robots = await RobotsFile.find('https://shop.com');
const urls = await robots.parseUrlsFromSitemaps();

// Extract IDs from URLs
const productIds = urls
    .map(url => url.match(/\/products\/(\d+)/)?.[1])
    .filter(Boolean);

// Fetch data via API
for (const id of productIds) {
    const data = await gotScraping({
        url: `https://api.shop.com/v1/products/${id}`,
        responseType: 'json',
    });
    // Process data
}

完全な例については、examples/hybrid-sitemap-api.js を参照してください。

ディレクトリの使い方

このスキルでは段階的開示を採用しており、詳細情報はサブディレクトリに整理され、必要なときにのみ読み込まれます。

ワークフロー（実装パターン）

対象：各フェーズの手順を追ったワークフローガイド

• workflows/reconnaissance.md - フェーズ 1 の対話型偵察（重要）
• workflows/implementation.md - フェーズ 4 の反復的な実装パターン
• workflows/productionization.md - フェーズ 5 の Apify Actor 作成ワークフロー

戦略（詳細解説）

対象：特定のスクレイピング手法に関する詳細ガイド

• strategies/framework-signatures.md - フレームワーク検出の参照表（フェーズ 0／1）
• strategies/cheerio-vs-browser-test.md - 早期終了を含む Cheerio とブラウザーの選択テスト
• strategies/proxy-escalation.md - 保護機能のテストをスキップ／実行する条件（フェーズ 4）
• strategies/traffic-interception.md - MITM プロキシによるトラフィックの傍受
• strategies/sitemap-discovery.md - サイトマップの完全ガイド（4 つのパターン）
• strategies/api-discovery.md - API の検索と使用
• strategies/dom-scraping.md - DevTools ブリッジによる DOM スクレイピング
• strategies/cheerio-scraping.md - HTTP のみを使ったスクレイピング
• strategies/hybrid-approaches.md - 戦略の組み合わせ
• strategies/anti-blocking.md - 多層的な検出回避（ステルス、人間化ツール、プロキシ、TLS）
• strategies/session-workflows.md - セッションの記録、HAR エクスポート、再生

例（実行可能なコード）

用途：参照または実行できる動作コード

JavaScript 学習用の例（シンプルな単独スクリプト）：

• examples/sitemap-basic.js - シンプルなサイトマップスクレイパー
• examples/api-scraper.js - API のみを使う方法
• examples/traffic-interception-basic.js - プロキシベースの調査
• examples/hybrid-sitemap-api.js - 組み合わせた方法
• examples/iterative-fallback.js - トラフィック傍受→サイトマップ→API→DOM スクレイピングの順に試す

TypeScript 本番環境向けの例（完全な Actor）：

• apify/examples/basic-scraper/ - サイトマップ + Playwright
• apify/examples/anti-blocking/ - フィンガープリント + プロキシ
• apify/examples/hybrid-api/ - サイトマップ + API（最適）

リファレンス（すぐに参照）

用途：一般的なパターンとトラブルシューティングをすぐに確認

• reference/report-schema.md - インテリジェンスレポートの形式（セクション 1～7 + 自己批評）
• reference/proxy-tool-reference.md - Proxy-MCP ツールリファレンス（80 以上の全ツール）
• reference/regex-patterns.md - 一般的な URL 正規表現パターン
• reference/fingerprint-patterns.md - ステルスモード + TLS フィンガープリントのプリセット
• reference/anti-patterns.md - 避けるべきこと

Apify（本番環境へのデプロイ）

用途：本番環境向け Apify Actor の作成

• apify/README.md - Apify を使うタイミングと方法
• apify/typescript-first.md - Actor に TypeScript を使う理由
• apify/cli-workflow.md - apify create ワークフロー（重要）
• apify/initialization.md - セットアップの完全ガイド
• apify/input-schemas.md - 入力検証のパターン
• apify/configuration.md - actor.json のセットアップ
• apify/deployment.md - テストとデプロイ
• apify/templates/ - TypeScript のボイラープレート

注：各ファイルは単独で完結しており、それぞれ個別に読むことができます。Claude は必要に応じて該当するファイルを参照します。

基本原則

1. リソースを投入する前に評価する

まずは低コストな方法（curl）から始め、必要な場合にのみ段階的に進めます。

• フェーズ 0（curl）からフェーズ 1（ブラウザー）、フェーズ 2（詳細スキャン）の順に進めます
• 品質ゲートにより、データが十分な場合はフェーズをスキップします
• curl ですべて取得できる場合は、ブラウザーを起動しないでください

2. まず検出し、その後関連するパターンを検索する

フレームワークの検出を使って検索範囲を絞り込みます。

• スキャンの前に strategies/framework-signatures.md と照合します
• 該当しないパターンはスキップします（Amazon に __NEXT_DATA__ はありません）
• 主要なサイトは、既知の戦略を直接参照します

3. 想定せず、検証する

抽出方法として主張する内容はすべてテストする必要があります。

• 「HTML 内にテキストが見つかった」だけでは不十分です。動作するセレクターまたはパスが必要です
• フェーズ 3 では、レポートの作成前にすべての検出結果を検証します
• 未検証の主張は、レポートで PARTIAL または NO としてマークされます

4. 反復的な実装

段階的に構築します。

• まずは小規模なテストバッチ（5～10 項目）
• 品質を検証
• 規模を拡大するか、フォールバックする
• 最後に堅牢性を加える

5. 本番環境に対応できるコード

本番環境向けにする際は、次の点に従います。

• TypeScript を使います（強く推奨）
• apify create を使います（手動でセットアップしないでください）
• 適切なエラー処理を追加します
• ロギングとモニタリングを含めます

---

覚えておいてください：まずトラフィック傍受、次にサイトマップ、その次に API、最後に DOM スクレイピングです。

各トピックの詳細なガイダンスについては、上記の該当するサブディレクトリ内のファイルを参照してください。