ライブビューとセッション
ホスト型ブラウザをライブで視聴し、操作を引き継ぐか、ビューを共有します。セッションを管理し、ブラウザを動かしたままにして、あとから再接続することもできます。
このページのリクエストは、すべてこのページから直接送信できます。サインインしていれば例にあなたの API キーが入り、「送信」を押すと実際に API を呼び出して、返ってきたレスポンスをそのまま表示します。フィールドを変えて、何が起きるかを確かめられます。
試すためのブラウザ
このあとの内容の多くでは、実行中のブラウザが必要です。ここで 1 つ起動してください。これは通常のセッションで、ほかのセッションと同じように残高から課金されます(1 GB あたり €1.00)。なお、このセッションはコマンドのない状態が 5 分続くか、合計 15 分が経過すると自動的に終了します。
POST ブラウザを起動する
レスポンスには、セッションの id と 1 回限りの connectUrl が含まれます。セッションは、クライアントがその URL に接続した時点で開始します(それまでは pending のままで、45 秒後に期限切れになります)。「接続」を押すと、Playwright や Puppeteer のスクリプトと同じように、ドキュメントが接続してタブを読み取り、切断します。keepAlive 付きなので、ブラウザはその後も動き続け、以下のリクエストで使えます。
curl -X POST 'https://www.clearcotelabs.com/api/v1/browsers' \ -H "authorization: Bearer cc_live_..." \ -H "content-type: application/json" \ -d '{"keepAlive":true,"url":"https://example.com","idleTimeoutSec":300,"timeoutSec":900,"note":"docs"}'
ライブビュー:視聴、操作、共有
ダッシュボードでセッションをクリックすると、そのトラフィックの送信先サイトを確認したり、ライブで視聴したりできます。「Take control」を押すと、自分でクリック、入力、スクロール、貼り付け、ページ移動ができます。たとえば、ログインしたり、スクリプトでは通過できないチェックを通過したりするときに使います。その間もスクリプトは接続されたままなので、操作中はスクリプトを一時停止してください。人による入力もアクティビティとみなされるため、操作中のセッションがアイドル状態として閉じられることはありません。「Share」を使うと、アカウントがなくても誰でも開けるリンクを作成できます。視聴のみか操作付きかを選べ、有効期間は 15 分から 4 時間で、セッションの終了後まで有効になることはありません。「Watch + replay」リンクでは、セッションをライブで視聴でき、終了後はそのリプレイ(録画の上にすべてのクリック、スクロール、ページ遷移を重ねて表示)を最長 14 日間見られます。
API からは次のように行います。
GET ライブビューを開く
実行中のセッションのライブビュー用 WebSocket です(60 秒以内に開いてください)。バイナリメッセージは JPEG フレーム、テキストメッセージは {"url","title","tabs"} です。control=1 を付けると、操作権限が付与された場合にレスポンスに "interactive": true が含まれます。「ここで視聴」を押すと、このページでビューが開きます。タイムラインの各イベントも、発生と同時に {"ev": …} として届きます(録画を参照)。
curl 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E/live' \ -H "authorization: Bearer cc_live_..."
POST ライブビューを共有する
アカウントがなくても誰でも開けるリンクです。操作権限の付与は任意で、有効期間は 1〜240 分(デフォルトは 30 分)、セッションの終了後まで有効になることはありません。操作権限付きのリンクは、API キーと同じように扱ってください。replay: true(操作なし)を指定すると、視聴 + リプレイ用のリンクになります。セッションの実行中はライブで、終了後はそのリプレイを見られます。有効期間は 1〜20160 分(既定 10080 分、7 日間)です。
curl -X POST 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E/share' \ -H "authorization: Bearer cc_live_..." \ -H "content-type: application/json" \ -d '{"control":false,"minutes":60}'
操作権限がある場合は、同じ WebSocket で JSON のテキストメッセージを送信します。座標は、表示しているフレームに対する割合(0〜1)で指定します。それ以外は無視されます。
| メッセージ | 動作 |
|---|---|
{"t":"mouse", | 押下(down)、解放(up)、または move。n はクリック回数、m は修飾キー(Alt 1、Ctrl 2、Meta 4、Shift 8)です。 |
{"t":"wheel", | 指定した位置で、ピクセル単位でスクロールします。 |
{"t":"key", | キーボードが送るのと同じ形式の、キーの押下または解放です。 |
{"t":"text", | 入力したかのようにテキストを挿入します(最大 5000 文字)。 |
{"t":"nav",、forward、reload、または {"t":"nav", | 履歴の移動、再読み込み、または http(s) アドレスを開きます。 |
GET /api/v1/browsers/<id> のレスポンスには traffic が含まれます。これはそのセッションのバイト数上位 20 サイトです。
セッションの管理
GET セッション 1 件
そのセッションのステータス、トラフィック、秒数、これまでの費用です。各フィールドの説明は、これらのリクエストの後にあります。
curl 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E' \ -H "authorization: Bearer cc_live_..."
GET セッション一覧
残高とセッションを新しい順に返します。デフォルトは 20 件で、limit で最大 100 件まで指定できます。ステータスと note の文字列で絞り込めます。それより前のページを取得するには、最後に受け取ったセッションの createdAt を before に指定します。行の「使う」を押すと、そのセッションをほかのリクエストで使えます。
curl 'https://www.clearcotelabs.com/api/v1/browsers' \ -H "authorization: Bearer cc_live_..."
PATCH セッションにラベルを付ける
note を設定または変更します(最大 256 文字)。null を指定すると消去されます。
curl -X PATCH 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E' \ -H "authorization: Bearer cc_live_..." \ -H "content-type: application/json" \ -d '{"note":"shop-de nightly"}'
DELETE セッションを停止する
誰も接続していないセッションは即座に終了します。実行中のブラウザは、1 回の報告間隔(約 15 秒)以内にサーバーによって閉じられます。
curl -X DELETE 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E' \ -H "authorization: Bearer cc_live_..."
作成時にセッションへ note を付けておくと、一覧やダッシュボードで見つけやすくなります。以前のセッションと同じサーバーで新しいセッションを起動するには(キャッシュが温まった状態の同じマシン)、そのセッションの worker を渡します。そのサーバーが満杯またはオフラインの場合、セッションは別のサーバーで起動し、その旨が warnings に示されます。
セッションは、ブラウザを閉じたときや切断したとき、また後述の制限に達したときにも終了します。停止リクエストを送ると、誰も接続していないセッションは即座に終了します。実行中のブラウザは、1 回の報告間隔(約 15 秒)以内にサーバーによって閉じられます。GET のレスポンスは次のとおりです。
{
"id": "bs_…",
"status": "active", // see the table below
"proxy": "managed", // or "custom"
"createdAt": "…", "startedAt": "…", "endedAt": null,
"endReason": null, // set once ended, e.g. "user", "balance", "launch_failed"
"stopRequested": false,
"usage": { "bytesUp": 120334, "bytesDown": 4812009, "gb": 0.0049, "seconds": 41 },
"traffic": [ { "site": "example.com", "bytesUp": 20400, "bytesDown": 3100000 }, … ], // top 20 sites
"costEur": 0.0050,
"pricing": { "eurPerGb": 1, "eurPerHour": 0 },
"queue": { "state": null, "position": null, "ahead": null, "etaSec": null, "updatedAt": "…" } // see below
}| status | 説明 |
|---|---|
pending | Created; nobody has connected yet. Counts towards the concurrency limit until it starts or expires (45 seconds after it was created; a run waits for its server instead). |
active | A browser is running and reporting usage. |
lost | No usage report for 5 minutes. Billed up to the last report; a late report puts it back to active. If none comes, it ends an hour after the longest a session may last (see Limits and errors): status ended, endReason worker_silent. If the server that ran it restarted, it ends as soon as that server is back: endReason worker_restarted, billed up to the last report. |
ended | Closed: you disconnected, stopped it, or a limit or the balance ended it. endReason says which. A launch its geo identity refused (geoIdentity strict) ends with endReason geo_refused:<code>, e.g. geo_refused:GEO_PROXY_COUNTRY_TIMEZONE_MISMATCH, and is not billed. |
expired | Nobody connected before expiresAt (45 seconds after creating it). Never billed. |
queue は、起動中のブラウザがサーバーの起動キューのどこにいるかを示します。そのため、混雑しているときも、接続が遅いのではなく順番待ちであることがわかります。作成時のレスポンスにも見積もりが含まれます。"queue": { "position": 3, "etaSec": 6 } は、今接続した場合にブラウザが入る位置です(サーバーがキューを報告しない場合はどちらも null です)。
| queue のフィールド | 意味 |
|---|---|
state | waiting_for_client: created, nobody has connected yet. queued: you connected and the browser waits for a launch slot on its server. launching: it is starting now. null: running, ended, or the server reported no queue in the last 30 seconds. |
position | 1-based place in the server's waiting list while queued, else null. |
ahead | How many browsers start before this one: position - 1 while queued, 0 while launching, else null. |
etaSec | Estimated seconds until it starts while queued: the browsers ahead, launched as many at a time as the server allows, at its average launch time. Else null. |
updatedAt | When the server last reported its queue (ISO time), or null when it has not in the last 30 seconds. |
一覧取得の GET /api/v1/browsers は、同じ形式のセッションオブジェクトを新しい順に並べた { balanceEur, sessions: [...] } を返します。
ブラウザを開いたままにして再接続する
デフォルトでは、クライアントが切断するとセッションは終了します。keepAlive: true を指定して起動すると、ブラウザはタブ、Cookie、出口 IP を保ったまま動作し続けます。そのため、後から実行するスクリプト(あるいはクラッシュ後やノート PC を閉じた後の同じスクリプト)で、前回の続きから作業を再開できます。
POST 再接続する
実行中の keepAlive セッション用に、1 回限りの新しい接続 URL を発行します(45 秒以内に接続してください)。「接続」を押すと、このページからブラウザに再び接続します。タブもすべてそのままです。
curl -X POST 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E/connect' \ -H "authorization: Bearer cc_live_..."
- 切断すれば実行したままにできます。Playwright の
browser.close()(connectOverCDP経由では切断するだけです)、Puppeteer のbrowser.disconnect()、あるいは単にプロセスを終了するだけでもかまいません。 DELETE /api/v1/browsers/<id>を送るか、CDP コマンドBrowser.closeを送ると終了します。Puppeteer のbrowser.close()はこのコマンドを送ります。Playwright ではawait (await browser.newBrowserCDPSession()).send("Browser.close")を使います。終了するまでは、同時実行数の枠を 1 つ占有し続けます。- 接続できるクライアントは同時に 1 つだけです。別のクライアントが接続している間の再接続は
409で拒否されます。keepAliveなしで起動したセッションへの再接続も同様です。 - 誰も接続していない間も、制限は適用されます。対象は
idleTimeoutSec(後で戻ってくるつもりのブラウザでは、最大 1800 まで引き上げてください)、timeoutSec、maxGb、そして残高です。開いたままのページはバックグラウンドのトラフィックを読み込み続け、その分もほかと同様に課金されます。