brightdata-proxy

Bright Data Proxy

Bright Data の 4 つのプロキシネットワーク向けに、動作するコードと設定を生成します。このスキルでは使用方法と統合方法を扱います。コントロールパネルの UI 設定手順は案内しません。ユーザーがまだゾーンを作成していない場合は、https://brightdata.com で登録し、アプリ内のプロキシ作成ヘルパーを使うよう伝えてください（コントロールパネルではゾーンの種類、プールの種類、認証情報を対話形式で設定できます。設定にはこちらが適切であり、このスキルではありません）。

クイックリファレンス（基本情報）

生成するコードでは、以下の値を使用してください。誤って生成されやすいため、必ずこれらを基準にしてください。

• プロキシホスト：brd.superproxy.io
• HTTP/HTTPS プロキシポート：33335（現行のポート。新しい SSL CA と組み合わせて使用します。有効期限は 2034 年 9 月）
  • 旧 CA 用の旧ポート 22225 もあります（有効期限は 2026 年 9 月。非推奨）。ユーザーが明示的に別の指定をしない限り、33335 を使用してください。
• SOCKS5 ポート：22228
• ユーザー名の形式：brd-customer-CUSTOMER_ID-zone-ZONE_NAME に、任意の -key-value パラメーターを追加します（「ターゲティング」を参照）。
• パスワード：コントロールパネルに表示されるゾーンのパスワード（アカウントのパスワードではありません）。
• テスト用エンドポイント（コードサンプルで使用し、実際のターゲットには使用しないでください）：https://geo.brdtest.com/mygeo.json — 出口 IP、国、都市、ASN を JSON 形式で返します。
• SSL CA：このスキルに assets/brightdata_proxy_ca.crt として同梱されています（Bright Data Proxy Root CA。有効期限は 2034 年 9 月）。生成するコードではこのパスを参照し、ユーザーにダウンロードさせないでください。必要に応じて個別に取得できる公開ダウンロード先は https://brightdata.com/static/brightdata_proxy_ca.zip です。

コントロールパネル内の https://brightdata.com/cp/zones/proxy_examples には、アカウントごとの各フレームワーク向けコードサンプルが最新の状態で表示されます。不確かな場合は、正確な情報を確認できる場所としてユーザーに案内してください。

同梱ツール（このスキル内）

• assets/brightdata_proxy_ca.crt — Bright Data Root CA です。ユーザーにダウンロードさせる代わりに、verify=、--cacert、ca:、または NODE_EXTRA_CA_CERTS で使用してください。
• scripts/smoke_test.sh — cURL ベースの認証情報スモークテストです。./smoke_test.sh CUSTOMER_ID ZONE_NAME ZONE_PASSWORD [COUNTRY] [SESSION_ID] を実行するか、BD_CUSTOMER_ID／BD_ZONE／BD_PASSWORD 環境変数を設定してください。同梱 CA を自動で検出し、解析済みの JSON 形式の位置情報を返します。認証エラー、HTTP エラー、ネットワークエラーごとに異なる終了コードを返します。ゾーン作成後、ユーザーが最初に実行するコマンドとしてこれを推奨してください。
• scripts/proxy_tester.html — 単一ファイルのブラウザー診断ツールです。ユーザーが認証情報を使ってブラウザーまたは OS のプロキシを設定し、このファイルをローカルで開く（または任意の場所から配信する）と、現在の出口 IP と位置情報がリアルタイムで表示されます。プロキシ使用前と使用後の出口を視覚的に比較できる、ベースライン保存機能があります。認証情報は sessionStorage のみに保存され、アップロードされることはありません。

---

判断 1：どのプロキシネットワークを使うか？

ユーザーが使用するネットワークを指定していない場合は、一度だけ確認してから進めてください。簡単な選択基準：

ネットワーク	推奨する場面
Datacenter	最も安価で高速です。保護されていないターゲット（ニュースサイト、公開 API、軽度のスクレイピング、少量のアカウント管理、制限の緩いサイトでの地域制限回避）に使用します。
ISP	接続先からは住宅用に見える固定 IP です。長期間のセッション、保護されたプラットフォームでのアカウント管理、IP のレピュテーションが重要でありながら速度と安定性も必要な用途に最適です。
Residential	1 億以上の IP を持つプールから割り当てられる実ユーザーの IP です。Datacenter と ISP がブロックされる場合の既定の選択肢です。難しいターゲットでも最も高い成功率を期待できます。GB 単位の従量課金で、速度は遅めです。SSL 証明書または KYC が必要です（以下の「Residential/Mobile ネットワークへのアクセス」を参照）。
Mobile	3G/4G/5G の携帯電話キャリアの IP です。最も高価です。ターゲットの制限が非常に厳しい場合（Instagram、TikTok、一部の銀行）に限って使用してください。ネットワークへのアクセス要件は Residential と同じです。

ユーザーが迷っている場合の既定の順序は、Datacenter → Residential です。ISP と Mobile は、特定のニーズに応じて選択してください。

Decision 2: どの IP プールタイプを選ぶか？（Datacenter と ISP）

Bright Data は、Datacenter と ISP のトラフィックを 3 種類の IP 割り当て方式で提供しています。ユーザーは、コントロールパネルでゾーンを作成するときにこの方式を選びます。

プールタイプ	内容	おすすめの用途
Shared pool（「pay-per-GB」または「unlimited」とも呼ばれます）	大規模な共有プールからランダムな IP を取得します。固定 IP は割り当てられません。トラフィック量に応じて料金を支払います。	大量のローテーション型スクレイピングの標準的な選択肢です。取得する IP の種類にはこだわらず、頻繁に新しい IP を使いたい場合に適しています。
Shared IPs	固定数の N 個の IP がリースされますが、ほかの Bright Data の顧客と共有します。Dedicated より低価格です。	中程度の予算向けです。ある程度 IP を安定させたいものの、専有までは必要ない場合に適しています。ある程度使われた IP を許容するターゲットで便利です。
Dedicated IPs	固定数の N 個の IP が専用にリースされます。ほかの顧客は使用しません。IP ごとのコストが最も高くなります。	IP を厳しくフィンガープリントするプラットフォームでのアカウント管理、管理可能なクリーンなレピュテーションが必要な用途、共有 IP を使うほかの顧客の不適切な行為によって問題が生じると困る用途に適しています。

Residential と Mobile で「dedicated」に相当するのは、-gip- パラメーターで選択する dedicated gIPs（IP グループ）です。DC/ISP の dedicated とは異なります。混同しないでください。

---

プロキシ URL の形式と認証

ユーザー名には、リクエストごとの設定がすべて含まれます。基本形式は次のとおりです。

brd-customer-CUSTOMER_ID-zone-ZONE_NAME[-param1-value1][-param2-value2]...

プロキシ URL に組み込むと、次のようになります。

http://brd-customer-CUSTOMER_ID-zone-ZONE_NAME[-PARAMS]:[email protected]:33335

注意点：

• HTTPS のターゲットであっても、スキームは http:// です。これはプロキシ自体のスキームであり、接続先のスキームではありません。
• パスワードに特殊文字が含まれる場合は、必ず URL エンコードしてください。
• パラメーターはハイフンでユーザー名に追加します。URL のクエリ文字列パラメーターではありません。
• ゾーン名は作成後に変更できません。別の名前にしたい場合は、新しいゾーンを作成する必要があります。

ユーザー名のパラメーター（ターゲティング、ローテーション、セッション）

パラメーター	対象	動作	ユーザー名のサフィックスの例
-country-XX	すべてのネットワーク	ISO 国コード（小文字 2 文字）。eu はランダムな EU 諸国を表します。	-country-us
-state-XX	Residential、Mobile のみ	米国の州（2 文字）。-country-us が必要です	-country-us-state-ny
-city-NAME	Residential、Mobile のみ	都市名。スペースは使用できません（sanfrancisco）。国の指定が必要です	-country-us-city-sanfrancisco
-zip-NNNNN	Residential、Mobile のみ	米国の ZIP コード（5 桁）	-country-us-zip-37501
-asn-NNNNN	Residential、Mobile のみ	特定の ASN をターゲットにします	-asn-56386
-os-X	Residential のみ	windows、macos、android	-os-windows
-carrier-X	Mobile のみ	特定の通信事業者（例：-carrier-dt）	-carrier-dt
-session-STRING	すべて	スティッキーセッション。同じセッション ID を指定すると、セッションの有効期間中は同じ出口 IP が返されます。ローテーションを実装するには、論理的な「ユーザーセッション」ごとにランダムな文字列を使用します。	-session-abc12345
-ip-A.B.C.D	Dedicated IPs を持つゾーンのみ	割り当て済みの特定 IP に固定します	-ip-1.2.3.4
-gip-NAME	Dedicated Residential または Mobile のみ	特定の gIP グループに固定します	-gip-us_7922_fl_hollywood_0
-dns-local / -dns-remote	すべて	remote はプロキシピアで DNS を解決します（Residential のデフォルト）。local はスーパー プロキシで解決します	-dns-remote
-const	Residential、Mobile	同じピアに固定します。ピアが利用できない場合、切り替える代わりに 502「no peer available」を返します	-const
-direct	すべて	スーパー プロキシ自体からリクエストを送信するよう指定します（ピアルーティングをスキップ）。通常は必要ありません。	-direct
-c_tag-VALUE	すべて	レスポンスヘッダーにエコーされるカスタムタグです。大量のリクエストとレスポンスの関連付けに使用します	-c_tag-job42-row7

重要な制約：Datacenter と ISP のゾーンでは、国によるターゲティングのみをサポートしています。州、都市、ZIP コード、ASN、OS、通信事業者によるターゲティングは Residential/Mobile 専用です。DC または ISP のゾーンに -city- を指定するコードを生成しないでください。エラーにならずに失敗するか、400 が返されます。

セッションとローテーションのパターン

• リクエストごとに新しい IP が必要ですか？ -session- を省略します。スーパー プロキシがリクエストごとに新しいピアを割り当てます。
• 複数ステップのフロー（ログイン → 操作 → 操作）の間、同じ IP を維持しますか？ ランダムな session_id を一度生成して再利用します：-session-{session_id}。新しい値を使うと、新しい IP になります。
• アイドル状態のセッションのタイムアウト（アイドル状態が長く続くと IP を失います。Bright Data のドキュメントを参照）：データセンターは約 1 分、レジデンシャルは約 5 分、ISP は約 7 分、モバイルは約 10 分です。タイムアウトを超えるフローでは、キープアライブリクエストを送信するか、IP がローテーションすることを許容してください。
• 最大限の制御：専用 IP ゾーンと -ip-A.B.C.D を使って、割り当て済みの特定の IP にすべてのリクエストを固定します。ランダム性はありません。

---

基本的なコードパターン

cURL（テスト／デバッグ用）

curl --proxy brd.superproxy.io:33335 \
  --proxy-user 'brd-customer-CUSTOMER_ID-zone-ZONE_NAME:ZONE_PASSWORD' \
  --cacert ./assets/brightdata_proxy_ca.crt \
  'https://geo.brdtest.com/mygeo.json'

（データセンターゾーンと ISP ゾーンでは、--cacert フラグは任意です。レジデンシャルゾーンとモバイルゾーンでは、ユーザーが CA をシステムにインストール済み、または KYC を完了していない限り必須です。以下の「レジデンシャルおよびモバイルのネットワークアクセス」を参照してください。）

証明書の検証を完全に回避する場合（ユーザーが「SSL エラーを無視する」方法を選んだ場合のみ可）：

curl -k --proxy brd.superproxy.io:33335 \
  --proxy-user 'brd-customer-CUSTOMER_ID-zone-ZONE_NAME:ZONE_PASSWORD' \
  'https://geo.brdtest.com/mygeo.json'

Python — requests

import requests

CUSTOMER_ID = "your_customer_id"
ZONE_NAME = "your_zone_name"
ZONE_PASSWORD = "your_zone_password"

proxy_user = f"brd-customer-{CUSTOMER_ID}-zone-{ZONE_NAME}"
proxy_url = f"http://{proxy_user}:{ZONE_PASSWORD}@brd.superproxy.io:33335"

proxies = {"http": proxy_url, "https": proxy_url}

# Preferred: verify TLS using the bundled Bright Data CA
resp = requests.get(
    "https://geo.brdtest.com/mygeo.json",
    proxies=proxies,
    verify="./assets/brightdata_proxy_ca.crt",  # path to bundled cert
    timeout=30,
)
print(resp.json())

国の指定：

proxy_user = f"brd-customer-{CUSTOMER_ID}-zone-{ZONE_NAME}-country-us"

スティッキーセッション（論理ユーザーごとにローテーションし、セッション内では同じ IP を使用）：

import secrets
session_id = secrets.token_hex(8)
proxy_user = f"brd-customer-{CUSTOMER_ID}-zone-{ZONE_NAME}-country-us-session-{session_id}"

多数のリクエストでローテーションする場合 — 各リクエストに専用のセッション ID を割り当てます：

import secrets, requests

def proxy_for_request():
    sid = secrets.token_hex(8)
    user = f"brd-customer-{CUSTOMER_ID}-zone-{ZONE_NAME}-session-{sid}"
    url = f"http://{user}:{ZONE_PASSWORD}@brd.superproxy.io:33335"
    return {"http": url, "https": url}

for target in targets:
    requests.get(target, proxies=proxy_for_request(), verify=CA_PATH, timeout=30)

Node.js — undici / fetch（Node 18+）

import { fetch, ProxyAgent } from 'undici';

const CUSTOMER_ID = 'your_customer_id';
const ZONE_NAME = 'your_zone_name';
const ZONE_PASSWORD = 'your_zone_password';

const proxyUser = `brd-customer-${CUSTOMER_ID}-zone-${ZONE_NAME}`;
const proxyUrl = `http://${proxyUser}:${ZONE_PASSWORD}@brd.superproxy.io:33335`;

const agent = new ProxyAgent(proxyUrl);

const res = await fetch('https://geo.brdtest.com/mygeo.json', { dispatcher: agent });
console.log(await res.json());

Node で CA を検証するには、環境で NODE_EXTRA_CA_CERTS=/path/to/brightdata_proxy_ca.crt を設定するか、ca を設定したカスタム Agent を渡します。証明書のチェックを回避する場合（最後の手段）：NODE_TLS_REJECT_UNAUTHORIZED=0。

Node.js — https-proxy-agent を使用する axios

import axios from 'axios';
import { HttpsProxyAgent } from 'https-proxy-agent';

const proxyUrl = `http://brd-customer-${CUSTOMER_ID}-zone-${ZONE_NAME}:${ZONE_PASSWORD}@brd.superproxy.io:33335`;
const agent = new HttpsProxyAgent(proxyUrl);

const res = await axios.get('https://geo.brdtest.com/mygeo.json', {
  httpAgent: agent,
  httpsAgent: agent,
  proxy: false, // important: tell axios to use our agent, not its own proxy logic
});
console.log(res.data);

フレームワークとの連携（Playwright、Puppeteer、Selenium、Scrapy、httpx、aiohttp）や追加のパターンについては、references/code-templates.md を参照してください。

---

レジデンシャルおよびモバイルのネットワークアクセス

レジデンシャルとモバイルには、データセンターや ISP にはないネットワークアクセスポリシーがあります。任意の HTTPS ターゲットへのリクエストを成功させるには、ユーザーは次の 3 つの方法から 1 つ を選ぶ必要があります。

1. Bright Data CA 証明書を使用する（推奨 — ほとんどのユーザーに推奨される方法）。この証明書は、このスキルの assets/brightdata_proxy_ca.crt にすでに含まれています。適用方法は 2 つあります。
   • リクエストごとにコード内で読み込む（システムへのインストールは不要）。Python の requests の場合：verify="./assets/brightdata_proxy_ca.crt"。cURL の場合：--cacert ./assets/brightdata_proxy_ca.crt。Node の場合：環境変数 NODE_EXTRA_CA_CERTS=./assets/brightdata_proxy_ca.crt を設定するか、ca を設定したカスタム Agent を渡します。これが最も簡潔な方法であり、生成コードではデフォルトとして推奨されます。
   • 証明書をシステムにインストールする（Windows／macOS Keychain／Linux の update-ca-certificates／iOS／Android）。CA 証明書のオプションを公開していないサードパーティ製ツールを使う場合に必要です。含まれている assets/brightdata_proxy_ca.crt を適切な信頼ストアにコピーし、その後アプリを再起動します。ユーザーが個別に取得したい場合は、公開ミラー https://brightdata.com/static/brightdata_proxy_ca.zip を利用できます。
2. KYC 認証。Bright Data のコントロールパネルで本人確認を申請します。承認後、ネイティブのプロキシアクセスでは証明書が不要になります。
3. SSL エラーを無視する（最後の手段。本番環境では推奨されません）。Python の場合：requests.get(..., verify=False)。Node の場合：rejectUnauthorized: false または NODE_TLS_REJECT_UNAUTHORIZED=0。cURL の場合：-k。この方法は機能しますが、中間者攻撃（MITM）に対するエンドツーエンド暗号化の保証が失われます。一時的なテストなら問題ありませんが、認証情報や個人識別情報を扱う用途には適しません。

レジデンシャル／モバイル向けの生成コードでは、方法 1a（コード内で CA を読み込む）をデフォルトとし、ユーザーが入力する証明書のパスはプレースホルダーにしてください。方法 2 と 3 については、代替手段として簡潔に説明してください。

データセンターと ISP では、このポリシーが適用されないため、上記の対応は不要です。

---

テストとデバッグ

実際のターゲットをスクレイピングする前に、プロキシが動作することを確認してください。以下のバンドル済みツールを使えば、エンドツーエンドで確認できます。

1. コマンドラインのスモークテスト — scripts/smoke_test.sh：

./scripts/smoke_test.sh CUSTOMER_ID ZONE_NAME ZONE_PASSWORD
# with optional country and sticky session:
./scripts/smoke_test.sh CUSTOMER_ID ZONE_NAME ZONE_PASSWORD us my-session-1

# or via env vars:
BD_CUSTOMER_ID=xxx BD_ZONE=yyy BD_PASSWORD=zzz ./scripts/smoke_test.sh

ゾーン経由で geo.brdtest.com/mygeo.json にアクセスし、解析済みの JSON（IP、国、都市、ASN）を返します。終了コードは認証失敗（2）と HTTP エラー（3）を区別するため、スクリプトからの利用にも適しています。

2. ブラウザー診断 — scripts/proxy_tester.html：

ファイルをブラウザーで開きます。地理情報エンドポイントに継続的にポーリングし、出口 IP／国／都市／ASN を表示します。ゾーンの認証情報を入力すると、ブラウザーまたは OS のプロキシ設定に貼り付けるための正確なプロキシ設定文字列が生成されます。「Save as baseline」ボタンを押すと、プロキシ使用前の IP が記録されるため、プロキシが有効になっていることを視覚的に確認できます（ステータスが緑色に変わり、変更前から変更後への変化が表示されます）。プロキシが動作していることをチームメイトに説明するときや、「ブラウザーの通信は実際にプロキシ経由なのか」という質問のデバッグに便利です。

手早く確認する場合は、cURL を直接使うこともできます。

curl --proxy brd.superproxy.io:33335 \
  --proxy-user 'brd-customer-CUSTOMER_ID-zone-ZONE_NAME:ZONE_PASSWORD' \
  --cacert ./assets/brightdata_proxy_ca.crt \
  'https://geo.brdtest.com/mygeo.json'

想定される結果は、ip、country、asn、geo を含む JSON です。これが表示されれば、認証とルーティングは正常に動作しています。Google、Bing、その他の検索エンジンに対して直接テストしないでください。Bright Data は、プロキシネットワークからの検索エンジンへの直接アクセスをブロックしています。その場合は SERP API を使用してください。

よくあるエラーとその意味（特に重要なもの）：

• 407 Proxy Authentication Required：ユーザー名の構成が間違っているか、ゾーンパスワードが正しくありません。brd-customer- プレフィックスと -zone- の部分を再確認してください。顧客 ID はメールアドレスではなく、コントロールパネルに記載されています。
• 502 "no peer available"：通常、オフラインの IP に対して -const または -ip- を指定した場合に発生します。-const を削除するか、別の IP を選んでください。
• 宛先からの 403（Bright Data からではない）：宛先がプロキシ IP をブロックしています。Residential を試す、スティッキーセッションを追加する、リクエスト頻度を下げる、または Web Unlocker API を使ってください。
• Residential／Mobile での TLS／証明書エラー：ネットワークアクセスの設定を省略しています。証明書をインストールする（またはコード内で読み込む）か、ひとまず verify=False に切り替えてください。
• DC／ISP でターゲティングが無視される：DC／ISP ゾーンで -city- または -state- を使用しています。これらのゾーンで有効なのは -country- のみです。

上記にない Bright Data の特定のエラーコードについては、完全なカタログ（https://docs.brightdata.com/proxy-networks/errorCatalog）で確認してください。正確なコードを特定するにはレスポンスヘッダーを調べてください。Bright Data は旧式の x-brd-err-code ヘッダーから RFC 9209 標準の Proxy-Status ヘッダーへの移行を進めているため、生成するデバッグコードでは両方を確認する必要があります。コードは category_number という形式で、どのレイヤーで失敗したかをすぐに把握できます。たとえば、client_*（認証またはリクエスト形式。例：client_10000）、policy_*（Bright Data によるポリシーブロック。例：policy_20050）、target_*（宛先側の失敗。例：target_40011）などです。

---

ユーザーがまだゾーンを設定していない場合

コントロールパネルでの手順をスクリプト化したり、ゾーン作成のためにアカウント管理 API を呼び出したりしないでください。これらの手順は対話形式で、アカウントごとに異なります。代わりに、次のように案内してください。

https://brightdata.com で登録してください（新規アカウントには 7 日間有効な $2 のトライアルクレジットが付与されます。また、支払い方法を追加すると 30 日間有効な $5 のボーナスも受け取れます。ただし、プロキシ製品は別途課金され、月ごとの無料クレジットの対象外です）。ログインしたら、Proxies & Scraping → Add をクリックしてください。アプリ内のガイドに従って、ネットワークとプールタイプを選び、ゾーンに名前を付けます。完了したら、ゾーンの概要ページから customer ID、zone name、zone password をコピーして、ここに貼り付けてください。コードを生成します。

コントロールパネルの proxy_examples ページ（https://brightdata.com/cp/zones/proxy_examples）には、多くの言語やフレームワーク向けの、アカウント固有の最新コード例も掲載されています。このスキルの内容が古くなっていると思われる場合は、内容を照合するために利用してください。

---

参照ファイル

• references/code-templates.md — Playwright、Puppeteer、Selenium（最新の認証拡張機能方式と SeleniumWire のフォールバック）、Scrapy、httpx、aiohttp、およびいくつかの言語バリエーション向けの、完全に動作するコードです。上記で扱われていない特定のフレームワークについてユーザーから質問があった場合に参照してください。
• references/troubleshooting.md — エラーの詳細なカタログとデバッグ手順です。ユーザーからエラーや予期しない動作の報告があった場合に参照してください。
• assets/brightdata_proxy_ca.crt — Bright Data Proxy Root CA（ポート 33335、有効期限は 2034 年 9 月）です。Residential または Mobile ゾーンを使用するコードを生成する際は、このパスを参照してください。
• scripts/smoke_test.sh — cURL 認証情報のスモークテスト（Testing セクションを参照）です。
• scripts/proxy_tester.html — 単一ファイルのブラウザ診断ツール（Testing セクションを参照）です。