CAPTCHA ソリューションと Playwright APIRequestContext を併用する

1. 1.

   依存関係をインストールする

   Node.js 22+を使い、playwrightパッケージをインストールしてください。公式JavaScript SDKは、solvethree.comの/downloads/にあるsolvethreeのバージョン0.1.0のtarball、solvethree-sdk-0.1.0.tgzからインストールしてください。インポート名は@solvethree/sdkです。レジストリでリリースされているとは限りません。

2. 2.

   環境変数を設定する

   Node.jsプロセスにSOLVETHREE_API_KEY、SOLVETHREE_PROXY、TARGET_URLを渡してください。ワークスペースのAPIキーはサーバー側で保持してください。TARGET_URLには、CAPTCHAを表示するページではなく、アプリケーションの実際のPOSTエンドポイントを指定する必要があります。プロキシURLには、パス、クエリ、フラグメントを含まないHTTPまたはHTTPSのURLを使ってください。

3. 3.

   サイトプロファイルとアクションを確認する

   対象のホスト名には、ワークスペースで利用できる有効なプロファイルが必要です。解決を実行する前にコンソールで設定してください。ホスト名を渡すだけではプロファイルは作成されません。この例ではアクションにloginを使っています。対象が別のアクションを要求する場合は変更してください。リクエストのデフォルトはreCAPTCHA Enterprise v3です。

この例を実行する前に、アプリケーションに必要なフォームフィールドとセッション要件を確認し、準備してください。この例で送信するのはCAPTCHAレスポンスフィールドのみです。ホスト名をまだ設定していない場合は、サイトプロファイルの設定を参照してください。

import { request } from 'playwright';
import { Solvethree } from '@solvethree/sdk';
const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
const target = new URL(process.env.TARGET_URL);
const proxy = new URL(process.env.SOLVETHREE_PROXY);
const result = await client.solve({ site: target.hostname, action: 'login', proxy: process.env.SOLVETHREE_PROXY });
const proxyConfig = { server: `${proxy.protocol}//${proxy.host}`, username: decodeURIComponent(proxy.username), password: decodeURIComponent(proxy.password) };

const targetClient = await request.newContext({
  proxy: proxyConfig, timeout: 30000,
  extraHTTPHeaders: { 'User-Agent': result.solution.userAgent, 'sec-ch-ua': result.solution.secChUa },
  // storageState: 'your-application-session.json', // only if your flow needs it
});
try {
  const response = await targetClient.post(target.href, {
    form: { 'g-recaptcha-response': result.solution.token }, maxRedirects: 0,
  });
  console.log('Application HTTP status:', response.status());
  // Inspect the response and supply the application's actual fields/CSRF/session.
} finally { await targetClient.dispose(); }

client.solve()はタスクを1回作成し、準備完了になるか例外がスローされるまでポーリングします。この例では、解決と送信の両方に同じプロキシを使います。Playwright向けに、プロキシのサーバーアドレスを認証情報から分離し、ユーザー名とパスワードをデコードします。

リクエストコンテキストは、solution.userAgentとsolution.secChUaをヘッダーとして適用します。フォームでは、タスクIDではなくsolution.tokenをg-recaptcha-responseに入れて送信します。プロキシと返された識別情報は組み合わせて使ってください。無関係なブラウザーヘッダーに置き換えたり、別の送信先にトークンを送ったりしないでください。

アプリケーションの実際のフィールドをフォームに追加し、必要に応じて認証情報やCSRFデータも含めてください。必要なアプリケーションセッションがすでにある場合は、任意のstorageState設定を有効にし、そのセッションの保存済み状態を指定してください。

APIRequestContextは独自のCookieストアを持つため、同じコンテキスト経由のリクエストでは、受け取ったCookieが保持されます。無関係なブラウザーコンテキストとCookieが自動的に共有されることはありません。事前のセッションリクエストと最後のPOSTでCookieを共有する必要がある場合は、同じコンテキストで実行してください。送信が終了すると、finallyブロックがコンテキストを破棄します。

この例はアプリケーションのHTTPステータスをログに記録しますが、ログインの成功を確認するものではありません。maxRedirectsをゼロに設定しているため、リダイレクトをたどらず、最初のレスポンスを確認できます。その本文、ヘッダー、Cookieを、アプリケーションが想定する成功時のレスポンスと照合してください。リダイレクトやHTTP 200だけでは、操作が成功したかどうかを判断できない場合があります。

タスクは準備完了になっているのに、アプリケーションがPOSTを拒否する。

まず送信リクエストを確認してください。トークンのフィールド、ホスト名とアクション、プロキシ、返された識別情報、必須のフォームフィールド、CSRF値、セッションCookieを確認します。

試してみましょう： 再度解決料金を支払う前に、リクエストデータの不足や不一致を修正してください。準備完了のタスクは利用可能な解決結果を提供しますが、送信先での受け入れを保証するものではありません。

解決処理がタスク失敗で終了する。

errorCodeとerrorを確認してください。すべての失敗をクレジットの問題と見なさないでください。

試してみましょう： そのタスクのポーリングを停止し、報告された原因に対処してください。失敗した解決処理の料金は返金されます。エラーの解釈については、APIエラー処理を参照してください。

タスク作成がタイムアウトする、または接続が切断される。

タスクIDが手元にあるか、またはrequestIdを使用したかを確認してください。接続のタイムアウトだけでは、作成に失敗したとは断定できません。

試してみましょう： タスクIDがある場合は、既存のタスクを取得してください。作成リクエストを復旧できるようにするには、requestIdを指定し、まったく同じ入力で再利用してください。これにより既存のタスクが返されます。同じ解決処理を別のタスクとしてすぐに開始しないでください。

アプリケーションへのリクエストがHTTPエラーを返す。

送信先のレスポンスは、solvethreeのタスク結果とは別に確認してください。

試してみましょう： レスポンス本文を成功時のペイロードとして扱う前に、成功以外のレスポンスに対処してください。トークンが原因だと決めつけず、アプリケーションへのリクエストや、報告されたサーバーエラーを修正してください。