Lv1

入門

認証、最初の API コール、レスポンス形式を理解する。

目安 2–4 時間／前提: HTTP / JSON の基本理解

Lv1 は、Bright Data を「まず 1 回通す」段階です。ここで身につけるのは、高度な抽出や大規模運用ではありません。認証方式を選び、最初の API コールを実行し、返ってきたレスポンスの形を読めるようになることです。この土台がないまま製品を広げると、後で zone と API キー、同期と非同期、HTML と JSON の違いで詰まります。

前提

先に次のページを読んでおくと、Lv1 の学習効率が上がります。

達成基準

API Access と Native Access の違いを説明できる
Authorization: Bearer <API_KEY> の付け方を理解している
zone が何を指すか説明できる
/request エンドポイントで最初の 1 回を通せる
HTML と JSON のどちらが返ってきているか判別できる
失敗時に、認証ミスと対象サイト要因を切り分けられる
USER と ADMIN の違いを理解し、最小権限でキーを発行できる

このレベルで扱う範囲

Lv1 では、製品全体を横断するより、共通の入り口を固めます。

項目	Lv1 でやること	Lv1 ではまだやらないこと
認証	API Key と Native Access の理解	キー更新 Runbook の自動化
API 呼び出し	1 URL の最小リクエスト	大量 URL の非同期ジョブ
レスポンス理解	HTML / JSON / raw を見分ける	高度なパーシング
運用	zone 名と権限の意味を理解する	SLA や監査対応

代表ユースケース

Lv1 で読むユースケースは、まず「何を実現するか」より「どう始めるか」に寄せます。

推奨ハンズオン

Step 1 認証完全ガイド

Step 1 では、curl、Python、Node.js のどれか 1 つでよいので、手元から最初のコールを通してください。3 つ全部やる必要はありませんが、最低 1 つは自分の実行環境で通すことが重要です。

実装パターン 1: API Access で最初の 1 回

Lv1 では API Access を先に触るのが自然です。新規実装では、Bearer トークンを付けるだけで始められるためです。

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"
  }'

この時点で確認するポイントは 3 つです。

HTTP ステータスが返っているか
zone の指定が合っているか
response.text が HTML か JSON か

返り値の見方

<html で始まるなら、HTML または raw body を見ています
{ や [ で始まるなら、JSON の可能性が高いです
401 / 403 の場合は、まず API キーと zone の指定を見直します

実装パターン 2: Native Access で接続確認

既存ツールを使う前提なら、Native Access の最小確認も Lv1 で押さえておく価値があります。

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

Lv1 では、このコマンドが「何を検証しているか」を理解できれば十分です。

brd.superproxy.io:33335 は接続先
ACCOUNT_ID、PRODUCT_NAME、PROXY_PASSWORD は Native Access の認証情報
-k は検証簡略化のためで、本番では証明書の扱いを整理します

Lv1 で確認しておくレスポンスの型

最初の段階で、レスポンス本文を雑にでも分類できるようにしておくと、その後の API 学習が楽になります。

見え方	典型例	次に考えること
HTML	`<html>` から始まる本文	自前パーサで読むか、別 API を選ぶか
JSON	`{}` または `[]`	そのまま保存するか、必要項目だけ抜くか
テキスト	`welcome` のような短い確認文	認証確認が主目的かを見直す
エラー本文	401、403、timeout	認証、zone、対象サイトのどこで失敗したか切り分ける

Lv1 の時点では、完全なパースは不要です。重要なのは、「返ってきたものを見て、次の手を決められること」です。

学習メモの残し方

Lv1 では、コードよりメモが効きます。次の 4 点だけは残しておくと、Lv2 以降で役立ちます。

使った zone 名
使った認証方式
返り値が HTML か JSON か
失敗したときに何を直したか

チーム学習でも個人学習でも、このメモがあると「前に何が通ったか」を再現しやすくなります。

公式一次情報の読み方

Lv1 では、Docs 全体を読む必要はありません。次の 2 本だけ先に押さえれば十分です。

認証と製品分類を先に理解しておくと、以降のページで迷いにくくなります。

Lv1 でよく詰まる点

`zone` と API キーを混同する

API キーは「誰が呼ぶか」、zone は「どの用途の設定で呼ぶか」です。両者は別物です。API キーが合っていても、zone 名が誤っていれば期待どおり動きません。

HTML を JSON だと思い込む

最初のレスポンスは、必ず本文を目視してください。JSON 前提で response.json() を呼ぶと、単純な HTML でも失敗します。

`ADMIN` キーをそのまま使う

Lv1 でも避けるべきです。学習用でも、できるだけ USER 権限で進めてください。後でそのまま本番コードに残りにくくなります。

Lv1 を終える判断

次の状態になったら、Lv2 に進んでよいです。

自分のマシンか開発環境から 1 回以上リクエストを通した
認証エラー時の見直し箇所がわかる
HTML と JSON の見分けがつく
「次は SERP、Browser、Crawl のどれに進むか」を目的ベースで選べる

次に学ぶこと

Lv2 では、共通の入り口から一歩進み、用途別の代表 API を触ります。検索なら SERP API、JS-heavy サイトなら Browser API、ドメイン全体なら Crawl API という切り分けを、自分で判断できるようにします。

前提