プログラマー向けモードで表示中ビジネスユーザー向けへ →
Bright Data 学習ポータル

Step 1 ・ Lv1 ・ 目安 45 分

Step 1 認証完全ガイド

API Access / Native Access の両方で「最初の 1 回」を curl / Python / Node で通し、権限モデルとキー運用の型を身につける。

はじめに

このガイドを完了すると、API Access（Bearer） と Native Access（Proxy） の両方で、Bright Data の Web Unlocker エンドポイントに対して最初のリクエストを curl / Python / Node.js で実行できるようになります。さらに、Dashboard から zone, customer ID, proxy password を取得する手順と、権限モデル・API キーのローテーション運用方法も学べます。

ゴールと所要時間

  • ゴール：API Access と Native Access の両方で Web Unlocker を呼び出し、正常にデータが取得できること
  • 所要時間：約 45 分
  • 難易度：Lv1（初心者向け）

前提

  • Bright Data アカウントが作成済み
  • Dashboard で Web Unlocker 用の ゾーン を 1 つ作成済み
  • $BRIGHTDATA_API_KEY（API キー）と $BRIGHTDATA_PROXY_PASSWORD（プロキシパスワード）を環境変数として設定済み

Tip：環境変数はシェルの export コマンドや .env ファイルで管理すると安全です。

手順 1：Dashboard で API キー発行（USER 権限、90 日有効）

操作メニュー説明
1Dashboard → API キー「新規作成」ボタンをクリック
2権限USER を選択
3有効期限90 日 を選択
4作成「作成」ボタンをクリックし、表示されたキーをコピー
5保存キーを $BRIGHTDATA_API_KEY に設定（例: export BRIGHTDATA_API_KEY=xxxxxxxxxxxx）

権限モデル（概要）

Bright Data の API キーは 5 段階の権限を持ちます。日常の API 呼び出しには最小権限（USER / OPS）を割り当ててください。

ロールBillingプロダクト設定Proxy/API 利用推奨使用シーン
ADMIN○○○管理者。金庫管理、通常運用では使わない
FINANCE○××経理・請求確認のみ
OPS×○○ゾーン設定管理・運用
LIMIT×△○Proxy パスワード・IP allow/deny のみ
USER××○日常の API 利用（アプリ・バッチ）

詳細は認証ガイドを参照。

ローテーション運用：90 日ごとに新しいキーを作成し、古いキーは Refresh で即時無効化します。CI/CD パイプラインでは環境変数を更新するだけで対応可能です。

手順 2：API Access（Bearer）で Web Unlocker を curl 呼び出し

# 必要な変数
export BRIGHTDATA_API_KEY=YOUR_API_KEY
export ZONE_ID=YOUR_ZONE_ID   # Dashboard の「ゾーン」ページで確認
 
# リクエスト
curl -X POST "https://api.brightdata.com/request" \
  -H "Authorization: Bearer $BRIGHTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://httpbin.org/get",
        "zone": "'"$ZONE_ID"'",
        "type": "webunlocker"
      }'

期待されるレスポンス（抜粋）

{
  "status": "ok",
  "data": {
    "url": "https://httpbin.org/get",
    "content": "{...}"
  }
}

手順 3：Python SDK（brightdata-sdk）で同じことを呼び出す

# SDK のインストール
pip install brightdata-sdk
import os
import json
from brightdata import BrightDataClient
 
# 環境変数から取得
api_key = os.getenv("BRIGHTDATA_API_KEY")
zone_id = os.getenv("ZONE_ID")
 
client = BrightDataClient(api_key=api_key)
 
# Web Unlocker 呼び出し
response = client.request(
    url="https://httpbin.org/get",
    zone=zone_id,
    request_type="webunlocker"
)
 
print(json.dumps(response, indent=2, ensure_ascii=False))

手順 4：Node.js（fetch）で同じことを呼び出す

# Node.js 18+ で組み込み fetch が利用可能
npm i dotenv   # 任意：.env ファイルから環境変数をロード
// index.js
require('dotenv').config(); // .env がある場合
 
const apiKey = process.env.BRIGHTDATA_API_KEY;
const zoneId = process.env.ZONE_ID;
 
async function requestWebUnlocker() {
  const res = await fetch('https://api.brightdata.com/request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: 'https://httpbin.org/get',
      zone: zoneId,
      type: 'webunlocker'
    })
  });
 
  if (!res.ok) {
    console.error('リクエスト失敗:', res.status, await res.text());
    return;
  }
 
  const data = await res.json();
  console.log(JSON.stringify(data, null, 2));
}
 
requestWebUnlocker();
node index.js

手順 5：Native Access に切替、プロキシ経由で同じ URL を取得

  1. プロキシ情報の取得（Dashboard → プロキシ → 詳細）
項目例
ホストbrd.superproxy.io
ポート33335
ユーザー名brd-customer-<ACCOUNT_ID>-zone-<PRODUCT_NAME>
パスワード$BRIGHTDATA_PROXY_PASSWORD

ACCOUNT_ID の取得元: Dashboard 右上のアカウントメニュー、または Account settings → Overview に表示される hl_ で始まる ID。プロキシページの Access Details / Code examples に出る username (brd-customer-...) からも確認できます。

  1. curl でプロキシ経由リクエスト
export BRIGHTDATA_PROXY_PASSWORD=YOUR_PROXY_PASSWORD
export PROXY_USER=brd-customer-123456-zone-webunlocker
 
curl -x "http://$PROXY_USER:$BRIGHTDATA_PROXY_PASSWORD@brd.superproxy.io:33335" \
  "https://httpbin.org/get"
  1. Python（requests）でプロキシ経由
import os
import requests
 
proxy_user = f"brd-customer-{os.getenv('ACCOUNT_ID')}-zone-webunlocker"
proxy_pass = os.getenv("BRIGHTDATA_PROXY_PASSWORD")
 
proxies = {
    "http": f"http://{proxy_user}:{proxy_pass}@brd.superproxy.io:33335",
    "https": f"http://{proxy_user}:{proxy_pass}@brd.superproxy.io:33335"
}
 
resp = requests.get("https://httpbin.org/get", proxies=proxies)
print(resp.text)
  1. Node.js（fetch）でプロキシ経由（https-proxy-agent が必要）
npm i https-proxy-agent
require('dotenv').config();
const fetch = require('node-fetch');
const HttpsProxyAgent = require('https-proxy-agent');
 
const proxyUser = `brd-customer-${process.env.ACCOUNT_ID}-zone-webunlocker`;
const proxyPass = process.env.BRIGHTDATA_PROXY_PASSWORD;
const proxyUrl = `http://${proxyUser}:${proxyPass}@brd.superproxy.io:33335`;
 
const agent = new HttpsProxyAgent(proxyUrl);
 
fetch('https://httpbin.org/get', { agent })
  .then(r => r.text())
  .then(console.log)
  .catch(console.error);

手順 6：Playwright / Puppeteer での接続コード（参考）

Playwright（Node.js）

npm i -D @playwright/test
// playwright-test.js
require('dotenv').config();
const { chromium } = require('playwright');
 
(async () => {
  const proxyUser = `brd-customer-${process.env.ACCOUNT_ID}-zone-webunlocker`;
  const proxyPass = process.env.BRIGHTDATA_PROXY_PASSWORD;
 
  const browser = await chromium.launch({
    proxy: {
      server: 'brd.superproxy.io:33335',
      username: proxyUser,
      password: proxyPass
    }
  });
 
  const page = await browser.newPage();
  await page.goto('https://httpbin.org/get');
  const content = await page.content();
  console.log(content);
  await browser.close();
})();

Puppeteer

npm i puppeteer
// puppeteer-test.js
require('dotenv').config();
const puppeteer = require('puppeteer');
 
(async () => {
  const proxyUser = `brd-customer-${process.env.ACCOUNT_ID}-zone-webunlocker`;
  const proxyPass = process.env.BRIGHTDATA_PROXY_PASSWORD;
 
  const browser = await puppeteer.launch({
    args: [
      '--proxy-server=brd.superproxy.io:33335',
      `--proxy-auth=${proxyUser}:${proxyPass}`
    ]
  });
 
  const page = await browser.newPage();
  await page.authenticate({ username: proxyUser, password: proxyPass });
  await page.goto('https://httpbin.org/get');
  const html = await page.content();
  console.log(html);
  await browser.close();
})();

失敗時のチェックリスト

エラーコード主な原因対処法
401API キーが無効または期限切れ$BRIGHTDATA_API_KEY が正しいか、期限を確認
403プロキシ認証失敗、ゾーンが無効$BRIGHTDATA_PROXY_PASSWORD と PROXY_USER を再確認
SSL_ERROR証明書エラー（自己署名等）curl -k（テスト限定）または OS の証明書ストアを更新
Timeoutネットワーク障害、ゾーンが停止中Dashboard でゾーンステータスを確認、プロキシポートが開いているか確認

次に読む

  • 認証の理論 → /authentication
  • 次のハンズオン → /hands-on/step-2-serp-rank
  • 認証方式の比較 → /basics/auth-methods

参考リンク