CloakBrowser CAPTCHAソルバー: CapSolverをPlaywrightブラウザ自動化に統合する方法

TL;DR

• CloakBrowserはPlaywright互換のPython APIを通じてChromiumのビルドを起動し、CapSolverはCAPTCHAタスクを処理してトークンまたは画像認識結果を返します。
• CloakBrowserはCAPTCHA解決サービスではありません。統合では、ブラウザの状態をCloakBrowserで保持し、CapSolverに必要なチャレンジパラメータのみを送信し、同じPlaywrightページを通じて結果を提出します。
• 既存のPlaywrightスクリプトでは、標準のChromiumランチャーをfrom cloakbrowser import launchに置き換える必要があります。
• チャレンジが現在のセッションに関連する場合、ページURL、サイトキー、プロキシ、クッキー、ロケール、ユーザー・エージェントを一貫させてください。
• 返されたトークンは中間結果です。ターゲットページまたは認証されたアプリケーションが受け入れたことを確認するまで、ワークフローを成功と見なさないでください。

CloakBrowserとCapSolverが行うこと

CloakBrowserはPlaywrightおよびPuppeteerの自動化用のChromiumベースのブラウザパッケージです。公式リポジトリでは、キャンバス、WebGL、オーディオ、フォント、GPU、スクリーン、WebRTC、および自動化に関連する挙動などのブラウザシグナルのソースレベルの変更が説明されています。Pythonランチャーは標準的なPlaywright Browserを返すため、new_page()、ロケータ、evaluate()、クリック、フォーム操作などの既知のメソッドが利用可能です。

CloakBrowserはCAPTCHAを解決しません。CapSolverはその別のサービスを提供します。アプリケーションはチャレンジパラメータでタスクを作成し、解決を受けてから、現在のページを使用して送信します。この境界は、ブラウザ環境の管理とCAPTCHA処理が異なる入力と失敗モードを持つため重要です。

責任の範囲は次の通りです：

CloakBrowser
  -> Chromiumを起動し、クッキー、プロキシ、ページ、ブラウザコンテキストを維持
  -> 現在のセッションに表示されるチャレンジパラメータを読み取る

CapSolver
  -> サポートされているタスクタイプと必要なチャレンジパラメータを受信
  -> トークンまたは画像認識結果を返す

Playwright API
  -> 結果を同じページに戻す
  -> 予期されるコールバックを呼び出すか、フォームを送信する
  -> 最終的なページまたはアプリケーションの応答を確認する

2つのサービスを統合する前にPlaywrightの復習が必要な場合、CapSolverのPlaywright用語集とPlaywrightブラウザ自動化ガイドを参照してください。

前提条件

このワークフローは、所有しているまたはテストまたは自動化に許可されているウェブサイトやアプリケーションでのみ使用してください。必要なものは次の通りです：

• Python 3.9以上；
• CloakBrowserのインストールとライセンスまたはサポートされた評価設定；
• CapSolverアカウントとAPIキー；
• 自分が自動化に許可されたページからのターゲットURLとチャレンジパラメータ。

Pythonパッケージをインストールしてください：

pip install cloakbrowser capsolver

CloakBrowserのライセンスについて、現在のリポジトリではcloakbrowser loginをインタラクティブな設定に、CLOAKBROWSER_LICENSE_KEY環境変数をCIまたはサーバーに使用しています。両方のベンダーの資格情報をソースコード管理から外してください。リテラルキーをコミットするよりも、環境変数またはシークレットマネージャーが安全です。

ステップ1: Playwright APIでCloakBrowserを起動する

以下の最小限の例は、ページを開き、そのタイトルを読み取り、ブラウザを閉じます：

from cloakbrowser import launch

browser = launch(
    headless=False,
    humanize=True,
    license_key="cb_...",
)

page = browser.new_page()
page.goto("https://example.com", wait_until="domcontentloaded")
print(page.title())
browser.close()

ランチャーのオプションはブラウザ環境を制御します：

セッションに結びついたチャレンジでは、チャレンジを読み取って解決を送信する間にプロキシ、ユーザー・エージェント、クッキー、またはブラウザコンテキストを変更しないでください。CapSolverのウェブセキュリティにおけるブラウザファINGERPRINTINGに関するFAQでは、複数のブラウザシグナルが一緒に評価される理由が説明されています。

ステップ2: CapSolver reCAPTCHA v2タスクを作成する

基本的なPython SDKのフローではAPIキーを設定し、サポートされているタスクオブジェクトを送信します。この例ではGoogleの公開reCAPTCHA v2デモ値を使用します：

import capsolver

capsolver.api_key = "CAP-..."

solution = capsolver.solve(
    {
        "type": "ReCaptchaV2TaskProxyLess",
        "websiteURL": "https://www.google.com/recaptcha/api2/demo",
        "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    }
)

token = solution.get("gRecaptchaResponse")
if not isinstance(token, str) or not token:
    raise RuntimeError(f"CapSolver did not return a reCAPTCHA token: {solution}")

print("Token received")

重要なフィールドは次の通りです：

本番環境へのデプロイ前に現在のCapSolver reCAPTCHA v2ドキュメントを確認し、デモパラメータではなくアクティブなページからの値を使用してください。より詳細なタスク選択と応答フィールドについては、reCAPTCHA v2解決ガイドをご覧ください。

CapSolverボーナスコードを取得する

自動化予算を即座に増やす！
CapSolverアカウントにチャージする際にボーナスコード CAP26 を使用すると、すべてのチャージで 5%のボーナス を受け取れます — 制限なし。
今すぐCapSolverダッシュボードで取得してください

ステップ3: 同じCloakBrowserページを通じてトークンを戻す

以下の完全なデモは、ナビゲーションとトークンの送信を1つのCloakBrowserページ内で保持します。CSSセレクタと送信動作は公開デモに特化しています。実際のアプリケーションではコールバック、フレームワーク管理のフィールド、または他のフォームフローを使用する可能性があります。

import re

import capsolver
from cloakbrowser import launch


def inject_recaptcha_token(page, token):
    if not isinstance(token, str) or not token:
        raise ValueError("A non-empty reCAPTCHA token is required")

    page.evaluate(
        """
        (token) => {
            const textarea = document.getElementById('g-recaptcha-response');
            if (!textarea) {
                throw new Error('g-recaptcha-response was not found');
            }
            textarea.value = token;
        }
        """,
        token,
    )

    with page.expect_navigation(
        wait_until="domcontentloaded",
        timeout=30_000,
    ):
        page.click("#recaptcha-demo-submit")

    return page.content()


def main():
    capsolver.api_key = "CAP-..."  # YOUR_CAPSOLVER_API_KEY

    browser = launch(
        license_key="cb_...",  # YOUR_CLOAKBROWSER_LICENSE_KEY
        headless=False,
        locale="en-US",
    )

    try:
        page = browser.new_page()
        page.goto(
            "https://www.google.com/recaptcha/api2/demo",
            wait_until="domcontentloaded",
            timeout=60_000,
        )

        solution = capsolver.solve(
            {
                "type": "ReCaptchaV2TaskProxyLess",
                "websiteURL": page.url,
                "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
            }
        )

        token = solution.get("gRecaptchaResponse")
        result_page = inject_recaptcha_token(page, token)

        match = re.search(
            r'<div class="recaptcha-success">(.*?)</div>',
            result_page,
        )
        print(match.group(1) if match else "Verification failed")
    finally:
        browser.close()


if __name__ == "__main__":
    main()

通常のPythonスクリプトとして実行してください：

python cloakbrowser-capsolver.py

本番環境では、キーを環境変数から読み込み、一時的なAPIまたはナビゲーションの失敗に対してバウンドされたリトライを追加し、セキュリティをログに記録せずにCapSolverタスクIDをロギングし、最終的なビジネス結果を検証してください。CapSolverは、PlaywrightまたはPuppeteerにCAPTCHA解決を統合する方法に関する焦点を当てたFAQも提供しています。

ステップ4: ImageToTextTaskで画像CAPTCHAを処理する

一部の許可されたテストワークフローでは、トークンベースのウィジェットではなく画像としてCAPTCHAが公開されることがあります。その場合、画像をキャプチャまたは抽出し、Data URLプレフィックスなしでBase64に変換してImageToTextTaskに送信してください。

元のワークフローからのスクリーンショットは、BotDetectの特徴デモの画像要素と入力フィールドを示しています：

import capsolver
from cloakbrowser import launch


TARGET_URL = "https://captcha.com/demos/features/captcha-demo.aspx"

browser = launch(headless=False, humanize=True)

try:
    page = browser.new_page()
    page.goto(TARGET_URL, wait_until="domcontentloaded")

    image_src = page.locator("#demoCaptcha_CaptchaImage").get_attribute("src")
    if not image_src or "," not in image_src:
        raise RuntimeError("Captcha image is not a Data URL")

    base64_image = image_src.split(",", 1)[1].replace("\n", "")

    solution = capsolver.solve(
        {
            "type": "ImageToTextTask",
            "websiteURL": page.url,
            "module": "common",
            "body": base64_image,
        }
    )

    text = solution.get("text")
    if not isinstance(text, str) or not text:
        raise RuntimeError(f"CapSolver did not return OCR text: {solution}")

    page.locator("#captchaCode").fill(text)
    page.locator("#validateCaptchaButton").click()
finally:
    browser.close()

セレクタは意図的にデモページに結びついています。許可されたターゲットページを検証し、実際の画像、入力、および送信セレクタを使用してください。

複数の画像と数値モジュール

ImageToTextTaskはサポートされている画像形式のための異なるモジュールを使用できます。元の記事にはこのモジュールの概要が含まれており、参照のためにここに保存されています：

サポートされているモジュールが複数の画像を受け入れる場合、そのモジュールでドキュメント化された配列を送信し、対応する答えを読み取ってください：

solution = capsolver.solve(
    {
        "type": "ImageToTextTask",
        "module": "number",
        "images": [base64_image],
    }
)

answers = solution["answers"]

モジュール名、リクエストフィールド、およびサポートされている形式は変更される可能性があるため、現在のImageToTextTaskドキュメントと確認してください。より広範なPython APIパターンについては、PythonでCAPTCHA解決APIを統合する方法を参照してください。

reCAPTCHA v3では何が変わるのか？

ブラウザアーキテクチャは同じですが、CapSolverのタスクとページパラメータはv3の実装に一致する必要があります。特に以下の点に注意してください：

1. CapSolverがドキュメント化したサポートされているreCAPTCHA v3タスクタイプを使用してください。
2. 統合でアクション値が使用されている場合、そのアクション値を提供してください。
3. 他の例ではなく、アクティブなページからURLとサイトキーを読み取ってください。
4. トークンを同じブラウザセッションに保持し、期限切れになる前に送信してください。
5. アプリケーションの応答を確認してください。APIから返されたスコアまたはトークンがターゲットアプリケーションがリクエストを受容したことを保証するものではありません。

トークンを送信するために元のクッキーとセッション状態なしで新しいページを開かないでください。これにより、ターゲットアプリケーションが結果を評価するために使用するコンテキストが破損します。

CloakBrowserとCapSolverのトラブルシューティング

スクリプトが標準のPlaywright Chromiumを起動する

このコードはCloakBrowserではなく、Playwrightのバンドル済みChromiumを起動します：

from playwright.sync_api import sync_playwright

pw = sync_playwright().start()
browser = pw.chromium.launch()

代わりにCloakBrowserのランチャーを使用してください：

from cloakbrowser import launch

browser = launch()

CloakBrowserリポジトリによると、Linuxで共有システムライブラリが不足している場合、playwright install-deps chromiumが役立ちます。playwright install chromiumを実行すると、Playwrightのブラウザをダウンロードするだけで、CloakBrowserの起動パスを修復しません。

CapSolverがトークンを返すが、ページが拒否する

各境界を順番に確認してください：

• websiteURLはアクティブなページで使用される完全なURL；
• websiteKeyはそのページに属する；
• 選択されたタスクタイプとオプションのアクションはチャレンジに一致する；
• トークンは予期されたフィールドに書き込まれるか、ページのコールバックに渡される；
• ページは再読み込みされてチャレンジが置き換えられていない；
• クッキー、プロキシ、ユーザー・エージェント、ブラウザコンテキストは一貫している；
• 最終的なページまたはアプリケーションの応答が受け入れを確認する。

画像タスクがテキストを返さない

画像のボディが有効なBase64であることを確認し、Data URLプレフィックスが削除されていることを確認し、選択されたモジュールが画像をサポートしていることを確認してください。応答フィールドが現在のドキュメントと一致していることを確認してください。デバッグのためにCapSolverのエラーコードとタスクIDをキャプチャしてください。APIキーまたは機密ページデータをログに記録しないでください。

送信後にナビゲーションが永遠に待機する

すべての送信が完全なナビゲーションを引き起こすとは限りません。一部のサイトではDOMが更新されるか、XHRリクエストが行われます。expect_navigation()を、実際の成功を表す条件に置き換えてください。ロケータが表示される、URLが変更される、応答イベント、またはアプリケーション固有のステータス要素などです。Playwrightの公式ブラウザAPIリファレンスが現在のAPI動作の最良のソースです。
CAPTCHAシステムはアクセス制御および不正防止メカニズムです。所有するシステムまたは明示的な許可を得たシステムでの法的な自動化にのみ、CapSolverとCloakBrowserを使用してください。サイトの利用規約、レートリミット、プライバシー要件、および適用可能な法律を尊重してください。プライベートデータへのアクセス、不正なトラフィックの作成、または他のユーザーへの干渉のために自動化を使用しないでください。

品質保証（QA）およびモニタリングの目的で、利用可能な場合は専用のテスト環境およびプロバイダーのテストキーを使用してください。失敗を追跡するために、ページURL、タスクタイプ、タスクID、経過時間、および最終的なアプリケーションの状態を記録してください。認証情報や個人データは保存しないでください。QAテスト用のCAPTCHA自動化ガイドには、制御されたテストワークフローの追加パターンが記載されています。

CapSolverで信頼性の高い自動ワークフローを構築する

CloakBrowserはPlaywright互換のブラウザ環境を提供し、CapSolverはサポートされているCAPTCHAタスクを処理します。これらの責任を分離することで、ワークフローをテストしやすくなります。アクティブなページからチャレンジを読み取り、対応する解決策をリクエストし、同じコンテキストで送信し、アプリケーションの結果を検証します。

公式サイトでCapSolverを試すことで、認証されたCloakBrowserまたはPlaywrightワークフローを実行してください。デモコードを本番環境に移す前に、現在のドキュメンテーションを確認してください。

よくある質問

Q: クロークブラウザはCAPTCHAソルバーですか？

いいえ。クロークブラウザはChromiumブラウザとPlaywright互換の自動化インターフェースを提供します。サポートされているCAPTCHAタスクは、CapSolverなどの別サービスが処理します。

Q: 既存のPlaywrightスクリプトでクロークブラウザを使用できますか？

通常は可能です。ブラウザの起動パスを from cloakbrowser import launch に置き換え、その後に返されるPlaywrightの Browser、ページ、ロケーター、評価メソッドをそのまま使用してください。環境でブラウザ固有のオプションと依存関係をテストしてください。

Q: なぜCAPTCHAの結果を同じブラウザコンテキストで送信しなければならないのですか？

ターゲットアプリケーションは、チャレンジをクッキー、プロキシアドレス、ブラウザシグナル、URL、または他のセッションデータに関連付ける可能性があります。コンテキストを切り替えると、通常は有効なチャレンジパラメータが不一致になることがあります。

Q: reCAPTCHAのサイトキーはどこで見つかりますか？

自動化が許可されているページに設定されたキーを使用してください。ウィジェットのマーカップやページスクリプトに表示される場合があります。関係のないチュートリアルやドメインからキーをコピーしないでください。

Q: CapSolverのトークンは成功を保証しますか？

いいえ。トークンは中間結果です。最終的な成功条件は、トークンが適切かつ適時に送信された後のターゲットページまたはアプリケーションからの応答です。

Q: この統合は画像CAPTCHAを処理できますか？

CapSolverの ImageToTextTask はドキュメント化された画像認識モジュールをサポートしています。認証されたページの画像を抽出し、必要なBase64ペイロードを送信し、同じクロークブラウザページで返されたテキストを入力してください。

Q: APIおよびライセンスキーはスクリプトに表示すべきですか？

いいえ。例では認識可能なプレースホルダーを使用しています。本番コードでは、シークレットを環境変数またはシークレットマネージャーから読み込み、ソースコードにコミットしてはいけません。

Q: この統合を安全にテストするにはどうすればよいですか？

プロバイダーのデモまたは自身が制御するアプリケーションから始めましょう。制限付きのリクエストレートを使用し、タスクIDと最終的な結果を記録してください。認証と明確な運用上の必要性がある場合にのみ、本番サイトに移行してください。