oxylabs-headless-browser

Oxylabs ヘッドレスブラウザー

検知回避機能とプロキシ連携を組み込んだリモートヘッドレスブラウザーサービスです。Chrome は Playwright、Puppeteer、および CDP 互換ライブラリに対応しています。Firefox はレガシー版で、Playwright の Firefox 接続 API を使用します。

環境変数

ヘッドレスブラウザーの認証情報には、OXY_UNBLOCKER_USERNAME と OXY_UNBLOCKER_PASSWORD を優先して使用してください。古い環境設定では、エイリアスとして OXY_HB_USERNAME と OXY_HB_PASSWORD もサポートされています。

接続 URL

ブラウザー	グローバルエンドポイント	米国エンドポイント
Chrome	wss://USERNAME:[email protected]	wss://USERNAME:[email protected]
Firefox（レガシー）	wss://USERNAME:[email protected]	wss://USERNAME:[email protected]

ブラウザーの種類

種類	最適な用途	備考
Chrome	高パフォーマンス、専用サーバー、住宅用プロキシ	chromium.connect_over_cdp / connectOverCDP を使用します
Firefox（レガシー）	Chrome 以外の方が適したターゲット向けの代替エンジン	firefox.connect を使用します。サポート対象の Playwright バージョンは 1.51 および ?o_pw=1.56 経由の 1.56 です

クイックスタート

Playwright（Python）：

from playwright.sync_api import sync_playwright
import os

username = os.environ.get("OXY_UNBLOCKER_USERNAME") or os.environ["OXY_HB_USERNAME"]
password = os.environ.get("OXY_UNBLOCKER_PASSWORD") or os.environ["OXY_HB_PASSWORD"]
endpoint = "ubc.oxylabs.io"

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(
        f"wss://{username}:{password}@{endpoint}"
    )
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.content())
    browser.close()

Playwright（JavaScript）：

const { chromium } = require("playwright");

const username = process.env.OXY_UNBLOCKER_USERNAME || process.env.OXY_HB_USERNAME;
const password = process.env.OXY_UNBLOCKER_PASSWORD || process.env.OXY_HB_PASSWORD;
const endpoint = "ubc.oxylabs.io";

(async () => {
  const browser = await chromium.connectOverCDP(
    `wss://${username}:${password}@${endpoint}`
  );
  const page = await browser.newPage();
  await page.goto("https://example.com");
  console.log(await page.content());
  await browser.close();
})();

Puppeteer：

const puppeteer = require("puppeteer");

const username = process.env.OXY_UNBLOCKER_USERNAME || process.env.OXY_HB_USERNAME;
const password = process.env.OXY_UNBLOCKER_PASSWORD || process.env.OXY_HB_PASSWORD;
const endpoint = "ubc.oxylabs.io";

(async () => {
  const browser = await puppeteer.connect({
    browserWSEndpoint: `wss://${username}:${password}@${endpoint}`
  });
  const page = await browser.newPage();
  await page.goto("https://example.com");
  console.log(await page.content());
  await browser.close();
})();

レート制限

• 同時セッション数： ブラウザーの種類ごとに 100
• 起動レート： ブラウザーの種類ごとに毎秒最大 10 セッション
• より高い制限： サポートへの問い合わせにより利用可能です

機能

• 検知回避： フィンガープリント管理機能を内蔵
• 住宅用プロキシ： プロキシを自動ローテーション
• ジオターゲティング： 接続パラメーターで国、都市、米国の州を指定
• 米国エンドポイント： 米国を拠点とするユーザーのレイテンシーを低減します。プロキシのジオロケーションとは異なります
• CAPTCHA 対応： ページ読み込み時に自動で解決します。window.postMessage({action: 'solve_captcha', type: '<captcha type>'}, '*') で手動実行も可能です
• セッション検査： o_vnc=true で VNC デバッグを有効化
• ローカルブラウザー不要： すべての実行はリモートで行われます

接続パラメーター

WebSocket URL にクエリパラメーターを追加します。

パラメーター	ブラウザー	説明
p_cc=US	Chrome, Firefox	2 文字の国コードを指定してトラフィックを経由させます
p_city=los_angeles	Chrome, Firefox	都市を指定します。p_cc または p_state と組み合わせてください
p_state=texas	Chrome, Firefox	米国の州を指定します。p_cc より優先されます
p_device=mobile	Chrome	desktop、mobile、または tablet のデバイスフィンガープリントをエミュレートします
o_vnc=true	Chrome, Firefox	視覚的なデバッグのためにセッション検査を有効化します
o_pw=1.56	Firefox	サポート対象の Firefox Playwright バージョン 1.51 または 1.56 を選択します
bargs=disable-notifications	Chrome	サポート対象の Chrome ブラウザー引数を渡します

サポート対象の Chrome bargs 値：force-color-profile:<profile>、window-position:X,Y、hide-scrollbars、enable-features:<feature1>,<feature2>、disable-notifications。

複数のブラウザー引数を指定する場合は、bargs を繰り返します。例：?bargs=force-color-profile:srgb&bargs=window-position:100,100。p_city には p_cc または p_state が必要です。p_state は p_cc より優先されます。

CAPTCHA 対応

• oxylabs-captcha-solve-start、oxylabs-captcha-solve-end、および oxylabs-captcha-solve-error のウィンドウメッセージを監視します。
• ページ読み込み時のチャレンジを捕捉できるよう、可能な場合はナビゲーションの前に CAPTCHA リスナーを登録してください。
• ページ読み込み後に表示される CAPTCHA は、window.postMessage({action: 'solve_captcha', type: '<captcha type>'}, '*') で解決を開始します。
• 手動での CAPTCHA 解決でサポートされる種類：hcaptcha、recaptcha、turnstile。

使用する場面

シナリオ	ヘッドレスブラウザーを使用
複雑な JavaScript サイト	はい
ボット対策で保護されたサイト	はい
ステルス機能を使ったブラウザー自動化	はい
スクリーンショット／PDF の生成	はい
シンプルな HTML スクレイピング	代わりに Web Scraper API の利用をご検討ください

サポートされているライブラリ

Chrome DevTools Protocol（CDP）をサポートする任意のライブラリ：

• Playwright（推奨）
• Puppeteer
• CDP を使用した Selenium
• カスタムの CDP 実装

Firefox はレガシーであり、Playwright のサポート対象バージョンである 1.51 または 1.56 と firefox.connect を使用してください。

詳しい例については、examples.md を参照してください。