Gumloop CAPTCHAの解決をWebワークフローに追加する方法

TL;DR

• GumloopのCAPTCHA解決は検証済みのネイティブ接続ではありません。組織所有のブラウザ復元サービスを使用して、Gumloopのドキュメントに記載されたHTTPおよびルーティングノードと組み合わせて使用してください。
• チャレンジ検出とトークンの適用を同じ認証済みブラウザセッション内で行い、ワークフローノードにページ状態の再構築を依頼しないでください。
• NO_CHALLENGE、RECOVERED、REVIEW、STOPなどの正確な状態を、オープンエンドモデルの決定ではなく決定論的なルールでルーティングしてください。
• 復元サービスをドキュメントに記載されたreCAPTCHA v2/v3およびCloudflare Turnstileアダプタに限定し、デフォルトで1回のワークフロー試行と明示的なアプリケーション検証を行ってください。
• 未対応のタイプ、ロストセッション、繰り返しチャレンジ、明確でない認証は、ウェブアクションを続行せずに人間のキューに送信してください。

イントロダクション

GumloopのCAPTCHA解決は、認証済みブラウザタスクの周囲で制御された復元ブランチとして最も効果的ですが、ネイティブ統合として想定されるものではありません。Gumloopは入力、HTTPコール、ルーティング、エラーパスのオーケストレーションを担当し、外部のブラウザワーカーはページセッションを保持し、検証済みの結果を適用します。CapSolverは、このワーカー内でドキュメント化されたCAPTCHAレイヤーを提供できます。この分離が重要である理由は、APIの結果だけでは元のページが進捗したことを証明できないためです。ワークフローはブラウザ状態を確認し、リトライ予算を強制し、認証またはセッションの継続性が不明な場合に停止する必要があります。以下のパターンは、アクセス可能なシステムおよびデータでの法的で合理的で責任あるユーザー認証自動化のためのものです。

前提条件のギャップから始める

このガイドの研究中に、GumloopとCapSolverのネイティブ接続は検証されませんでした。したがって、GumloopのCAPTCHA解決には明示的な前提条件が必要です。あなたのチームは、認証済みブラウザセッションを所有し、狭い復元エンドポイントを公開するHTTPSサービスを運用する必要があります。これはGumloopのプライベートAPIや隠しノードではなく、Gumloopが公式にCapSolverと統合しているという主張でもありません。

境界はGumloopでドキュメント化された機能に従います。そのCall APIノードは、ヘッダーとリクエストボディを含むHTTPSエンドポイントにGETまたはPOSTリクエストを送信できます。そのInputノード契約は、ユーザー、Webhook、またはデフォルトから値を受信できます。これらの機能は、あなたの組織が制御するサービスを呼び出すには十分ですが、それ自体でブラウザセッションを作成または保持することはできません。

フローを構築する前に必要なもの

これらのコンポーネントをまず準備してください:

• ページ、クッキー、ストレージ、ユーザーエージェント、ネットワークコンテキストを所有する認証済みブラウザワーカー;
• サービス認証で保護されたHTTPS復元エンドポイント;
• 復元サービスのシークレットマネージャーにのみ保存されるCapSolver APIキー;
• 許可されたホストとアクションのホワイトリスト;
• 終端状態で、生の資格情報なしのタイプ付き応答;
• 未対応または曖昧なケースのための手動レビュー先。

どのコンポーネントも欠けていれば、GumloopのCAPTCHA解決は設計またはテストステータスにとどめておく必要があります。検証されていないGumloopノードを代替したり、通常のワークフローテキストにプロダクションAPIキーを配置しないでください。

5段階のワークフロー契約を使用する

信頼性の高いGumloop CAPTCHA解決の設計は、オーケストレーションとブラウザ実行を分離します。Gumloopのキャンバスは決定経路をモデル化する必要があります。ブラウザワーカーはチャレンジ検出、CapSolverコール、結果の適用、ページ検証を所有する必要があります。

ステージ1: 範囲付きブラウザイベントを受信

ワークフローは、不透明な実行参照を含むWebhookまたは手動入力から開始されます。クッキー、パスワード、生のHTML、ブラウザストレージダンプを送信しないでください。最小限のイベントは次のようになります:

{
  "run_id": "run_01JX...",
  "session_ref": "browser_session_7f2a",
  "approved_host": "portal.example",
  "approved_action": "submit_owned_test_form",
  "observed_state": "CHALLENGE_DETECTED",
  "challenge_type": "recaptcha_v2",
  "attempt": 0
}

入力はすでに承認された実行への参照です。このステージの出力は、有効な復元要求またはSTOPです。ホスト、アクション、またはセッション参照が欠如している、またはポリシー外であれば、ワークフローはすぐに停止します。

ステージ2: 復元サービスを呼び出す

https://automation.example.net/v1/browser/recoverなどの組織所有のエンドポイントにPOSTリクエストを送信するようにCall APIノードを構成します。サービス認証ヘッダーにマネージド資格情報を使用してください。ボディには、制限付きイベントフィールドを渡し、CapSolver APIキーを渡さないでください。

{
  "run_id": "{{run_id}}",
  "session_ref": "{{session_ref}}",
  "approved_host": "{{approved_host}}",
  "approved_action": "{{approved_action}}",
  "challenge_type": "{{challenge_type}}",
  "attempt": "{{attempt}}",
  "max_attempts": 1
}

このJSONは、あなたのサービス用の一般的なHTTP契約です。これはGumloopのエクスポートやCapSolver APIリクエストではありません。実装前に、Gumloopワークスペースで利用可能な正確な変数補間と資格情報制御を確認してください。

ステージ3: 操作状態のみを返す

サービスは、生の解決値を見ずにGumloopがルーティングできる小さな応答を返すべきです:

{
  "state": "RECOVERED",
  "run_id": "run_01JX...",
  "correlation_id": "recovery_91c8",
  "attempts_used": 1,
  "continuation_verified": true,
  "reason": "expected form step became visible"
}

役立つ終端応答はNO_CHALLENGE、RECOVERED、REVIEW、STOPです。一時的なサービス障害はRETRYABLE_ERRORを返すことができますが、Gumloopは再度呼び出す前に1回のリトライ予算を消費する必要があります。欠如した状態、パースできないボディ、または不明な値を持つHTTP 200を成功と見なさないでください。

ステージ4: 精確な条件でルーティング

Gumloopルーターの標準モードを使用して、正確な状態マッチングを行ってください。チャレンジ復元は決定論的な制御問題であるため、モデルの解釈は必要ありません。

この表はGumloop CAPTCHA解決の出力を定義するものであり、プロバイダーの内部タスクステータスではありません。プロバイダーのステートは、ワークフローに終端応答が到達する前に復元サービス内で解決する必要があります。

ステージ5: トランスポートエラーを別途処理

Call APIノードをGumloopのError Shieldの失敗ブランチでラップしてください。失敗したコールを調査するために必要な非シークレット入力フィールドのみをパススルーに有効にしてください。エラー経路はレビュー記録を作成するかアラートを送信する必要があります。ブラウザアクションに自動的に再接続しないでください。

トランスポートエラー、プロバイダーのエラー、アプリケーションの拒否、未対応のチャレンジには異なる証拠が必要です。これら4つを1つのリトライブランチに結合すると、Gumloop CAPTCHA解決が運用しにくくなり、終端エラー後に繰り返しトラフィックを生成する可能性があります。

公式CapSolverフィールドで復元サービスを実装

復元サービスは公式CapSolverフィールドが属する場所です。createTaskリクエストはclientKeyとタスクオブジェクトを受け入れます。getTaskResultレスポンスは非同期タスクでerrorId、status、solutionを使用します。公式の応答は、processing結果は3秒後に再クエリ可能であると述べています。

以下のPython例はreCAPTCHA v2アダプタのみを実装しています。reCAPTCHA v2タスク定義からドキュメント化されたReCaptchaV2TaskProxyLess、websiteURL、websiteKeyフィールドを使用しています。ブラウザ固有の検出および適用関数は、あなたのワーカーが所有するプレースホルダーであり、GumloopまたはCapSolver APIメソッドではありません。

import os
import time
import requests

CAPSOLVER_KEY = os.environ["CAPSOLVER_API_KEY"]
CREATE_TASK = "https://api.capsolver.com/createTask"
GET_RESULT = "https://api.capsolver.com/getTaskResult"
APPROVED_HOSTS = {"portal.example"}


def solve_recaptcha_v2(website_url: str, website_key: str) -> dict:
    created = requests.post(
        CREATE_TASK,
        json={
            "clientKey": CAPSOLVER_KEY,
            "task": {
                "type": "ReCaptchaV2TaskProxyLess",
                "websiteURL": website_url,
                "websiteKey": website_key,
            },
        },
        timeout=15,
    ).json()

    if created.get("errorId") or not created.get("taskId"):
        return {"state": "REVIEW", "reason": "task creation failed"}

    for _ in range(4):
        time.sleep(3)
        result = requests.post(
            GET_RESULT,
            json={"clientKey": CAPSOLVER_KEY, "taskId": created["taskId"]},
            timeout=15,
        ).json()

        if result.get("errorId"):
            return {"state": "REVIEW", "reason": "provider returned an error"}
        if result.get("status") == "ready":
            return {"state": "SOLUTION_READY", "solution": result["solution"]}
        if result.get("status") != "processing":
            return {"state": "REVIEW", "reason": "unexpected task status"}

    return {"state": "STOP", "reason": "poll budget exhausted"}


def recover_authorized_session(event: dict, browser_store) -> dict:
    if event.get("approved_host") not in APPROVED_HOSTS:
        return {"state": "STOP", "reason": "host outside approved scope"}
    if event.get("attempt", 0) >= event.get("max_attempts", 1):
        return {"state": "STOP", "reason": "attempt budget exhausted"}

    page = browser_store.get(event["session_ref"])
    if page is None:
        return {"state": "REVIEW", "reason": "browser session unavailable"}

    info = detect_supported_challenge(page)  # your verified browser adapter
    if info is None:
        return {"state": "NO_CHALLENGE"}
    if info["type"] != "recaptcha_v2":
        return {"state": "REVIEW", "reason": "adapter not configured"}

    solved = solve_recaptcha_v2(info["website_url"], info["website_key"])
    if solved["state"] != "SOLUTION_READY":
        return solved

    apply_solution_in_same_session(page, solved["solution"])
    if not verify_expected_transition(page, event["approved_action"]):
        return {"state": "REVIEW", "reason": "application did not advance"}

    return {"state": "RECOVERED", "continuation_verified": True}

関数の入力は承認された実行イベントと不透明なブラウザセッション参照です。出力はGumloop用の終端状態です。未承認ホスト、試行予算の枯渇、欠如したブラウザセッション、未対応のアダプタ、プロバイダーのエラー、予期しないタスクステータス、ポール予算の枯渇、またはアプリケーション検証の失敗で停止します。

v2タスクオブジェクトを他のチャレンジタイプに再利用しないでください。公式のreCAPTCHA v3タスクガイドとCloudflare Turnstileタスクガイドから別個のアダプタを作成してください。各アダプタの必要なフィールド、返される解決策、ブラウザ適用ロジック、および検証アサーションを分離してください。

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

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

ブラウザの継続性をキャンバスの外に保つ

セッションの継続性はGumloop CAPTCHA解決における決定的な境界です。解決策が技術的に有効であっても、異なるページ、クッキージャー、ユーザーエージェント、プロキシID、ルート、または保護されたアクションに戻ると失敗する可能性があります。

Gumloopワークフローは不透明なsession_refを渡すべきであり、コピーされたフィールドからブラウザ状態を再構築すべきではありません。復元ワーカーはその参照を解決し、現在のURLとチャレンジを確認し、同じブラウザコンテキストで結果を適用し、特定のアプリケーションアサーションをチェックします。例として、フォームステップが表示される、所有するQAルートが完了する、または予期された公開ページ要素が表示されることが挙げられます。

アプリケーション検証は「HTTPコールが成功した」より強力でなければなりません。隣接するn8n復元診断は、ワークフロープラットフォームが別個の復元チェックを必要とする理由を示しています。Gumloopでは、このチェックをワーカー応答にモデル化し、成功ブランチが実行される前にcontinuation_verified=trueを要求する必要があります。

ループできないリトライ予算を設定

良いGumloop CAPTCHA解決フローには2つの予算があります。復元サービス内のプロバイダーのポール予算と、Gumloop内のワークフローのリトライ予算です。これらは異なる問題を解決します。

プロバイダーのポール予算は、処理中のタスクに対してサービスが待機する時間を制御します。ワークフローのリトライ予算は、一時的なトランスポートエラー後にGumloopが復元サービスを再度呼び出せるかどうかを制御します。初期ポリシーとして、1回のワークフロー復元試行と小さなタイムアウト付きのプロバイダーのポールループを設定するのが適切です。これらの値は、観測された認証済みワークロードからのみ調整してください。

以下の状況ではリトライせずに停止してください:

• ページホストまたは意図されたアクションが承認されたイベントと異なる;
• ブラウザセッションを復元できない;
• チャレンジタイプが分類できない、または構成されたアダプタがない;
• ログイン、支払い、プライベート、制限付き、または機密データの境界に到達し、認証外;
• プロバイダーが終端エラーを返す;
• 解決後の同じチャレンジが再出現;
• 予期されたアプリケーション遷移が発生しない;
• サービス応答が空、破損、または未知の状態を使用する。

ワークフローは停止理由、相関ID、試行回数、および赤カットされたターゲット識別子を記録する必要があります。APIキー、クッキー、生の解決値、または不要なページコンテンツを通常のログに保存しないでください。

パウスノードを発明せずに人間のフォールバックを追加

人間のフォールバックは、操作するGumloopのサーフェスによって異なります。標準的なワークフローでは、REVIEWを通知、チケット、シート、またはその他のマニュアルキューにルーティングし、その後自律的なブラウザアクションを終了してください。すべてのワークフローが無限に一時停止できるとは主張しないでください。あなたのGumloopプランと構成がそれを証明する必要があります。

Gumloopは別途、エージェントツールコールの人の承認を文書化しています。復元アクションがGumloopエージェントとして承認されたツールとして公開されている場合、ツールコールの前に承認を要求し、決定後にエージェントを再開させることができます。これはエージェント制御オプションであり、CapSolverコネクタの証明ではありません。復元サービスの承認チェックの代用でもありません。

GumloopのCAPTCHA解決証拠を確認するオペレーターは、以下を確認する必要があります。

• 承認されたホストとアクション;
• ロウソリューション値を含まないチャレンジカテゴリ;
• ブラウザセッションの状態;
• 使用された試行回数と残り;
• 最後のアプリケーションアサーション;
• 自律実行が停止した正確な理由。

承認は、1つの名前付きアクションを許可するもので、新しいホストやデータ範囲に実行を拡張してはなりません。

プロダクション前に失敗フローをテストする

所有するシステムまたはテストが許可されているシステムでGumloop CAPTCHA解決を固定値で検証してください。受け入れテストは、Gumloopキャンバスとブラウザワーカーの両方をカバーする必要があります。

1. 有効なNO_CHALLENGEイベントを送信し、復元エンドポイントを呼び出さずにワークフローが続くことを確認してください。
2. 承認されたreCAPTCHA v2の固定値を送信し、ブラウザワーカーがセッションを保持し、アプリケーションアサーションが通過した後のみRECOVEREDを返すことを確認してください。
3. 提供者ポール予算が期限切れになるまでprocessingを返し、サービスがSTOPを返すことを確認してください。
4. 復元エンドポイントのタイムアウトをシミュレートし、Error Shieldが成功パスではなくレビュー経路を使用することを確認してください。
5. 知らない状態を返し、ルーターが終端のワイルドカードブランチを選択することを確認してください。
6. ブラウザセッションを削除し、フローが新しいコンテキストを静かに作成しないことを確認してください。
7. そのアダプタが構成される前にreCAPTCHA v3またはTurnstileの固定値を提示し、結果がREVIEWであることを確認してください。
8. アプリケーション後にチャレンジを繰り返し、ワークフローが無限リトライループを消費しないことを確認してください。

最終的なテスト証拠は4つの質問に答えなければなりません：実行は承認されましたか？チャレンジアダプタは文書化されましたか？同じブラウザセッションが継続しましたか？意図されたアプリケーション状態は進みましたか？APIコールからの「はい」だけでは十分ではありません。

結論

Gumloop CAPTCHA解決は、Gumloopがオーケストレーターであり、認可されたブラウザサービスがセッションに敏感な復元を所有している場合に信頼できます。文書化されたInput、Call API、Router、Error Shieldの動作を使用してください。小さなHTTP契約を公開し、リトライを制限し、元のページ遷移を検証し、不確実性をレビューにルーティングしてください。ネイティブコネクタを主張したり、ブラウザ状態をワークフローにコピーしたりしないでください。これらの制御の後で文書化されたreCAPTCHA v2/v3またはCloudflare Turnstile処理が必要な承認済みウェブオートメーションの場合、CapSolverをサービス境界内の復元コンポーネントとして評価してください。

FAQ

GumloopはCapSolverと公式に統合していますか？

いいえ、このガイドでは公式なネイティブGumloop-CapSolverコネクタは確認されていません。実装は、Gumloopの文書化されたHTTPおよびルーティング機能を使用して、CapSolverを統合した組織所有の復元サービスを呼び出しています。

GumloopのCall APIノードからCapSolver APIを直接呼び出せますか？

Call APIノードはPOSTリクエストを送信できますが、直接呼び出すとプロバイダーの資格情報が漏洩する可能性があり、ブラウザセッションを保持または再開できません。狭いサーバーサイドの復元サービスは、キーを保存し、セッションを所有し、結果を適用し、検証された状態のみを返すため、より安全な運用境界です。

ワークフローがサポートするCAPTCHAの種類はどれですか？

このエージェント指向のパターンでは、reCAPTCHA v2、適用可能な場合のreCAPTCHA v3（エンタープライズを含む）、およびCloudflare Turnstileの別々の文書化されたアダプタを構成してください。タスクタイプ間でフィールドを再利用したり、サポートされていないタイプをリトライ可能なエラーとして扱ったりしないでください。

Gumloopワークフローはどのくらいのリトライを許可すべきですか？

1回のワークフロー復元試行から始めましょう。提供者のポーリングを復元サービス内で行い、独自の時間とクエリ予算を使用してください。チャレンジが繰り返される、セッションの継続性が失われる、提供者がエラーを返す、またはアプリケーション検証に失敗した場合に停止してください。

Gumloopはいつ実行を人間レビューに送るべきですか？

認証が不明瞭な場合、ブラウザセッションが欠如している場合、チャレンジタイプがサポートされていない場合、応答が不正な形式の場合、試行予算が尽きている場合、または予期されたページ遷移が発生しない場合に、人間レビューを使用してください。レビューは承認されたホスト、アクション、またはデータ範囲を拡張してはなりません。