UC-WEB-005Web AccessLv3Lv4

AI システムへの Web データ統合

アプリ／ETL／AI ワークフローに Web データ取得を直接組み込み、運用を一本化する。

Web Access APIsSDK

KPI 例

接続系統数
データ鮮度
稼働率

AI システムで重要なのは、単発で取得できることよりも、どの API をどの条件で呼ぶかを一貫した形にすることです。検索結果は SERP API、保護ページは Web Unlocker、広域収集は Crawl API と役割を分け、そのうえで認証、zone、保存形式を共通化しておくと、後段の評価や再実行がかなり楽になります。

このページでは、公式の Python SDK / JavaScript SDK を使う前提も含めつつ、まずは API 呼び出しの共通面を固める考え方を扱います。SDK の詳細シグネチャは公式ドキュメントを参照し、このサイトでは 共通設計の最小形 に絞ります。

誰の課題か

RAG、調査エージェント、回答生成に Web データを継続投入したい AI エンジニア
取得方法が用途ごとにばらばらで、再現性や監査性を持たせにくいチーム
Python と Node.js の両方で Bright Data を使うが、認証や zone 設計を統一したい開発組織

AI システムでは、取得できたかどうか以上に、後から「どの API のどの実行結果を使ったか」を追えることが重要です。

推奨製品セット

製品	役割	このページでの位置づけ
Web Unlocker	保護ページの単発取得	HTML / raw body の入口
SERP API	検索結果の構造化取得	検索起点の調査フローを担当
Crawl API	ドメイン単位の広域収集	Markdown / HTML / JSON のジョブ収集
Python SDK	Python 側の統合入口	共通の認証・設定をコードに閉じ込める
JavaScript SDK	Node.js 側の統合入口	同じ設計を JS ワークフローに展開する

まず API ごとの責務を分け、その後に SDK で共通化します。
どの言語でも、少なくとも api_key、zone、対象 API 種別、保存先を一貫して扱えるようにします。

最小実装イメージ

Python で API 選択を 1 か所にまとめる

import os
import requests
 
API_KEY = os.getenv("BRIGHTDATA_API_KEY")
ENDPOINT = "https://api.brightdata.com/request"
 
def call_brightdata(mode: str, payload: dict) -> dict:
    if mode not in {"unlocker", "serp"}:
        raise ValueError(f"unsupported mode: {mode}")
 
    response = requests.post(
        ENDPOINT,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=60,
    )
    response.raise_for_status()
    return response.json()
 
serp_result = call_brightdata(
    "serp",
    {
        "zone": "serp_api1",
        "payload": {
            "engine": "google",
            "q": "bright data api",
            "language": "ja",
            "location": "Tokyo",
            "num": 10,
        },
    },
)
 
unlocker_result = call_brightdata(
    "unlocker",
    {
        "zone": "web_unlocker1",
        "url": "https://example.com/protected-page",
        "format": "raw",
    },
)
 
print(serp_result.keys())
print(type(unlocker_result))

この共通関数を先に決めておくと、後から公式 SDK に置き換える場合も、呼び出し側の責務を崩さずに済みます。

Node.js 側でも認証と zone を共通化する

const apiKey = process.env.BRIGHTDATA_API_KEY;
 
async function requestBrightData(payload) {
  const res = await fetch("https://api.brightdata.com/request", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });
 
  if (!res.ok) {
    throw new Error(`Bright Data request failed: ${res.status}`);
  }
 
  return res.json();
}
 
const data = await requestBrightData({
  zone: "serp_api1",
  payload: {
    engine: "google",
    q: "bright data api",
    language: "ja",
    location: "Tokyo",
    num: 10,
  },
});
 
console.log(Object.keys(data));

SDK を導入するとしても、まずはこのレベルで「どの payload を投げるか」を固定しておくほうが運用しやすくなります。

運用ポイント

API ごとに zone を分けます。serp_api1、web_unlocker1、crawl_docs のように責務で区切ると、AI パイプライン側の追跡がしやすくなります。
Python と Node.js で別々の書き方をしても、環境変数名はそろえます。少なくとも BRIGHTDATA_API_KEY と zone 名の扱いは共通にします。
取得結果をそのまま LLM に渡さず、取得日時、対象 URL、API 種別、zone を必ず付けて保存します。
検索結果、HTML、Markdown を同じ保存先に雑に混ぜると再利用しづらくなります。用途別にテーブルやファイルを分けます。
SDK を採用するときも、一次情報で確認できない自動再試行や課金挙動を前提にせず、まずは明示的なログを残す設計を優先します。