scrapfly-screenshot

Scrapfly スクリーンショット

Scrapfly Screenshot API を使用して、JavaScript のレンダリングとボット対策の回避に対応した、高品質なウェブページのスクリーンショットを取得します。

使用する場面

• ウェブサイトの全ページまたはビューポートのスクリーンショットを取得する
• CSS セレクターまたは XPath で指定したページ要素のスクリーンショットを撮影する
• ボット対策で保護されたページをレンダリングして、画面をキャプチャする
• さまざまな形式（JPG、PNG、WebP、GIF）でスクリーンショットを生成する
• さまざまな画面解像度でページをテストする

セットアップ

pip install scrapfly-sdk

API キーは環境変数 SCRAPFLY_API_KEY で指定するか、クライアントに直接渡す必要があります。

API リファレンス

エンドポイント： GET https://api.scrapfly.io/screenshot

ScrapflyClient

from scrapfly import ScrapflyClient, ScreenshotConfig
import os

client = ScrapflyClient(key=os.environ["SCRAPFLY_API_KEY"])

ScreenshotConfig のパラメーター

パラメーター	型	デフォルト	説明
url	str	必須	スクリーンショットの対象 URL
format	str または Format	"jpg"	画像形式："jpg"、"png"、"webp"、"gif"（Format 列挙型）
capture	str	"viewport"	キャプチャ範囲："viewport"、"fullpage"、または CSS セレクター／XPath
resolution	str	None	画面の寸法。例："1920x1080"、"375x812"
country	str	None	プロキシの国（ISO 3166-1 alpha-2。例："us"、"de"）
proxy_pool	str	None	プロキシプール："basic"（データセンタープロキシ。Unblocker はオフ）、"unblocker"（レジデンシャルプロキシと Unblocker）、"unblocker_ultra"（同じ構成ですが、対象または独自の料金が設定されたボット対策で利用できる唯一のプール）、または "auto"（API がリクエスト前に対象のプロファイルに基づいてプールを選択します。データセンタープロキシで Unblocker を使うか、対象に必要なプールを選択します。すべての対象で利用できます）。Screenshot API が受け付けるのはこの 4 つのみで、それ以外の値は無視されます。未設定の場合は、API のスクリーンショット用デフォルトが適用されます。スクリーンショットの料金はどのプールでも同じです。0.12.0 より後の scrapfly-sdk リリースでは ScreenshotConfig で利用できます
timeout	int	None	リクエスト全体のタイムアウト（ミリ秒）
rendering_wait	int	1000	ページ読み込み後、キャプチャ前に待機する時間（ミリ秒）
wait_for_selector	str	None	キャプチャ前に、この CSS／XPath セレクターが表示されるまで待機します
options	list[str] または list[Options]	None	スクリーンショットの動作フラグ。例："load_images"、"dark_mode"、"block_banners"、"print_media_format"（Options 列挙型）
auto_scroll	bool	False	キャプチャ前に最下部までスクロールして、遅延読み込みを開始します
js	str	None	キャプチャ前に実行する生の JavaScript（SDK が Base64 エンコードします。最大 16KB）
cache	bool	None	このスクリーンショットリクエストのレスポンスキャッシュを有効にします
cache_ttl	bool または int	None	キャッシュの TTL（有効期間）。cache=True の場合にのみ有効です
cache_clear	bool	None	cache=True の場合、この URL の既存のキャッシュエントリーを消去します
vision_deficiency	str または VisionDeficiency	None	アクセシビリティテスト用に視覚障害をシミュレートします。例："deuteranopia"、"protanopia"、"achromatopsia"（VisionDeficiency 列挙型）
webhook	str	None	非同期のスクリーンショット完了コールバックを受け取る Webhook 名
raise_on_upstream_error	bool	True	上流のページがエラーステータスを返した場合に例外を発生させます

例

ビューポートの基本的なスクリーンショット

from scrapfly import ScrapflyClient, ScreenshotConfig
import os

client = ScrapflyClient(key=os.environ["SCRAPFLY_API_KEY"])

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
))

# Save the screenshot image
with open("screenshot.jpg", "wb") as f:
    f.write(result.image)

PNG 形式の全ページスクリーンショット

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    format="png",
    capture="fullpage",
    auto_scroll=True,
))

with open("fullpage.png", "wb") as f:
    f.write(result.image)

特定の要素のスクリーンショット

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/product/1",
    rendering_wait=5000,
    format="png",
    capture="div.features" # CSS selector
))

with open("element.png", "wb") as f:
    f.write(result.image)

カスタム解像度（モバイル）

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    resolution="375x812",  # iPhone viewport
))

with open("mobile.jpg", "wb") as f:
    f.write(result.image)

バナーのブロックとダークモードを適用したスクリーンショット

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    options=["block_banners", "dark_mode"],
    rendering_wait=2000,
))

with open("clean_dark.jpg", "wb") as f:
    f.write(result.image)

キャプチャ前に動的コンテンツを待機する

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    wait_for_selector="div.products",
    rendering_wait=3000,
))

with open("fully_loaded_screenshot.jpg", "wb") as f:
    f.write(result.image)

地域ターゲティングを使ったスクリーンショット

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    country="de",
    resolution="1920x1080",
))

with open("german_version.jpg", "wb") as f:
    f.write(result.image)

キャプチャ前にJavaScriptを実行する

スクリーンショットを撮影する前に、カスタムJSを実行します（例：ナビバー、Cookieモーダル、サイドバーを削除する）。セレクターは対象のページに合うものに置き換えてください。DevToolsでページを調べ、セレクターを確認できます。

import base64

# Example: remove navbar (adjust selector for your page: nav, header, .navbar, etc.)

js_code = "var el = document.querySelector('.navbar-collapse'); if (el) el.remove();"
js_code = base64.urlsafe_b64encode(js_code.encode('utf-8')).decode('utf-8')

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    js=js_code, # remove the nav bar
    rendering_wait=1000,
))

with open("clean.jpg", "wb") as f:
    f.write(result.image)

エラー処理

from scrapfly.errors import ScrapflyError

try:
    result = client.screenshot(ScreenshotConfig(url="https://web-scraping.dev/products"))
    with open("screenshot.jpg", "wb") as f:
        f.write(result.image)
except ScrapflyError as e:
    print(f"Screenshot failed: {e.message}")

重要な注意事項

• レスポンスのimage属性には、画像の生のバイナリデータが含まれます
• ブラウザーはJPEG形式でキャプチャするため、再エンコードされない形式は"jpg"（デフォルト）のみです。"png"、"webp"、"gif"はキャプチャから変換されるため、ピクセル単位で完全に一致するソースではありません
• capture="fullpage"の場合、遅延読み込み画像を読み込むためにauto_scroll=Trueを推奨します
• block_bannersはCookie同意バナーやオーバーレイポップアップを削除します
• rendering_waitのデフォルトは1000msです。JavaScriptを多用するページでは値を増やしてください
• jsパラメーターの内容は、16KB未満にしてBase64エンコードする必要があります
• スクリーンショットはScrapflyに保存され、レスポンスヘッダーX-Scrapfly-Screenshot-UrlのURLから取得できます
• 独自の料金が発生するターゲットまたはボット対策では、proxy_pool="basic"と"unblocker"を使うとERR::PROXY::UNBLOCKER_ULTRA_REQUIREDが返されます（HTTP 422、課金されません）。proxy_pool="unblocker_ultra"を使ってスクリーンショットを再度送信してください