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 キーのドロップダウンには、スコープ内のすべてのアクティブなキー(個人キー、管理する組織キー、アクセスできるチーム共有キー)が表示されます。リクエストの請求先となるキーを選択します。アクティブなキーがまだない場合は、インラインプロンプトから API Keys ページにリンクして作成できます。

モードの選択

上部の Mode 行で、Auto と手動エンジンの切り替えを行います。Autoが選択されている場合、フォームは最小限のAutoサーフェス(URLとvalidateに加えていくつかの調整機能)に切り替わります。Autoをオフにすると、Single、Proxy、Browser の3つのピルが表示されます。ピルを切り替えると、表示されるフィールドと、リクエストが送信されるエンジンが切り替わります。現在の選択は、ページを再読み込みしても保持されます。

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 を発行します)と本文を無視します。

リクエストタブ

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

タブ	制御内容
UI	タイムアウト、リダイレクト、フラグ、プロキシ、ブラウザ固有のオプション、検証ルールのフォームフィールド
Body	POST / PUT / PATCHリクエスト用のフリーフォームの本文
Headers	キーと値のペアとしてのカスタムリクエストヘッダー
Cookies	リクエストとともに送信するCookie
Raw	送信される正確なJSONペイロード(直接編集可能)

UI / Body / Headers / Cookies で変更した内容は、Raw に反映されます。Raw を直接編集することも可能であり、他のタブもそれに合わせて更新されます。エンジンのデフォルト値と異なる値が設定されているタブや折りたたみ可能なセクションには赤い点が表示されるため、カスタマイズした項目を一目で確認できます。

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、Auto に適用されます。Browser は自身でリダイレクトを処理します。
Flags: Single、Proxy、Browser 用の unblocker (Browser で unblocker を有効にすると自動防御ソルバーがトリガーされます)。Single および Proxy 用の tryJsonData と returnBuffer。Auto では代わりに forceProxy と returnSession が公開されます。
Proxy: Single または Browser 用に特定のプロキシ ID を選択するか、Proxy エンジン用に maxTries、Proxy 外部タイムアウト、exitCountries、ignoreProxies を設定します。Auto では ignoreProxies も公開されます。
Browser profile: os、browser、version の3つの連動するドロップダウンで、FourA が実際に提示できる内容をリストします。これらは Single モードおよび Proxy モードで表示されます。最新の Chrome を使用する場合は空のままにしてください。各選択は他の2つを絞り込むため、何も解決されない組み合わせは表示されません。このセクションでは Web Unblocker をオンにする必要があります。オフの場合、ブラウザのヘッダーは送信されず、プロファイルは半分しか適用されず、API は代わりにリクエストを拒否します。
Browser: checkStatus や checkText などの Browser 専用オプション。
Validate: validate.status (ステータスコード)、validate.headers (ヘッダーのキーと値のルール)、および validate.data (本文の accept / fail 部分文字列、| で区切られた代替) の accept / fail ルール。Auto を含むすべての Mode で使用できます。

終了国のスコープ設定 (Proxy Mode)

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

スコープ設定下でプロキシ呼び出しが成功すると、レスポンスストリップのプロキシ ID の横に exit <CODE> が表示され、提供された国が要求したものと一致しているかを確認できます。

ツールバーのリセット

ツールバーにあるResetボタン(HistoryとSavedの隣)は、playgroundを初期状態にクリアします。この操作は破壊的であるため、削除される項目(3つのプロダクトフォーム(Single、Proxy、Browser)、jarに保存されたcookie、引き継がれたproxy、および現在のresponse)を正確にリストする確認ダイアログが開きます。保存されたプリセットと選択されたAPI keyは保持されます。確認するにはReset everythingをクリックします。それ以外はキャンセルされます。

送信とキャンセル

Sendをクリックしてrequestを発行します。呼び出しの実行中、右側の列はスピナーとCancelボタンのあるローディング状態に切り替わります。中止するにはCancelをクリックします(モバイルの場合はボタンを再度タップします)。キャンセルされたrequestは、エラーをレンダリングする代わりに、「Request canceled.」というアイドル状態のプレースホルダーを復元します。

requestが完了(または失敗)した瞬間に、responseカードは結果に切り替わります。コールドターゲットではラダーが数段上がる可能性があるため、Autoの実行は手動エンジンよりも時間がかかる場合があります。

responseの読み取り

response列は、requestのレイアウトを反映しており、独自のタブがあります。

タブ	表示内容
Body	パースされたbody。返された内容に応じて、JSON、HTML、テキストビューが切り替わります。
Headers	1行に1つずつのresponse header。
Cookies	ターゲットから返されたcookie。パース済み(ホストグループ化)ビューと生の(Set-Cookieテキスト)ビューの両方で表示されます。パース済みビューでは、ホストのみのcookieに`HO`バッジが表示されます。ドメインcookieにはマークは付きません。
Raw	APIから返された完全なJSONエンベロープ。

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

実行間の値の引き継ぎ

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

Autoの実行では、完全なsessionトリプル(proxy、cookies、userAgent)が提供されます。
Browserの実行では、response userAgentと、使用された場合はproxy IDが提供されます。
Proxyの実行では、返されたproxy IDが提供されます。

Carryをクリックして、各値を適用する場所を1クリックで選択します。userAgentはSingleまたはProxyのUser-Agent headerになり、proxy IDはSingleまたはBrowserのproxyフィールドにドロップされます。引き継がれた値を受け取ったフィールドには「変更済み」を示す赤いドットが表示され、何が変更されたかを確認できます。

フルスクリーンへの展開

responseツールバーの展開アイコンを使用すると、responseカードが分割レイアウトからフルスクリーンオーバーレイに引き上げられます。深いJSONツリー、長いSet-Cookieダンプ、または半幅の列では窮屈になる広いHTML bodyにこれを使用します。オーバーレイが開いている間、ページ自体のスクロールは停止します。折りたたむには、アイコンを再度クリックします(またはEscapeを押します)。

curl Reproducer

レスポンスの下にある curl ブロックには、作成したリクエストと等価の正確なコマンドラインが表示されます。これをコピーして、ターミナルからリクエストを再現したり、チームメンバーと共有したり、バグレポートに貼り付けたりできます。

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

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

プリセットの保存

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

ツールバーの Saved を開くと、プリセットの参照、名前の変更、削除ができます。任意のプリセットをクリックすると、フォームに再読み込みされます。

プリセットのフィールド	保存内容
Name	短いラベル (最大100文字)
Description	任意の説明 (最大500文字)
Endpoint	プリセットが対象とするエンジン (auto / single / proxy / browser)
Config	UI フィールド、header、cookie、body を含む、リクエストの完全な payload

プリセットはユーザーアカウントにスコープされており、チームメンバーとは共有されません。

History からのリプレイ

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

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

History は自動的にアカウントにスコープされます。自分の実行履歴のみが表示されます。

Activity から開く

Activity Log の詳細ダイアログには Open in Playground ボタンがあります。これをクリックすると、Playground がアーカイブされたリクエストとアーカイブされたレスポンスの両方とともに読み込まれます。フォームは保存された payload から入力され、レスポンスカードにはその時点での API の返答が、proxy メタストリップに「archived」バッジ (「archived [, truncated] [, via ]」) 付きで表示されます。

そこからパラメーターを変更して Send を押し、ライブ API に対して新しいリクエストを実行することも、再実行せずにアーカイブされた payload を検査することもできます。payload は24時間保持されるため、古い Activity 行には再読み込み可能なレスポンスがありません。

ヒント

新しいターゲットに対してコードを書く前に、Playgroundで開始してください。Autoをオンにすると、安価なfetchで十分か、サイトがbrowserによる解決を強制するかが数秒でわかります。
国によってロックされたターゲットの場合、exitCountriesを設定してProxy呼び出しを1回実行し、返されたproxy IDをBrowser呼び出しに引き継ぐことで、JavaScriptのレンダリングが同じ出口を経由するようにします。
定期的にスクレイピングする各ターゲットのプリセットを保存してください。保存したプリセットの再生は1クリックで済みますが、記憶からrequestを再構築するには時間がかかります。
セッションベースのスクレイピングをデバッグするには、Cookiesタブを使用します。生のSet-Cookieビューには、ターゲットが送信したものが正確に表示されます。
ターゲットに拒否された場合は、より重いエンジンを使用する前に、Browserプロファイル選択で別のエントリを試してください。提示されるブラウザの切り替えは無料ですが、browserのレンダリングは無料ではありません。
Playgroundのrequestは、選択したキーに対して課金されます。本番環境の利用状況をきれいに保ちたい場合は、カジュアルな探索には専用の低クォータキーを使用してください。