コンテンツにスキップ
D2B for Agents

クイックスタート

1. 認証 — PAT を発行する

Section titled “1. 認証 — PAT を発行する”

すべての /api/v1 呼び出しは PAT(Personal Access Token)の Bearer 認証です。コンソールから発行するか、ログイン済みセッション(JWT)で API から発行します。

Terminal window
curl -X POST https://d2b.dev/api/v1/me/tokens \
  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "scopes": ["workbooks:read", "workbooks:write"]}'
# → {"token": "d2b_pat_...", ...}  ※トークンはこの応答でのみ平文
  • スコープはリソース×アクションです: workbooks:read/write/delete、cloud-files:read(Drive / OneDrive の一覧・取り込み。ログインには既定で付き、PAT には明示して付けます)・governance:configure・workspaces:read/create/configure/delete・keys:read/mint/revoke・account:read・billing:manage。含意は同一リソース内のみ(write ⊃ read 等)。workbook 削除・snapshot restore・version revert は workbooks:delete
  • トークンは必ず 1 つのアカウントに固定されます(1 トークン = 1 アカウント)。ログイン済みセッションからの発行は既定アカウント宛てで、account_id に自分の開発者アカウントを指定するとそのアカウント宛てになります。GET /api/v1/me の account_id / account_name で確認できます
  • resource で到達範囲を絞れます: workbook:<id>(その workbook のみ — エージェントに渡すときの推奨)、workspace:<id>(そのワークスペースの workbook のみ。作成先もそこに固定)。既定の account はアカウント配下すべてです。到達範囲を決めるのは resource だけで、スコープは「何ができるか」を決めます — workspaces:read を持たないキーでも account ピンならアカウント内のどのワークスペースにも作成できます。届かないワークスペースを workspace_id に指定すると、一覧も作成も 403 です
  • 届くワークスペースは GET /api/v1/me/workspaces で名前付きで確認できます(is_default が workspace_id 省略時の作成先)。/me と workbook 一覧にも workspace_name が付きます
  • ワークスペースの provision は workspaces:create、キー発行は keys:mint、課金操作は billing:manage — 権限はリソース×アクションで独立しており、傘スコープはありません。必要な権限だけを組み合わせて発行してください(GitHub fine-grained PAT と同型)
  • workspace_id を省略した workbook 作成は、そのトークンのアカウントの最古のワークスペース(既定アカウントなら個人ワークスペース)に着地します。ワークスペースが 1 つもない開発者アカウントでは 409 になるので、先にコンソール(Workspaces)か workspaces:create キー(POST /api/control/workspaces)で作成してください

2. Python で 5 分

Section titled “2. Python で 5 分”
Terminal window
pip install d2b-sdk
from d2b import D2BClient


client = D2BClient(api_key="d2b_pat_...", base_url="https://d2b.dev")


# 1) ワークブック = 作業コンテナ
wb = client.workbooks.create(title="月次売上")["id"]


# 2) messy な Excel を投げる。wait=True で 202+job を SDK が面倒みる。
#    抽出と構造化が終わると、クリーンな型付きテーブルになっている
result = client.sources.upload(wb, "uriage_2026-06.xlsx", wait=True)


# 3) 何ができたか見る(エージェントの基本動作)
for t in client.tables.list(wb):
    print(t["name"], t["row_count"])
schema = client.tables.schema(wb, "売上明細")


# 4) SQL で分析(governance 適用済み・読み取り専用)
out = client.query.sql(wb, 'SELECT 商品, sum(金額) FROM "売上明細" GROUP BY 1')


# 5) 派生テーブルは transform で作る(lineage が残る)
client.transforms.create(
    wb, name="agg/monthly", kind="sql",
    template='CREATE OR REPLACE TABLE "{{ artifact_name }}" AS '
             'SELECT 商品, sum(金額) AS 売上 FROM "{{ src }}" GROUP BY 1',
    artifact_name="商品別売上", args={"src": "売上明細"},
)


# 6) 人間に返す
xlsx = client.export.tables(wb, tables=["商品別売上"])                  # 整形 xlsx
original = client.sources.render_template(wb, "uriage_2026-06.xlsx")  # 元の書式のまま値だけ更新


# 7) 版を切る
client.versions.commit(wb, "2026-06")

3. curl で同じこと

Section titled “3. curl で同じこと”
Terminal window
BASE=https://d2b.dev; H="Authorization: Bearer $D2B_PAT"
WB=$(curl -s -X POST $BASE/api/v1/workbooks -H "$H" -H "Content-Type: application/json" \
       -d '{"title": "monthly"}' | jq -r .id)
curl -s -X POST $BASE/api/v1/workbooks/$WB/sources -H "$H" -F file=@sales.xlsx -F mode=auto -F async=true
#   → {"job_id": ...}  →  GET $BASE/api/v1/jobs/{job_id} を poll
curl -s $BASE/api/v1/workbooks/$WB/tables -H "$H"
curl -s -X POST $BASE/api/v1/workbooks/$WB/query -H "$H" -H "Content-Type: application/json" \
     -d '{"sql": "SELECT count(*) FROM \"sales\""}'

4. CLI なら

Section titled “4. CLI なら”
Terminal window
pipx install d2b-sdk   # または uvx --from d2b-sdk d2b …
d2b login
d2b workbooks create --title monthly
d2b upload sales.xlsx --workbook WB --wait
d2b query 'SELECT count(*) FROM "sales"' --workbook WB

次: 中核概念、MCP で接続する、ワークブックを git で管理する。

messy な Excel — auto と staged の使い分け

Section titled “messy な Excel — auto と staged の使い分け”

まず既定の mode=auto で投げます(D2B がシートを表ごとに切り出し、結合ヘッダ・単位行・小計行・階層を読んで表を整えます)。抽出や構造化が期待と違ったときだけ staged に落とします:

  1. mode=staged で同じファイルを入れ直す(バイト保存のみ・解釈ゼロ)
  2. POST .../sources/{name}/analyze → 返ってくる parse spec(ヘッダ行・データ範囲・型)を確認して直す
  3. POST .../sources/{name}/materialize で確定

判断フローは「auto → 結果を目視 → 外れていたら staged で parse spec を握って再現」。auto の結果は別名で残るので、比較しながら直せます。

アップロード応答の structuring フィールドが結果を明示します: structured(構造化済み)/ skipped(structuring=skip を指定。元の表のみ)/ deferred(structuring=defer を指定。あとで差し替え)/ raw_fallback(構造化を頼んだが元の表のまま。理由は structuring_reason に出ます — no_credits はクレジット不足、building は構築中で再アップロードで再試行、failed:… は失敗。staged に切り替えることもできます)/ off(サーバ側で構造化が無効)。CLI は raw_fallback のとき stderr に警告を出します。

API / CLI / SDK / MCP からのアップロードも、既定で D2B が構造化します(structuring=auto)。シートは表と、そのまわりの表題・注記(<シート>_補足情報)に切り分けられ、切り出した表はシート上の並びのまま残ります。そこから、期間が列に並ぶ表は縦持ちに整えられ、小計・合計を含む報告書の表は階層ごとの表(<表>_階層1、<表>_階層2 …。同じ階層の行から計算される合計・差引は <表>_階層1_計算項目 など)と科目の木(<表>_科目)に分けられます。表が 1 つだけでまわりに何もないシートは切り分けず、整形済みの表がファイル名を引き継ぎます。元のシートは系譜に残ります。構造化はワークブックのクレジットを消費します(同じ内容のファイルを再度アップロードしたときはキャッシュから返り、構造化の料金はかかりません)。元の表のまま自分の LLM と add_transform で整形したいときは --no-structuring(API: structuring=skip)を指定すると、シートをそのままの形で ~1 秒・無料で着地させます。--defer-structuring(structuring=defer)は元の表を即返しし、構造化を裏で実行して完成後にテーブルを差し替えます(artifact.updated イベントが発火)。