基礎 / 認証方式

Bright Data では、同じプロダクトでも API Access と Native Access の 2 系統で接続できます。課金レートはどちらを選んでも同じなので、判断軸は「どの実装に最短で組み込めるか」と「運用をどこで制御したいか」です。

このページでは、認証ガイド を前提に、実装寄りの観点で両方式を比較します。最初に全体像をつかみ、最後に curl、Python、Node.js の最小例まで確認すると、どちらで着手すべきか迷いにくくなります。

一次情報: Authentication | Bright Data Docs

まず結論

• 新規実装なら、まずは API Access を優先するのが基本です。
• 既存のプロキシ前提ツールを載せ替えるなら、Native Access のほうが変更範囲を抑えられます。
• Browser API や Web Unlocker のように、ユースケース次第で両方の入り口を持てる製品は、チーム事情で選んで問題ありません。

API Access を選ぶ場面

API Access は、Bearer トークンを HTTP ヘッダーに付ける方式です。JSON をそのままアプリケーションに流し込めるため、Bright Data を「外部 API のひとつ」として扱えます。

特に次の条件に当てはまるなら、API Access で始めるのが自然です。

• 収集結果を Node.js、Python、ワークフローエンジンでそのまま処理したい
• zone、URL、出力形式、ジョブ ID をアプリケーションコード側で明示したい
• SERP API、Browser API、Crawl API、Scrapers、Discover、Deep Lookup を横断して使いたい
• USER / OPS 権限の API キーを分け、職務分離をしやすくしたい

API Access の利点

API Access の注意点

• 既存ツールが --proxy 前提なら、API 化のために呼び出し側を書き換える必要があります。
• Refresh でキーを再生成すると旧キーは即時無効化されます。段階切替をしたい場合は、最初から複数キーで運用します。
• 失敗時の再試行やキューイングは、アプリ側で持つ設計になりやすいです。詳しくは 基礎 / 運用 を参照してください。

Native Access を選ぶ場面

Native Access は、Bright Data をプロキシとして使う方式です。host:port + username:password を設定できるツールなら、そのまま接続できることが多く、既存資産のリフトに向きます。

次の条件に当てはまるなら、Native Access が近道です。

• すでに Playwright、Puppeteer、Selenium、独自クローラがあり、HTTP プロキシだけ差し込みたい
• 出力は HTML やネットワークレスポンスをそのまま受け取り、後段で独自パースしたい
• プロキシ認証の Runbook が既に社内で整っている

Native Access の利点

Native Access の注意点

• PRODUCT_NAME は zone 作成時の名前で、後から変更できません。命名を先に決める必要があります。
• Residential network と Web Unlocker を KYC なしで使うケースでは、証明書の考慮が必要です。
• 権限管理は API キーのような細かい PermissionLevel ではなく、zone とパスワードの管理が中心になります。

詳細比較

認証情報の持ち方

API Access は、人・環境・ジョブ単位でキーを分ける設計に向いています。Native Access は、接続先のアプリがプロキシをどう扱うかに強く依存します。

レスポンス設計

非同期処理や Webhook を使う設計なら、ほぼ API Access 一択です。逆に、1 ページずつ人間がブラウザで確認しながら進めるような検証では Native Access が便利です。

運用責任の置き場所

判断フロー

以下の順に考えると、選択を誤りにくくなります。

1. 既存実装がプロキシ前提か、HTTP API 前提かを確認する
2. 結果を JSON として扱いたいか、HTML を自前で処理したいかを決める
3. キー期限や権限分離を API キー単位で管理したいか確認する
4. 非同期ジョブや Webhook を将来使うなら API Access を優先する
5. 短期の移行なら Native Access、中長期の統合基盤なら API Access を検討する

API Access を選ぶべきサイン

• バッチ、ETL、スケジューラ、CI で呼び出す
• ロードマップ Lv2 以降で複数 API を横断して学びたい
• 基礎 / API グループ にある複数製品を同じ書き方で試したい

Native Access を選ぶべきサイン

• 既存 Playwright スクリプトの proxy 設定だけ変えたい
• ブラウザを人間が操作しながら調査する
• 社内の監視・ログ基盤が既にプロキシ接続を中心に設計されている

実装例 1: curl で API Access

最初の 1 回を通すなら、/request エンドポイントに zone と url を渡すのがわかりやすいです。

curl -X POST https://api.brightdata.com/request \
  -H "Authorization: Bearer $BRIGHTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "zone": "web_unlocker1",
    "url": "https://example.com",
    "format": "raw"
  }'

• web_unlocker1 は例です。実際には自分の zone 名を使います。
• format を変えると、後段での扱い方が変わります。

実装例 2: Python で API Access

運用コードの最小形です。requests で十分始められます。

import os
import requests
 
response = requests.post(
    "https://api.brightdata.com/request",
    headers={
        "Authorization": f"Bearer {os.environ['BRIGHTDATA_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "zone": "web_unlocker1",
        "url": "https://example.com",
        "format": "raw",
    },
    timeout=60,
)
 
response.raise_for_status()
print(response.text[:400])

• API Access は、例外処理、再試行、メトリクスの挿入がしやすい形です。
• 本格運用では、HTTP 429 や timeout を見てバックオフします。

実装例 3: Node.js で API Access

Node.js では fetch だけでも十分です。

const response = await fetch("https://api.brightdata.com/request", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.BRIGHTDATA_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    zone: "web_unlocker1",
    url: "https://example.com",
    format: "raw"
  })
});
 
if (!response.ok) {
  throw new Error(`Bright Data request failed: ${response.status}`);
}
 
const body = await response.text();
console.log(body.slice(0, 400));

• バックエンド API やジョブワーカーへそのまま組み込みやすい書き方です。
• ロードマップ Lv2 では、この形を土台に SERP API や Browser API へ広げます。

Native Access の最小確認

比較のため、Native Access 側の最小確認も載せておきます。既存クローラの延長で試すならこちらです。

curl --proxy brd.superproxy.io:33335 \
  --proxy-user "brd-customer-$ACCOUNT_ID-zone-$PRODUCT_NAME:$PROXY_PASSWORD" \
  -k https://geo.brdtest.com/welcome.txt

• ACCOUNT_ID は hl_ で始まる顧客 ID です。
• PRODUCT_NAME は zone 名で、作成後は変更できません。
• 証明書要件がある環境では、-k に頼らず正規に証明書を配備します。

チーム別のおすすめ

迷ったときの実務ルール

• 新規プロジェクトなら API Access で始める
• 既存資産の短期移行なら Native Access を優先する
• zone は用途別に分け、検証・本番を混ぜない
• API キーは USER か OPS で発行し、ADMIN を埋め込まない
• 3 か月後に非同期や Webhook が必要になりそうなら、最初から API Access に寄せる

次に読む

• 認証ガイド
• 基礎 / API グループ
• 基礎 / 運用
• Step 1 認証完全ガイド
• ロードマップ Lv1