brightdata/bright-data-best-practices

bright-data-best-practices は何をしますか？

ベストプラクティスを組み込んだ本番対応のBright Data統合を構築します。コーディングアシスタント（Claude Code、Cursorなど）を使用してWebスクレイピング、検索、ブラウザ自動化、構造化データ抽出を実装する開発者向けのリファレンスドキュメントです。以下のAPIをカバーしています：

• Web Unlocker API
• SERP API
• Web Scraper API
• Browser API（Scraping Browser）

はじめに

認証

Bright Data APIを使用するには、アカウントのダッシュボードから取得した認証情報（トークンまたはAPIキー）が必要です。環境変数として設定することを推奨します。

export BRIGHTDATA_TOKEN="your_token_here"
export BRIGHTDATA_API_KEY="your_api_key_here"

一般的なリクエストパターン

すべてのAPIはHTTPSエンドポイントを通じてアクセス可能です。以下は、Pythonのrequestsライブラリを使用した基本的な例です。

import requests
import os

headers = {
    "Authorization": f"Bearer {os.getenv('BRIGHTDATA_TOKEN')}",
    "Content-Type": "application/json"
}
response = requests.get("https://api.brightdata.com/v1/endpoint", headers=headers)

Web Unlocker API

Web Unlocker APIは、CAPTCHAの解決、IPブロックの回避、ブラウザフィンガープリンティングの管理など、高度なアンチブロッキング機能を提供します。

主要な機能

• 自動CAPTCHA解決
• 自動IPローテーション
• ブラウザフィンガープリントのランダム化
• JavaScriptレンダリングのサポート

使用例

import requests

url = "https://example.com/target-page"
response = requests.post(
    "https://api.brightdata.com/v1/webunlocker",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    json={
        "url": url,
        "country": "us",
        "wait_for": 5000  # ミリ秒
    }
)
data = response.json()

ベストプラクティス

• エラーハンドリング: HTTP 429（レート制限）や503（サービス利用不可）に対応するリトライロジックを実装してください。
• タイムアウト設定: リクエストには適切なタイムアウト（例：30秒）を設定してください。
• 同時実行制限: ダッシュボードで設定された同時リクエスト数を超えないようにしてください。

SERP API

SERP APIは、Google、Bing、Yahooなどの検索エンジンから構造化された検索結果を取得するために使用します。

主要な機能

• 複数検索エンジンのサポート
• カスタム検索パラメータ（地域、言語、日付範囲など）
• 構造化JSONレスポンス
• ページネーションのサポート

使用例

import requests

response = requests.post(
    "https://api.brightdata.com/v1/serp",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    json={
        "q": "最新のAI技術",
        "source": "google",
        "gl": "jp",  # 国コード
        "hl": "ja"   # 言語コード
    }
)
results = response.json()

ベストプラクティス

• 検索クエリのエンコード: 特殊文字やURLエンコードが必要なクエリは適切に処理してください。
• レート制限: APIのレート制限を尊重し、必要に応じてリクエスト間にディレイを入れてください。
• 結果のキャッシュ: 同じクエリに対する結果をローカルにキャッシュして、重複リクエストを避けてください。

Web Scraper API

Web Scraper APIは、特定のWebページからデータを抽出するために使用します。カスタムCSSセレクタやXPathを使用して、必要な要素のみを取得できます。

主要な機能

• CSSセレクタとXPathによるターゲット要素の指定
• JavaScriptレンダリングのサポート
• ページ全体のHTMLまたは特定セクションの取得
• ページネーションの自動処理

使用例

import requests

response = requests.post(
    "https://api.brightdata.com/v1/webscraper",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    json={
        "url": "https://example.com/products",
        "selector": "div.product-item",
        "extract": [
            {"name": "title", "selector": "h2.product-title"},
            {"name": "price", "selector": "span.product-price"},
            {"name": "link", "selector": "a.product-link", "attribute": "href"}
        ]
    }
)
data = response.json()

ベストプラクティス

• セレクタの精度: 変更に強い安定したセレクタ（IDやデータ属性ベース）を使用してください。
• エラーハンドリング: ページが変更された場合に備えて、セレクタが要素を見つけられなかった場合の処理を実装してください。
• データ検証: 抽出したデータの型や形式を検証する処理を追加してください。

Browser API（Scraping Browser）

Browser APIを使用すると、ヘッドレスブラウザをリモートで操作できます。複雑なWeb操作やJavaScriptによる動的コンテンツの処理に適しています。

主要な機能

• Puppeteer/Playwright互換のAPI
• 完全なブラウザ自動化（クリック、フォーム入力、ナビゲーション）
• スクリーンショットとPDFの生成
• カスタムJavaScriptの実行

使用例

const puppeteer = require('puppeteer');

async function run() {
  const browser = await puppeteer.connect({
    browserWSEndpoint: `wss://api.brightdata.com/v1/browser?token=YOUR_TOKEN`
  });
  const page = await browser.newPage();
  await page.goto('https://example.com');
  const title = await page.title();
  console.log(title);
  await browser.close();
}
run();

ベストプラクティス

• セッション管理: 長時間のスクレイピングでは、ブラウザセッションを適切に管理し、不要になったら閉じてください。
• エラーハンドリング: ネットワークエラーやブラウザクラッシュに対処するために、try-catchブロックを使用してください。
• リソース最適化: 不要な画像やスクリプトの読み込みをブロックして、帯域幅とパフォーマンスを最適化してください。

await page.setRequestInterception(true);
page.on('request', (request) => {
  if (['image', 'stylesheet', 'font'].includes(request.resourceType())) {
    request.abort();
  } else {
    request.continue();
  }
});

一般的なベストプラクティス

• 環境変数: APIキーやトークンはコードに直接記述せず、環境変数またはシークレット管理サービスを使用してください。
• ログ記録: デバッグと監査のために、適切なログ記録を実装してください。
• レート制限の管理: APIのレート制限を監視し、制限に近づいたらリクエストを抑制するロジックを追加してください。
• データ保存: スクレイピングしたデータは、データベースやファイルシステムに構造化して保存してください。
• エラーハンドリング: すべてのAPIリクエストに対して、タイムアウト、リトライ、例外処理を実装してください。

参考リンク

• Bright Data 公式ドキュメント
• ダッシュボード
• APIリファレンス