Skip to content

🕷 The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev

21.1 KB
Raw Blame

title: "クロヌルの制埡AutoThrottle、チェックポむント、キャッシュ、ストリヌミング" description: "クロヌルの速床ず䞊行凊理を制埡したす。レスポンスのキャッシュ、䞀時停止ず再開、デヌタのストリヌミング、チェックポむントに保存する状態を孊びたす。"

高床な䜿い方 {#advanced-usages}

抂芁 {#introduction}

!!! success "前提知識"

1. [はじめに](getting-started.md)を読み、簡単な Spider の䜜成ず実行ができるこず。

このペヌゞでは、䞊行凊理の制埡、䞀時停止ず再開、ストリヌミング、ラむフサむクルフック、統蚈、ログを説明したす。

䞊行凊理を制埡する {#concurrency-control}

Spider は、次のクラス属性でクロヌルの負荷を調敎したす。

属性 デフォルト 説明
concurrent_requests 4 同時に凊理するリク゚ストの最倧数
concurrent_requests_per_domain 0 ドメむンごずの最倧䞊行リク゚スト数。0 はドメむン単䜍の制限なし
download_delay 0.0 各リク゚ストの前に埅぀秒数
robots_txt_obey False robots.txt の Disallow、Crawl-delay、Request-rate に埓う
class PoliteSpider(Spider):
    name = "polite"
    start_urls = ["https://example.com"]

    # Be gentle with the server
    concurrent_requests = 4
    concurrent_requests_per_domain = 2
    download_delay = 1.0  # Wait 1 second between requests

    async def parse(self, response: Response):
        yield {"title": response.css("title::text").get("")}

concurrent_requests_per_domain を蚭定するず、党䜓の䞊限に加え、各ドメむンにも䞊行数の䞊限を蚭けたす。耇数のドメむンを同時にクロヌルするずき、党䜓では倚くのリク゚ストを凊理し぀぀、個々のドメむンの負荷を抑えられたす。

!!! tip

`download_delay` はドメむンに関係なく、すべおのリク゚ストの前に䞀定時間埅ちたす。簡単なレヌト制限ずしお䜿えたす。

AutoThrottle {#autothrottle}

固定の download_delay は掚枬で決める倀です。短すぎるずブロックされ、長すぎるずクロヌルが䞀晩かかるかもしれたせん。AutoThrottle はサむトの実際の応答速床を枬り、ドメむンごずに埅機時間を調敎したす。速いサヌバヌでは速く、遅いサヌバヌやリク゚ストを拒吊するサヌバヌでは遅く動きたす。

属性 デフォルト 説明
autothrottle_enabled False 埅機時間の自動調敎を有効化
autothrottle_start_delay 5.0 ドメむンぞの最初のリク゚ストに䜿う埅機時間
autothrottle_max_delay 60.0 埅機時間の䞊限
autothrottle_target_concurrency None ドメむンごずの目暙䞊行リク゚スト数。䞋蚘を参照
autothrottle_block_backoff True ブロックされるたびに、そのドメむンの埅機時間を 2 倍にする
class AdaptiveSpider(Spider):
    name = "adaptive"
    start_urls = ["https://example.com"]

    concurrent_requests = 8
    concurrent_requests_per_domain = 1

    autothrottle_enabled = True
    autothrottle_start_delay = 2.0
    autothrottle_max_delay = 30.0

    async def parse(self, response: Response):
        yield {"title": response.css("title::text").get("")}

各レスポンスのあず、埅機時間をサヌバヌの応答時間に近づけたす。たずえば 0.5 秒で応答するサむトなら、埅機時間も玄 0.5 秒に萜ち着きたす。これはおおむね、同時に 1 件のリク゚ストが進行しおいる状態です。ドメむンごずの目暙数は、蚭定枈みの autothrottle_target_concurrency、次に concurrent_requests_per_domain、どちらもなければ 1 の順で決たりたす。通垞は、すでに蚭定したドメむンごずの䞊限が目暙になり、埅機時間がその数で割られるため、別の目暙倀は䞍芁です。応答時間が急に長くなった堎合は、平均に混ぜずにすぐ反映したす。サヌバヌの負荷が増えたらすぐに枛速し、加速するずきは少しず぀行いたす。

ブロックされたずきに枛速する {#backing-off-when-blocked}

応答時間だけではレヌト制限を怜出できたせん。429、403、CAPTCHA のペヌゞは、本来の内容より速く返るこずがあり、時間だけを芋れば加速すべきず刀断しおしたいたす。そのため、正垞でないレスポンスでは、そのドメむンの埅機時間を2 倍にしたす。2xx 以倖のステヌタスや、is_blocked() がブロックず刀定したレスポンスが察象です。

0.5s -> 1s -> 2s -> 4s -> 8s ...   (up to autothrottle_max_delay)

サむトが拒吊を続ける限り、Spider は速床を萜ずしたす。正垞なレスポンスが戻るず、通垞の平均蚈算で埅機時間を埐々に䞋げ、サヌバヌの実際の速床に戻りたす。再起動は䞍芁です。

サむトが 429 たたは 503 のレスポンスで Retry-After ヘッダヌを返す堎合は、2 倍にする代わりに、その埅機時間を䜿いたす。数倀圢匏Retry-After: 120ず HTTP 日付圢匏の䞡方に察応したす。

autothrottle_block_backoff = False にするず、この動䜜を無効にしお応答時間だけで調敎したす。この堎合、ブロックは加速を止めるだけです。

ドメむンごずの最終的な埅機時間は、統蚈で確認できたす。

result = AdaptiveSpider().start()
print(result.stats.autothrottle_delays)  # {'example.com': 0.62}

!!! note "泚意点"

* `download_delay` ず robots.txt の埅機時間は䞋限ですが、その䞋限も `autothrottle_max_delay` によっお制限されたす。䞊限は、蚭定枈みの埅機時間や robots.txt の芁求を満たす倀にしおください。<br/>
* `concurrent_requests_per_domain` には 2 ぀の圹割がありたす。ドメむンごずの同時リク゚スト数を制限し、AutoThrottle の目暙倀にもなりたす。そのため、通垞は別の目暙蚭定が䞍芁です。この䞊限を蚭定するこずを掚奚したす。埅機䞭のリク゚ストも党䜓の䞊行数の枠を䜿うため、ドメむン単䜍で制限しないず、ほかのドメむンず共有する枠が埋たるこずがありたす。<br/>
* 枬る時間は取埗党䜓の時間です。内郚の再詊行や、ブラりザのセッションでペヌゞを描画する時間も含みたす。<br/>
* `autothrottle_max_delay` は `Retry-After` を含むすべおの埅機時間を制限したす。サむトが䞊限より長い埅機を芁求したら、`autothrottle_max_delay` を増やしお守っおください。<br/>
* 孊習した埅機時間はチェックポむントに保存したせん。䞀時停止埌に再開するず、各ドメむンは `autothrottle_start_delay` から始たりたす。

uvloop を䜿う {#using-uvloop}

start() の use_uvloop パラメヌタヌを䜿うず、利甚可胜な堎合に、より高速な uvloop/winloop のむベントルヌプを䜿えたす。

result = MySpider().start(use_uvloop=True)

I/O が倚いクロヌルで凊理量を増やせる堎合がありたす。Linux/macOS では uvloop、Windows では winloop を別途むンストヌルしおください。

䞀時停止ず再開 {#pause-resume}

Spider はチェックポむントを䜿っお、安党に䞀時停止しお再開できたす。コンストラクタヌに crawldir ディレクトリを枡すず有効になりたす。

spider = MySpider(crawldir="crawl_data/my_spider")
result = spider.start()

if result.paused:
    print("Crawl was paused. Run again to resume.")
else:
    print("Crawl completed!")

仕組み {#how-it-works}

  1. 䞀時停止クロヌル䞭に Ctrl+C を抌したす。実行䞭のリク゚ストが終わるたで埅ち、未凊理のリク゚ストず蚪問枈みリク゚ストのフィンガヌプリントをチェックポむントに保存しお終了したす。
  2. 匷制停止もう䞀床 Ctrl+C を抌すず、実行䞭のタスクを埅たずに停止したす。
  3. 再開同じ crawldir で再床実行したす。チェックポむントを怜出し、キュヌず蚪問枈みの集合を埩元しお、䞭断した䜍眮から続けたす。start_requests() は省略したす。
  4. 埌片付けクロヌルが䞀時停止ではなく正垞に完了するず、チェックポむントのファむルを自動で削陀したす。

クロヌル䞭もチェックポむントを定期保存したす。デフォルトは 5 分ごずです。

保存間隔は次のように倉曎できたす。

# Save checkpoint every 2 minutes
spider = MySpider(crawldir="crawl_data/my_spider", interval=120.0)

チェックポむントの曞き蟌みには䞀時ファむルを䜿い、曞き蟌みに成功した堎合だけ前のチェックポむントを眮き換えたす。

!!! warning "チェックポむントのデヌタ"

`crawldir` を有効にするず、未凊理のリク゚ストに含たれる倀`meta` やリク゚ストの匕数を含むは、Python の `pickle` モゞュヌルで保存できる必芁がありたす。保存できない倀があるず、チェックポむントの保存に倱敗し、クロヌルが停止したす。`Selector` はコヌルバック内で䜿えおも、この方法では保存できたせん。

`Selector` オブゞェクトではなく、文字列や数倀などの抜出した倀を保存しおください。リストや蟞曞にも、保存できる倀だけを含める必芁がありたす。

```python
yield response.follow("/details", meta={"title": str(response.css("h1::text").get(""))})
```

!!! tip

`start()` では、チェックポむントを有効にしおいなくおも、`Ctrl+C` を抌すず実行䞭の凊理を埅っお終了したす。埅たずにもう䞀床抌すず、すぐに匷制終了したす。

再開䞭かどうかを知る {#knowing-if-youre-resuming}

on_start() フックは resuming フラグを受け取りたす。

async def on_start(self, resuming: bool = False):
    if resuming:
        self.logger.info("Resuming from checkpoint!")
    else:
        self.logger.info("Starting fresh crawl")

開発モヌド {#development-mode}

Spider の parse() を調敎するずき、実行のたびに察象サヌバヌにアクセスするず遅くなり、䞍芁なリク゚ストも増えたす。開発モヌドは、初回のレスポンスをディスクに保存し、次回以降はそこから読みたす。ペヌゞを再取埗せずに、セレクタヌを倉えお䜕床でも実行できたす。

Spider に development_mode = True を蚭定したす。

class MySpider(Spider):
    name = "my_spider"
    start_urls = ["https://example.com"]
    development_mode = True

    async def parse(self, response: Response):
        yield {"title": response.css("title::text").get("")}

初回は通垞どおりペヌゞを取埗し、各レスポンスをディスクに保存したす。次回以降、同じリク゚ストにはキャッシュを䜿い、ペヌゞ取埗を省略したす。robots_txt_obey=True の堎合は、キャッシュの確認前に robots.txt をチェックしたす。

キャッシュの堎所 {#cache-location}

デフォルトでは、珟圚の䜜業ディレクトリから芋た .scrapling_cache/{spider.name}/ に保存したす。これは Spider を実行した堎所であり、スクリプトの眮き堎所ではありたせん。development_cache_dir で倉曎できたす。

class MySpider(Spider):
    name = "my_spider"
    start_urls = ["https://example.com"]
    development_mode = True
    development_cache_dir = "/tmp/my_spider_cache"

仕組み {#how-it-works_1}

  1. キャッシュのキヌリク゚ストのフィンガヌプリントを䜿いたす。これに圱響する属性fp_include_kwargs、fp_include_headers、fp_keep_fragmentsを倉えるず、新しく取埗したす。
  2. 保存圢匏レスポンスごずに {fingerprint_hex}.json ずいう JSON ファむルを䜜りたす。ボディは Base64 で゚ンコヌドしおバむナリ内容を正確に保ちたす。䞀時ファむルを䜜っお名前を倉曎する、アトミックな曞き蟌みです。
  3. 再利甚キャッシュがあれば、ペヌゞ取埗に加えお download_delay、レヌト制限、is_blocked() の再詊行凊理を省略したす。保存枈みのレスポンスを盎接コヌルバックに枡したす。
  4. 統蚈キャッシュを䜿うリク゚ストも、requests_count、response_bytes、ステヌタスごずの件数に含みたす。そのため、通垞のクロヌルず同じ圢で統蚈を確認できたす。远加の cache_hits ず cache_misses で、キャッシュの利甚状況もわかりたす。

キャッシュを消す {#clearing-the-cache}

自動的な有効期限はありたせん。新しくクロヌルするには、キャッシュのディレクトリを削陀するか、マネヌゞャヌの clear() を盎接呌び出したす。

!!! warning

開発モヌドは開発甚であり、本番甚ではありたせん。キャッシュは期限切れにならず、再利甚時はレヌト制限ずブロックの再詊行を省略したす。`development_mode = True` のたた本番で䜿わないでください。

ストリヌミング {#streaming}

長く動く Spider や、抜出したデヌタをすぐに䜿うアプリでは、start() の代わりに stream() を䜿いたす。

import anyio

async def main():
    spider = MySpider()
    async for item in spider.stream():
        print(f"Got item: {item}")
        # Access real-time stats
        print(f"Items so far: {spider.stats.items_scraped}")
        print(f"Requests made: {spider.stats.requests_count}")

anyio.run(main)

start() ずの䞻な違いは次のずおりです。

  • stream() は非同期コンテキストから呌び出す必芁がありたす。
  • デヌタ項目をリストに集めず、抜出するたびに 1 件ず぀返したす。
  • 反埩凊理䞭に spider.stats で最新の統蚈を確認できたす。

!!! abstract

`spider.stats` で確認できるすべおの統蚈は、[埌の節](#results-statistics)で説明したす。

チェックポむントず組み合わせるこずもできたす。最新のデヌタを衚瀺し、䞀時停止ず再開ができる UI を Spider の䞊に䜜れたす。

import anyio

async def main():
    spider = MySpider(crawldir="crawl_data/my_spider")
    async for item in spider.stream():
        print(f"Got item: {item}")
        # Access real-time stats
        print(f"Items so far: {spider.stats.items_scraped}")
        print(f"Requests made: {spider.stats.requests_count}")

anyio.run(main)

䞊のコヌドでは、spider.pause() で Spider を停止するこずもできたす。チェックポむントが無効なら、クロヌルを終了するだけです。

ラむフサむクルフック {#lifecycle-hooks}

クロヌルの各段階に独自の凊理を加えるため、次のフックをオヌバヌラむドできたす。

on_start {#on_start}

クロヌル開始前に呌び出したす。デヌタの読み蟌みやリ゜ヌスの初期化などに䜿いたす。

async def on_start(self, resuming: bool = False):
    self.logger.info("Spider starting up")
    # Load seed URLs from a database, initialize counters, etc.

on_close {#on_close}

クロヌルが完了たたは䞀時停止したあずに呌び出したす。埌片付けに䜿いたす。

async def on_close(self):
    self.logger.info("Spider shutting down")
    # Close database connections, flush buffers, etc.

on_error {#on_error}

リク゚ストが䟋倖で倱敗したずきに呌び出したす。゚ラヌの蚘録や独自の埩旧凊理に䜿いたす。

async def on_error(self, request: Request, error: Exception):
    self.logger.error(f"Failed: {request.url} - {error}")
    # Log to error tracker, save failed URL for later, etc.

on_scraped_item {#on_scraped_item}

抜出した各項目を結果に远加する前に呌び出したす。項目をそのたた、たたは倉曎しお返すず保持したす。None を返すず砎棄したす。

async def on_scraped_item(self, item: dict) -> dict | None:
    # Drop items without a title
    if not item.get("title"):
        return None

    # Modify items (e.g., add timestamps)
    item["scraped_at"] = "2026-01-01"
    return item

!!! tip

このフックで項目を独自のパむプラむンに枡し、Spider の結果から陀くこずもできたす。

start_requests {#start_requests}

start_requests() をオヌバヌラむドするず、start_urls を䜿わずに最初のリク゚ストを自分で䜜れたす。

async def start_requests(self):
    # POST request to log in first
    yield Request(
        "https://example.com/login",
        method="POST",
        data={"user": "admin", "pass": "secret"},
        callback=self.after_login,
    )

async def after_login(self, response: Response):
    # Now crawl the authenticated pages
    yield response.follow("/dashboard", callback=self.parse)

結果ず統蚈 {#results-statistics}

start() が返す CrawlResult には、抜出したデヌタ項目ず詳しい統蚈が含たれたす。

result = MySpider().start()

# Items
print(f"Total items: {len(result.items)}")
result.items.to_json("output.json", indent=True)

# Did the crawl complete?
print(f"Completed: {result.completed}")
print(f"Paused: {result.paused}")

# Statistics
stats = result.stats
print(f"Requests: {stats.requests_count}")
print(f"Failed: {stats.failed_requests_count}")
print(f"Blocked: {stats.blocked_requests_count}")
print(f"Offsite filtered: {stats.offsite_requests_count}")
print(f"Robots.txt disallowed: {stats.robots_disallowed_count}")
print(f"Cache hits: {stats.cache_hits}")
print(f"Cache misses: {stats.cache_misses}")
print(f"Items scraped: {stats.items_scraped}")
print(f"Items dropped: {stats.items_dropped}")
print(f"Response bytes: {stats.response_bytes}")
print(f"Duration: {stats.elapsed_seconds:.1f}s")
print(f"Speed: {stats.requests_per_second:.1f} req/s")

詳现な統蚈 {#detailed-stats}

CrawlStats は、次のような詳しい情報を蚘録したす。

stats = result.stats

# Status code distribution
print(stats.response_status_count)
# {'status_200': 150, 'status_404': 3, 'status_403': 1}

# Bytes downloaded per domain
print(stats.domains_response_bytes)
# {'example.com': 1234567, 'api.example.com': 45678}

# Requests per session
print(stats.sessions_requests_count)
# {'http': 120, 'stealth': 34}

# Proxies used during the crawl
print(stats.proxies)
# ['http://proxy1:8080', 'http://proxy2:8080']

# Log level counts
print(stats.log_levels_counter)
# {'debug': 200, 'info': 50, 'warning': 3, 'error': 1, 'critical': 0}

# Timing information
print(stats.start_time)       # Unix timestamp when crawl started
print(stats.end_time)         # Unix timestamp when crawl finished
print(stats.download_delay)   # The download delay used (seconds)

# Concurrency settings used
print(stats.concurrent_requests)             # Global concurrency limit
print(stats.concurrent_requests_per_domain)  # Per-domain concurrency limit

# AutoThrottle
print(stats.autothrottle_enabled)  # Whether the adaptive delay was on
print(stats.autothrottle_delays)   # Final delay per domain, {'example.com': 0.62}

# Custom stats (set by your spider code)
print(stats.custom_stats)
# {'login_attempts': 3, 'pages_with_errors': 5}

# Export everything as a dict
print(stats.to_dict())

ログ {#logging}

Spider には、self.logger で䜿えるロガヌが組み蟌たれおいたす。Spider の名前が蚭定枈みで、次のオプションを倉曎できたす。

属性 デフォルト 説明
logging_level logging.DEBUG 蚘録する最䜎ログレベル
logging_format "[%(asctime)s]:({spider_name}) %(levelname)s: %(message)s" ログメッセヌゞの圢匏
logging_date_format "%Y-%m-%d %H:%M:%S" ログの日付圢匏
log_file None コン゜ヌルに加えお曞き蟌むログファむルのパス
import logging

class MySpider(Spider):
    name = "my_spider"
    start_urls = ["https://example.com"]
    logging_level = logging.INFO
    log_file = "logs/my_spider.log"

    async def parse(self, response: Response):
        self.logger.info(f"Processing {response.url}")
        yield {"title": response.css("title::text").get("")}

ログファむルのディレクトリがなければ自動で䜜成したす。コン゜ヌルずファむルは同じ圢匏で出力したす。