Playground
Playground(サイドバー > Playground)を使用すると、コードを書くことなく、実際のリクエストを自身の本番キーで実行できます。新しいターゲットサイトのテスト、処理が難しいレスポンスのデバッグ、またはAuto、Single、Proxy、Browserの比較を行う最も迅速な方法です。
アクセス先: foura.ai/dashboard#playground
機能の概要
1つのフォーム、4つのエンジン、実際のリクエストトラフィック。
- Auto: スマートフェッチ機能。URLと
validateルールを渡すと、FourAが機能する最も低コストなパスを選択します。 - Single: 現実的なブラウザ挙動の通信特性を備えた直接HTTPフェッチ
- Proxy: マネージドローテーションプロキシフェッチ。ターゲットから見える国をオプションで指定可能
- Browser: JSレンダリングサイト向けに、ChromeブラウザインスタンスでURLを開く
リクエストは、ページ上部で選択したAPI keyに対して実行されます。利用量は本番環境の呼び出しと同様にそのキーのクォータにカウントされるため、テストでの過度な消費にご注意ください。
キーの選択
API keyドロップダウンには、利用可能なすべてのアクティブなキーが表示されます。My Keysの下に自身のキーが表示され、続いて所属する組織ごとにグループ化されて表示されます。メンバーは誰でも組織のキーを実行でき、そのリクエストは組織オーナーのプランに対してカウントされます。リクエストの請求先とするキーを選択してください。アクティブなキーがまだない場合は、インラインプロンプトからAPI Keysページにアクセスして作成できます。
モードの選択
上部のMode行で、Autoと手動エンジンの切り替えを行います。Autoを選択すると、フォームは最小限のAuto用UI(URL、validate、いくつかの調整項目)に切り替わります。Mode: Auto、およびEndpoint: Single、Proxy、Browserの行は常に両方表示されます。一方を選択すると他方の選択が解除されます。エンドポイントを切り替えると、表示されるフィールドとリクエストが送信されるエンジンが切り替わります。現在の選択内容はページをリロードしても保持されます。
| モード | 使用するタイミング |
|---|---|
| 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 | タイムアウト、リダイレクト、フラグ、proxy、ブラウザ固有オプション、および validate ルールのフォームフィールド |
| Body | POST / PUT / PATCH request 用のフリーフォーマット body |
| Headers | キーと値のペアで指定するカスタム request header |
| Cookies | このブラウザ内でホストごとに保持される cookie jar。Use jar は一致する cookie を request に付加し、Save response cookies は response で設定された cookie を保存します。両方ともデフォルトで有効であり、タブにはこの request で送信される内容がプレビューされます |
| Raw | 送信される正確な JSON payload。Copy JSON を備えた読み取り専用プレビューと、その下に curl 再現コードを表示 |
UI / Body / Headers / Cookies で変更した内容はすべて Raw に反映されます。Raw に直接入力することはできません。request の変更は他のタブで行ってください。エンジンのデフォルトと異なる値を持つタブや折りたたみセクションには赤色のドットが表示されるため、カスタマイズした箇所を一目で確認できます。
UI ペインのセクション
UI タブでは、設定が折りたたみ可能なセクションにグループ化されています。空のフィールドにはエンジンのスキーマデフォルトが適用されます。現在の Mode に適用されないセクションは非表示になります。
- タイムアウト:
timeout_ms、connect_timeout_ms、accept_timeout_ms、server_response_timeout_ms、dns_cache_timeout_sec。BrowserおよびAutoではtimeout_msのみ公開されます (Autoでは合計バジェット)。 - リダイレクト:
followRedirects(0-20) の切り替えと設定。SingleおよびProxy。Browserは独自にリダイレクトを追従します。 - フラグ: Single、Proxy、Browser向けの
unblocker(Browserでのunblockerはページが要求するチェックを完了します)、SingleおよびProxy向けのtryJsonDataとreturnBuffer。Autoでは代わりにforceProxyとreturnSessionが公開されます。 - プロキシ: SingleまたはBrowser用に特定のプロキシIDを選択するか、Proxyエンジン用に
maxTries、Proxy外部タイムアウト、exitCountries、exitClass、ignoreProxiesを設定します。AutoではignoreProxiesとexitClassも公開されます。exitClassセレクトには3つの状態があります。未設定の場合はフィールドを一切送信せず、standardは標準プールを指定し、premiumは標準プールで問題が発生している場合にプレミアム出口へリクエストをエスカレーションできるようにします。未設定とstandardはどちらも標準プールに留まります。クラスを指定したリクエストが成功するとexitClassが返されます。プレミアムにはプレミアム出口を含むプランが必要です。exitClassを参照してください。 - ブラウザプロファイル: FourAが実際に提供できる内容をリストする、os、browser、versionの3つの連動ドロップダウン。SingleおよびProxyモードで表示されます。最新のChromeを使用する場合は空のままにしてください。各セレクトによって他の2つが絞り込まれるため、該当なしになる組み合わせが表示されることはありません。このセクションには
unblockerを有効にする必要があります。無効の場合、ブラウザヘッダーが送信されず、プロファイルが不完全に適用されるため、APIはリクエストを拒否します。 - ブラウザ:
checkStatusやcheckTextなどのブラウザ専用オプション。 - 検証: 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が、それぞれの出口国および時間とともに一覧表示されます。useをクリックするとSingleまたはBrowserのproxyフィールドにそのIDが設定され (Proxyエンジンは独自に検出します)、**×**をクリックするとリストから削除されます。
出口国のスコープ設定 (Proxyモード)
ProxyのexitCountriesフィールドは、ターゲットから認識される2文字の国コード(CZ, GB)のカンマ区切りリストを受け付けます。値は送信時にトリムされ、大文字に変換され、重複が排除されます。標準プールからの選択は厳格な許可リスト方式です。出口が不明なproxyは除外され、プールが別の国にフォールバックすることはありません。プレミアム出口もこのリストに従います。exitClassをpremiumに設定すると、プレミアム出口はリストされた国のいずれかから選ばれ、標準プールに存在しない国は該当するプレミアム出口に割り当てられます。premiumがない場合、一致するものがないプールはcode: "no_eligible_proxy"を返し、リクエストされたスコープがdetails.exitCountriesに反映されます。スコープを保持したまま後で再試行してください。
スコープ指定のもとでproxy呼び出しが成功すると、提供された国がリクエストと一致することを確認できるよう、レスポンスストリップのproxy IDの横にexit <CODE>が表示されます。
出口の場所(Proxyモード)
ProxyのExit locationグループは、地域、都市、ネットワーク、デバイス、アドレスの保持期間など、プレミアム出口の発信元を指定します。exitCountriesで国が1つだけ指定されている場合、地域、都市、ネットワークのリストが入力されます。これらはいずれもプレミアム出口経由でのみリクエストを送信するため、exitClassをpremiumに設定してください。レスポンス内のproxy IDに場所が保持されるため、SingleまたはBrowserにそのIDを引き継ぐだけで十分です。Exit locationを参照してください。
ツールバーのリセット
ツールバーのResetボタン(HistoryとSavedの横)を押すと、Playgroundが初期状態にクリアされます。破壊的な操作であるため、消去される内容を正確に一覧表示する確認ダイアログが開きます。これには、すべてのリクエストタブ、Cookie jar内の保存されたCookie、引き継がれたproxy、現在のレスポンスが含まれます。保存済みのプリセットと選択されたAPIキーは保持されます。確認するにはReset everythingをクリックします。それ以外の操作はキャンセルされます。
送信とキャンセル
Sendをクリックしてリクエストを実行します。呼び出しの処理中は、右側の列がスピナーとCancelボタンのある読み込み状態に切り替わります。中止するにはCancelをクリックします(モバイルではボタンをもう一度タップします)。キャンセルされたリクエストは、エラーを表示する代わりに「Request canceled.」を含む待機状態のプレースホルダーに戻ります。
レスポンスカードは、リクエストが完了(または失敗)した瞬間に結果へと切り替わります。スマートフォンや、フォームの下にレスポンスが配置される幅の狭いウィンドウでは、画面下部に届いたレスポンスカードが表示位置まで自動的にスクロールされます。Auto実行は、コールドターゲットに対してラダーが複数の段階を踏む可能性があるため、手動エンジンよりも時間がかかる場合があります。
レスポンスの確認
レスポンス列は、リクエストレイアウトと同様に独自のタブを備えています。
| タブ | 表示内容 |
|---|---|
| Body | パースされた body。返された内容に応じて JSON、HTML、Text 表示を切り替えます。 |
| Headers | 1行につき1つのレスポンス header。 |
| Cookies | ターゲットから返された cookie。パース済み(ホスト別グループ化)と raw(Set-Cookie テキスト)の両方のビューで表示されます。パース済みビューでは、host-only cookie に HO バッジが表示され、domain 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> が表示されます。このストリップにはレスポンスサイズも表示され、API から報告された場合はリクエストで消費されたクレジットも表示されます。Auto 実行の場合、実行段階と試行回数はストリップ下のテキストに表示されます。
呼び出しで必要とされた処理
メタストリップの下のテキストは、ページの取得に使用された処理を言語化して示します。Auto 実行の場合、実行段階(FourA がホストに対してすでに保持していたセッション、通常の request、rotating proxy、実ブラウザ、または最初にブラウザを使用してから安価なリプレイを実行)、チャレンジが解決されたかどうか、試行回数、および消費コストが表示されます。リクエストで exitClass が設定されていた場合は、プレミアム出口と標準プールのどちらから配信されたかも表示されます。
プランの制限により呼び出しが拒否された場合、テキストにはまず「Stopped by your plan, not by the site」と表示され、続いて該当する制限(当日のブラウザリクエストの上限到達、実行中リクエスト過多、当期のクレジット消費済みなど)と Usage & Limits へのリンクが表示されます。この行は API が返した X-FourA-Limit コードから生成されるため、取得困難なページが失敗した際に、サイトによって阻止されたのかプラン制限によるものなのかを判別できます。
実行間での値の引き継ぎ
再利用可能なセッションデータを返した実行の後は、レスポンスツールバーの小さな Carry コントロールに利用可能なデータが表示されます。
returnSessionで実行された Auto 実行では、セッションのuserAgentおよびproxyが提供されます。セッションの cookie はレスポンスの Cookies タブに表示され、Save response cookies が有効な場合は cookie jar に保存されます。- Browser 実行では、レスポンスの
userAgentに加え、使用された場合は proxy ID が提供されます。 - Proxy 実行では、返された proxy ID、およびローテーションによって指定外のものが選択された場合のブラウザプロファイルが提供されます。
Carry をクリックし、ワンクリックで各値を適用する場所を選択します。userAgent は Single または Proxy の User-Agent ヘッダーになり、proxy ID は Single または Browser の proxy フィールドに挿入されます。引き継がれた値を受け取ったフィールドには「変更済み」を示す赤いドットが表示され、何が変更されたかを確認できます。
引き継がれたbrowser profileは、OS、browser、versionの3つのセレクトボックスを入力し、手動でプロファイルを選択したときと同じルールに従ってunblockerをオンにします。フォームはIDフィールドではなく3つのセレクトボックスで構成されているため、プロファイルカタログがロードされた後にのみ提供されます。
このプロファイルは、成功したリクエストが入力したリクエストと同一でなかったことを示す唯一の値です。Proxyは、要求していないブラウザファミリーに移行した場合にのみprofileをレポートします。これを指定せずに再実行すると、失敗したバージョンが再現されます。Proxyリクエストの試行回数が上限に達した理由を参照してください。
フルスクリーンへの拡大
レスポンスツールバーの拡大アイコンをクリックすると、レスポンスカードが分割レイアウトから全画面オーバーレイに切り替わります。深いJSONツリー、長大なSet-Cookieのダンプ、または半画面幅のカラムでは窮屈になる幅の広いHTMLボディの確認に使用してください。オーバーレイが開いている間、ページ自体のスクロールは停止します。アイコンをもう一度クリックする(またはEscapeキーを押す)と元の表示に戻ります。
curlによる再現コード
リクエストのRawタブにあるJSONの下に、構築中のリクエストとまったく同等のコマンドラインを示すcurlブロックとCopy curlボタンが表示されます。これをコピーして、ターミナルからのリクエスト再現、チームメンバーへの共有、またはバグ報告への貼り付けに利用できます。
表示可能なキーの場合、スニペットの横にあるReveal keyボタンを押すと実際のプレーンテキストキーがcurlに直接挿入され、そのままコピーして実行できるようになります。もう一度クリックすると非表示になります。レガシーキー(表示機能のリリース前に作成されたもの)にはPASTE_PLAINTEXT_FOR_<key-name>プレースホルダーが維持されます。表示可能にするにはAPI Keysページからキーを再生成してください。
キーの表示は毎回サーバー側で監査ログに記録され、プレーンテキストのキーは現在のページセッションのメモリ内にのみ保持されます。
プリセットの保存
同じターゲットを繰り返し再設定する場合は、保存してください。リクエストタブ行のSaveをクリックして、現在の設定に名前を付けてプリセットとして保存します。
ツールバーのSavedを開くとプリセットを確認できます。Loadをクリックしてフォームに入力するか、Deleteをクリックして削除します。
FourA Chrome拡張機能のDevToolsタブから開いたリクエストは、そのキーがアカウントに存在する場合、拡張機能のキーが選択された状態で読み込まれ、ページ上にその旨が表示されます。存在しない場合は、キーを選択するよう求められます。unblockerを設定していない再実行リクエストは、APIの挙動と同様にオンの状態で実行されます。
| プリセットフィールド | 保存内容 |
|---|---|
| Name | 短いラベル(最大100文字) |
| Description | 任意のメモ(最大500文字) |
| Endpoint | プリセットが対象とするエンジン(auto / single / proxy / browser) |
| Config | UIフィールド、header、cookie、bodyを含む完全なリクエストペイロード |
プリセットはユーザーアカウント単位でスコープされ、チームメンバーとは共有されません。
履歴からの再実行
実行したすべてのリクエストは記録されます。ツールバーのHistoryを開くと、最新順にソートされた直近20件の実行履歴を確認できます。
各行にはendpoint、対象URL、ステータス、および時間が表示されます。任意の行でReplayをクリックするとそのrequestがフォームに再読み込みされ、Sendをクリックすると再実行されます。
履歴は自動的にアカウント単位でスコープされ、自身の実行のみが表示されます。
Activityからの起動
Activity Log詳細ダイアログにはOpen in Playgroundボタンがあります。これをクリックすると、Playgroundがアーカイブされたrequestとresponseの両方を読み込んで起動します。フォームには保存されたpayloadが入力され、responseカードにはproxyメタストリップに「archived」バッジ付きでその時点にAPIが返した内容が表示されます(「archived
そこからパラメータを変更してSendを押し、ライブAPIに対して新しいrequestを実行することも、再実行せずにアーカイブされたpayloadを確認するだけにすることも可能です。payloadは24時間保持されるため、古いActivityの行には再読み込み可能なresponseがありません。
ヒント
- 新しい対象に対するコードを書く前にPlaygroundで試してください。Autoを有効にすると、安価なfetchで十分か、サイトがブラウザによる解決を強制するかが数秒で分かります。
- 国制限のある対象の場合、
exitCountriesを設定してProxy呼び出しを1回実行し、返されたproxy IDをBrowser呼び出しに引き継ぐことで、同一の出口経由でJavaScriptのレンダリングが行われます。 - 定期的にスクレイピングする対象ごとにプリセットを保存してください。保存されたプリセットの再実行は1クリックで完了しますが、記憶を頼りにrequestを再構築するには時間がかかります。
- セッションベースのスクレイピングのデバッグにはCookiesタブを使用してください。生のSet-Cookieビューに対象が送信した内容が正確に表示されます。
- 対象に拒否された場合は、より負荷の高いエンジンを使う前に、Browser profile選択項目で別のエントリを試してください。提示するブラウザの切り替えは無料ですが、ブラウザのレンダリングには費用がかかります。
- Playgroundのrequestは選択したキーに対して課金されます。本番環境の使用状況を整理された状態に保ちたい場合は、気軽な検証用として低クォータの専用キーを使用してください。
関連情報
- API Endpoints:
exitCountriesおよびブラウザプロファイルフィールドを含む全4エンジンの完全なパラメータリファレンス - Smart Fetch (Auto): Autoの内部動作
- Choosing the Right Endpoint: Auto、Single、Proxy、Browserの使い分け
- API Keys: Playgroundのrequestを認証するキーの管理
- Activity Log: 過去のrequestをPlaygroundで直接開く
- Dashboard Overview: すべてのサイドバーセクション