Playground

Playground（サイドバー > Playground）を使用すると、コードを書くことなく実際のキーに対してライブAPIリクエストを実行できます。新しいターゲットサイトのテスト、問題のあるレスポンスのデバッグ、またはAuto、Single、Proxy、Browserの比較を並行して行うための最速の方法です。

foura.ai/dashboard#playgroundからアクセスしてください。

機能の概要

1つのフォーム。4つのエンジン。実際のトラフィック。

Auto: スマートフェッチ。URLとvalidateルールを指定すると、FourAが動作する最も低コストなパスを自動選択します。
Single: 現実的なブラウザ同様のネットワーク特性を備えた直接HTTPフェッチ
Proxy: マネージドローテーションプロキシフェッチ。必要に応じてターゲットから見える国を指定可能
Browser: JSレンダリングサイト向けにChromeブラウザインスタンスでURLを開く

リクエストは、ページ上部で選択したAPIキーに対して実行されます。利用量は本番環境の呼び出しと同様にそのキーのクォータにカウントされるため、テストでの過度な消費にご注意ください。

キーの選択

APIキードロップダウンには、使用可能なすべてのアクティブなキーが一覧表示されます。My Keysの下に自身のキーが表示され、続いて所属する組織ごとにグループ化されます。どのメンバーも組織のキーを実行でき、そのリクエストは組織オーナーのプランにカウントされます。リクエストの請求先とするキーを選択してください。アクティブなキーがまだない場合は、インラインプロンプトからAPI Keysページに移動して作成できます。

モードの選択

上部のMode行で、Autoと手動エンジンの切り替えを行います。Autoを選択すると、フォームは最小限のAutoインターフェース（URL、validate、およびいくつかの設定項目）に切り替わります。Mode: Auto、およびProduct: Single、Proxy、Browserの両方の行が常に表示されます。一方を選択すると、もう一方は選択解除されます。Productを切り替えると、表示されるフィールドとリクエストが送信されるエンジンが切り替わります。現在の選択状態はページをリロードしても保持されます。

Mode	使用場面
Auto	新しいターゲットまたは保護レベルが混在するサイト。Autoが最も低コストなパスを選択し、成功した設定を記憶します。
Single	高速なHTTPフェッチ。既知のホストに対する最初の選択肢として最適です。
Proxy	自動プロキシローテーション付きの同一フェッチ。ターゲットから見える国が必要な場合は`exitCountries`を設定します。
Browser	Chromeブラウザインスタンスでページを読み込みます。JavaScript実行後にのみデータが表示される場合に使用します。

リクエストの構築

URL行

最上部の行には、HTTPメソッド（GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS）、ターゲットURL、Sendボタンがあります。Single、Proxy、Autoはすべてのメソッドに対応します。Browserはメソッド（Chromeはナビゲーションに常にGETを使用）とbodyを無視します。

リクエストタブ

URL行の下にある5つのタブで、その他のすべての項目を入力できます。

タブ	制御対象
UI	タイムアウト、リダイレクト、フラグ、プロキシ、ブラウザ固有オプション、および検証ルールのフォームフィールド
Body	POST / PUT / PATCH request 用の自由形式 body
Headers	キー・バリューペア形式のカスタム request header
Cookies	request とともに送信する Cookie
Raw	送信される正確な JSON ペイロード（Copy JSON 付きの読み取り専用プレビュー）およびその下の curl 再現コマンド

UI / Body / Headers / Cookies で変更した内容はすべて Raw に反映されます。Raw に直接入力することはできません。request の変更は他のタブで行ってください。エンジンのデフォルトと異なる値が設定されているタブや折りたたみセクションには赤いドットが表示されるため、カスタマイズした箇所を一目で確認できます。

UI ペインセクション

UI タブでは設定が折りたたみセクションにグループ化されています。空のフィールドにはエンジンのスキーマデフォルトが適用されます。現在の Mode に適用されないセクションは非表示になります。

Timeouts: timeout_ms、connect_timeout_ms、accept_timeout_ms、server_response_timeout_ms、dns_cache_timeout_sec。Auto では timeout_ms（合計バジェット）のみが表示されます。
Redirects: 切り替えおよび followRedirects（0-20）の設定。Single および Proxy 用。Browser は独自にリダイレクトを追跡します。
Flags: Single、Proxy、Browser 用の unblocker（Browser 上の unblocker はページが要求するチェックを完了します）。Single および Proxy 用の tryJsonData および returnBuffer。Auto では代わりに forceProxy および returnSession が表示されます。
Proxy: Single または Browser 用に特定のプロキシ ID を選択するか、Proxy エンジン用に maxTries、Proxy の外部タイムアウト、exitCountries、exitClass、ignoreProxies を設定します。Auto では ignoreProxies も表示されます。exitClass の選択には3つの状態があります。未設定の場合はフィールド自体を送信せず、standard は request をエスカレーションしないことを示し、premium は標準プールで問題が発生している場合にプレミアム出口へのエスカレーションを許可します。未設定と standard は異なる request となるため、どちらかを意図していない限り選択を空のままにしてください。プレミアムにはプレミアム出口を含むプランが必要です。exitClass を参照してください。
Browser profile: os、browser、version の3つの連動ドロップダウンで、FourA が実際に提示可能な項目を一覧表示します。Single および Proxy モードで表示されます。最新の Chrome を使用する場合は空のままにしてください。各選択肢によって他の2つが絞り込まれるため、該当なしとなる組み合わせは表示されません。このセクションを使用するには unblocker を有効にする必要があります。オフにすると browser header が送信されず、プロファイルが中途半端にしか適用されないため、API は request を拒否します。
Browser: checkStatus や checkText などのブラウザ専用オプション。
Validate: status accept および status fail にはカンマ区切りのステータスコード（validate.status）を指定し、body accept および body fail には | 区切りの代替文字列を含む部分文字列（validate.data）を指定します。Single、Proxy、Auto で利用可能です。Browser では代わりに checkStatus および checkText を使用します。フォームにヘッダールール（validate.headers）用のフィールドはありません。

実行によって動作するプロキシが返されると、UIタブの末尾に Working proxies セクションが表示されます。最新順に最大20件のプロキシIDが、それぞれの送信元国（Exit Country）および時間とともに一覧表示されます。use をクリックすると Single または Browser の proxy フィールドに値が入力され（Proxy エンジンは自動検出）、× でリストから削除されます。

送信元国の絞り込み（Proxy モード）

Proxy の exitCountries フィールドには、ターゲットから認識される2文字の国コード（CZ, GB）をカンマ区切りで指定できます。値は送信時にトリミング、大文字化、および重複排除されます。選択は厳格な許可リスト形式です。送信元が不明なプロキシは除外され、リクエストが他の国にフォールバックすることはありません。現在のプールに一致するものがない場合、レスポンスは code: "no_eligible_proxy" を返し、指定されたスコープが details.exitCountries にエコーバックされます。スコープを保持したまま後で再試行してください。

スコープ指定下でプロキシ呼び出しが成功すると、レスポンスバーのプロキシIDの横に exit <CODE> が表示され、提供された国が要求どおりであるかを確認できます。

ツールバーのリセット

ツールバーの Reset ボタン（History および Saved の隣）は、Playground を初期状態にクリアします。破壊的な操作であるため、消去対象を明記した確認ダイアログが開きます。対象は3つの製品フォーム（Single、Proxy、Browser）すべて、Jar 内の保存済み Cookie、保持されているプロキシ、および現在のレスポンスです。保存されたプリセットと選択中の API キーは保持されます。確認するには Reset everything をクリックします。それ以外の操作はキャンセルとなります。

送信とキャンセル

Send をクリックしてリクエストを送信します。呼び出しの実行中、右側のカラムはスピナーと Cancel ボタンが付いた読み込み状態に切り替わります。処理を中止するには Cancel をクリックします（モバイルでは同じボタンを再度タップ）。キャンセルされたリクエストは、エラーを表示する代わりに "Request canceled." とアイドル状態のプレースホルダーを復元します。

リクエストが完了（または失敗）した瞬間に、レスポンスカードが結果の表示に切り替わります。Auto 実行では、コールドターゲットに対してラダーが複数段階ステップアップする場合があるため、手動エンジンよりも時間がかかることがあります。

レスポンスの確認

レスポンスカラムはリクエストのレイアウトに対応したタブ構成になっています。

タブ	表示内容
Body	パースされた本文。返された内容に応じて JSON、HTML、Text 表示を切り替えます。
Headers	1行に1つずつのレスポンスヘッダー。
Cookies	ターゲットから返された Cookie。パース済み（ホスト別グループ化）と Raw（Set-Cookie テキスト）の両方の形式で表示されます。パース済み表示では、ホスト専用 Cookie に `HO` バッジが表示されます。ドメイン Cookie にはバッジが付きません。
Raw	API から返された完全な JSON エンベロープ。

レスポンスツールバーには、レスポンス全体に対する Copy と Download、および開いているタブ内を検索する Find in response（Ctrl+K または Cmd+K、Enter と Shift+Enter で一致項目間を移動）が用意されています。Body、Headers、Cookies の各タブにも、そのタブ専用の Copy と Download があります。

タブの上のメタストリップには、アップストリームのHTTPステータス、合計時間、呼び出しを処理したproxy ID、および（スコープ指定されたProxy呼び出しの場合）2文字のexit <CODE>が表示されます。Auto実行の場合、ストリップにはレスポンスを返したラダー段階、行われたサブ試行回数、消費されたクレジットも表示されます。

呼び出しに必要な処理

メタストリップの下の文には、ページ取得に使用された処理内容が言葉で表示されます。Auto実行の場合、段階（ホストに対してFourAが既に持っていたセッション、通常のrequest、ローテーションproxy、実ブラウザ、または最初にブラウザを使用しその後に低コストなリプレイ）、チャレンジが解決されたかどうか、試行回数、かかったコストが示されます。

プランの制限のいずれかによって呼び出しが拒否された場合、文の先頭に「サイトではなく、ご利用のプランによって停止されました」と表示され、その後に該当する制限（本日のブラウザrequest上限到達、処理中のリクエスト数が多すぎる、今期のクレジット上限到達など）とUsage & Limitsへのリンクが続きます。この行はAPIが返したX-FourA-Limitコードから生成されるため、失敗した困難なページについて、サイト側がブロックしたのかプランが停止したのかを判別できます。

実行間での値の引き継ぎ

再利用可能なセッションデータを返した実行の後は、レスポンスツールバーの小さなCarryコントロールに使用可能な値が表示されます。

Auto実行では、完全なsessionの3つ組（proxy、cookies、userAgent）が提供されます。
Browser実行では、レスポンスのuserAgentに加えて、使用された場合はproxy IDが提供されます。
Proxy実行では、返されたproxy ID、ローテーションで指定外のものが選択された場合のブラウザプロファイル、および呼び出しを処理したexitClassが提供されるため、プレミアムレスポンスを直接送り返すことができます。

Carryをクリックすると、各値をワンクリックで適用する場所を選択できます。userAgentはSingleまたはProxyのUser-Agentヘッダーになり、proxy IDはSingleまたはBrowserのproxyフィールドに入力されます。引き継がれた値を受け取ったフィールドには「変更済み」の赤いドットが表示され、変更内容を確認できます。

引き継がれたbrowser profileは、os、browser、versionの3つのセレクトボックスに入力され、手動でプロファイルを選択した時と同じルールでunblockerが有効になります。フォームがidフィールドではなく3つのセレクトボックスであるため、プロファイルカタログが読み込まれた後にのみ提供されます。

プロファイルは、成功したリクエストが入力したリクエストと異なっていたことを示す唯一の値です。Proxyは、指定されていないブラウザファミリーに移行した場合にのみprofileを報告します。これを含めずにリプレイすると、失敗したバージョンをリプレイすることになります。詳細はWhy a Proxy Request Ran Out of Triesを参照してください。

フルスクリーンに拡大

レスポンスツールバーの拡大アイコンをクリックすると、レスポンスカードが分割レイアウトから全画面オーバーレイに切り替わります。深いJSONツリー、長いSet-Cookieダンプ、または半幅カラムでは狭い幅の広いHTMLボディに活用してください。オーバーレイが開いている間、ページ自体のスクロールは停止します。もう一度アイコンをクリックする（またはEscapeキーを押す）と元の表示に戻ります。

curl再現ツール

requestの Raw タブのJSONの下にあるcurlブロックには、作成中のrequestと完全に同等のコマンドラインが表示され、Copy curl ボタンが用意されています。これをコピーして、ターミナルからrequestを再現したり、チームメンバーと共有したり、バグレポートに貼り付けたりできます。

表示可能なキーの場合、スニペットの横にある Reveal key ボタンを押すと、実際のプレーンテキストキーがcurlに直接挿入され、そのままコピーして実行できます。もう一度クリックすると非表示になります。レガシーキー（表示機能のリリース前に作成されたもの）は PASTE_PLAINTEXT_FOR_<key-name> プレースホルダーを維持します。表示可能にするには、API Keys ページからキーを再生成してください。

キーの表示は毎回サーバー上で監査ログに記録され、プレーンテキストのキーは現在のページセッションのメモリにのみ保持されます。

プリセットの保存

同じターゲットを繰り返し再設定する場合は、保存してください。requestタブの行にある Save をクリックすると、現在の設定に名前を付けてプリセットとして保存できます。

ツールバーの Saved を開くと、プリセット一覧が表示されます。Load をクリックしてフォームに入力するか、Delete をクリックして削除します。

FourA Chrome拡張機能のDevToolsタブから開いたrequestは、そのキーがアカウント内に存在する場合、拡張機能のキーが選択された状態で読み込まれ、ページ上にその旨が表示されます。存在しない場合は、キーの選択を求められます。unblocker が設定されていないリプレイrequestは、APIと同様にそれを有効にして実行されます。

プリセット項目	保存内容
Name	短いラベル（最大100文字）
Description	任意のメモ（最大500文字）
Endpoint	プリセットが対象とするエンジン（auto / single / proxy / browser）
Config	UIフィールド、header、cookie、bodyを含む完全なrequestペイロード

プリセットのスコープはユーザーアカウント単位であり、チームメンバーとは共有されません。

履歴からのリプレイ

実行したすべてのrequestはログに記録されます。ツールバーの History を開くと、最新順にソートされた過去20件の実行履歴が表示されます。

各行にはendpoint、ターゲットURL、ステータス、時刻が表示されます。任意の行の Replay をクリックしてそのrequestをフォームに再読み込みし、Send をクリックして再実行します。

履歴は自動的にアカウント単位でスコープ設定され、自分自身の実行履歴のみが表示されます。

Activityからのオープン

Activity Log の詳細ダイアログには Open in Playground ボタンがあります。これをクリックすると、Playgroundにアーカイブされたrequestとアーカイブされたresponseの両方が読み込まれます。保存されたペイロードからフォームが自動入力され、responseカードには当時のAPI返却内容が表示され、proxyメタストリップに「archived」バッジが表示されます（"archived [, truncated] [, via ]"）。

そこからパラメータを変更して Send をクリックし、ライブAPIに対して新しいrequestを実行することも、再実行せずにアーカイブされたペイロードを確認するだけにすることもできます。ペイロードは24時間保持されるため、それより古いActivity行には再読み込み可能なresponseがありません。

Tips

新しいターゲットに対するコードを書く前に、Playgroundから始めてください。Autoを有効にすると、安価なfetchで十分か、サイトがブラウザによる解決を強制するかを数秒で判断できます。
国制限のあるターゲットの場合、exitCountriesを設定してProxy呼び出しを1回実行し、返されたproxy IDをBrowser呼び出しに引き継ぐことで、同じ出口経由でJavaScriptのレンダリングを実行します。
定期的にスクレイピングするターゲットごとにプリセットを保存してください。保存したプリセットの再実行は1クリックで完了しますが、記憶を頼りにリクエストを再構築するには時間がかかります。
セッションベースのスクレイピングをデバッグするにはCookiesタブを使用します。未加工のSet-Cookieビューには、ターゲットから送信された内容がそのまま表示されます。
ターゲットに拒否された場合は、より重いエンジンに切り替える前にBrowserプロファイル選択の別のエントリを試してください。提示するブラウザの変更は無料ですが、ブラウザレンダリングは無料ではありません。
Playgroundのリクエストは選択したキーに対して課金されます。本番環境の使用状況を分離したい場合は、気軽な検証用に低クォータの専用キーを使用してください。