運用

Lv5 は、本番運用の段階です。ここでは新しい API を覚えるより、安全に回し続ける仕組みを作ることが中心になります。権限分離、期限ローテーション、監査、SLA、コスト管理、Grounding を含む評価設計をそろえ、障害時に止まる理由と戻し方を説明できる状態を目指します。

前提

• ロードマップ Lv4
• 認証ガイド
• 基礎 / 運用
• 用語集

達成基準

• ADMIN / FINANCE / OPS / USER の役割分担を運用に落とし込める
• API キーの有効期限とローテーション手順を持っている
• zone 単位でコストと失敗率を追える
• 監査対象の操作とログ保存方針を決めている
• SLA の観点で成功率、遅延、配信遅延を見られる
• 取得品質と回答品質の両方にアラートを置ける
• 失効、403、parsing drift などの障害時 Runbook を持っている

代表ユースケース

• UC-AI-004 Answer Engine
• UC-AI-005 LLM Grounding
• UC-DEV-003 MCP Server で AI クライアント接続
• UC-WEB-005 AI システムへの Web データ統合

推奨ハンズオン

• Step 1 認証完全ガイド
• Step 6 MCP + AI エージェント連携

Lv5 では新しいハンズオンを増やすより、既存手順を本番基準で読み直すのが重要です。特に認証と AI 連携のページは、権限と評価の観点で再確認します。

権限分離

Bright Data の権限モデルは、Lv5 で本領を発揮します。すべてを 1 本のキーで回す設計は避けます。

実務ルール

• ADMIN キーは金庫管理し、平常運用で使わない
• アプリ用キーは環境ごとに分ける
• 検証環境と本番環境でキーを共有しない

期限ローテーション

API キーは期限付きで発行し、定期的に入れ替えます。Unlimited で運用を始めると、担当者異動や漏えい時の被害が大きくなります。

最小 Runbook

1. 新しいキーを発行する
2. シークレットマネージャを更新する
3. 検証ジョブを流す
4. 本番ワーカーを順次切り替える
5. 旧キーを失効させる

Refresh は旧キーを即時無効化するため、段階切替が必要な運用では新規キー発行ベースで進めたほうが安全です。

実装パターン 1: 期限付きキーを前提に読む

本番コードでは、キーの読み込みを 1 か所に寄せます。

export function getBrightDataApiKey() {
  const apiKey = process.env.BRIGHTDATA_API_KEY;
  if (!apiKey) {
    throw new Error("BRIGHTDATA_API_KEY is not set");
  }
  return apiKey;
}

単純ですが、Lv5 ではこうした接続点の一元化が効きます。差し替えや監査の対象が見えやすくなるためです。

実装パターン 2: 失敗率の簡易集計

運用では、件数だけでなく失敗率を見る必要があります。

stats = {"ok": 0, "timeout": 0, "forbidden": 0}
 
for result in results:
    stats[result["status"]] += 1
 
total = sum(stats.values())
for key, value in stats.items():
    print(key, round(value / total, 3))

Lv5 では、こうした簡易集計を監視基盤へ置き換えていきます。最初から大きなダッシュボードを作る必要はありませんが、比率で見る癖は必要です。

監査の観点

すべてのログを残すのではなく、何を監査対象にするかを決めます。

監査対象の例

• API キーの作成、更新、失効
• zone の追加、設定変更
• Webhook 受信失敗
• MCP 経由の高頻度呼び出し
• コスト急増の原因になったジョブ

監査で見たいこと

• 誰が変えたか
• いつ変えたか
• 変更後に何が起きたか

SLA の考え方

Lv5 では、成功率だけではなく遅延も含めて見ます。

Grounding と評価

AI 系の運用では、回答がそれらしく見えるだけでは足りません。Lv5 では、Grounding を含む評価設計が必要です。

最低限の評価項目

• 回答に元 URL が付いているか
• 回答本文と引用内容が矛盾していないか
• 鮮度が要求される問い合わせで古い結果を返していないか
• 取得失敗時に推測で埋めていないか

障害時 Runbook

API キー失効

• 新キー発行
• シークレット更新
• 影響ジョブの再実行
• 原因を監査ログへ残す

403 増加

• zone と認証の誤り確認
• ターゲット変化の有無確認
• Unlocker や Browser API への切替判断

parsing drift

• 欠損率アラート確認
• サンプル比較
• 自前パーサ修正または Scraper への切替検討

Lv5 の到達イメージ

Lv5 を終えた状態では、Bright Data は単なる API 群ではなく、運用可能なデータ取得基盤になります。重要なのは、失敗しないことではなく、失敗したときに原因を説明し、再発防止までつなげられることです。

次に学ぶこと

Lv5 は終点というより運用の入り口です。ここから先は、自社のドメインに合わせて KPI と Runbook を深めます。必要に応じて、各ユースケースページへ戻って対象別の監視と評価を具体化してください。

• UC-AI-004 Answer Engine
• UC-AI-005 LLM Grounding
• UC-WEB-001 保護サイトの安定収集基盤