CSVインポート仕様

概要

Tesseraへの移行はCSVインポートに一本化しています。ほぼどのCMSからでも作れる形式だからです。このページは、そのCSVをどう書けば通るかの仕様です。人が読むためのページですが、AIエージェントに渡しても同じ内容で解釈できるように書いています （同じ仕様はMCPツール get_csv_import_spec からも取得できます）。

手順全体（棚卸し → 書き出し → 取り込み → 公開）はブログ「CMS移行の手順ガイド」を参照してください。

CSVの書き方

• 1行目はヘッダー（列名）。既存のコンテンツの種類へ入れる場合は、列名をフィールドのシステム名（apiId）に一致させる。新しい種類をCSVから作る場合は列名は任意（表示名になる）
• 文字コードは UTF-8 推奨（Shift_JIS・EUC-JP も自動判定して読める）。改行やカンマを含むセルはダブルクォートで囲む
• 複数の値（配列・複数参照・複数メディア）は1つのセルにまとめ、「;」または「|」で区切る
• reference型（参照）は参照先エントリの代表表示名（ラベルフィールドの値。例: 著者名）で指定する。IDは不要。参照される側の種類を先に取り込む
• media型は画像・PDF・動画のURL（取り込み時にワークスペースのアセットへコピーされる。1ファイル20MBまで、SVG不可、同じURLは1回だけ取得）または既存アセットのIDで指定する
• date型は ISO 8601（YYYY-MM-DD または YYYY-MM-DDTHH:mm:ssZ）
• boolean型は true/false または 1/0
• number型は数値。先頭のゼロを保ちたい値（郵便番号等）は text 型にする
• richtext_markdown型は Markdown 本文
• array型は「;」または「|」区切り、object型は JSON 文字列
• select型は選択肢のいずれかの値と完全一致させる
• 取り込んだエントリは常に「下書き」。既存エントリは変更されず、常に新規として追加される（重複チェックなし）
• 行ごとに独立して処理され、必須の空欄・unique の重複・参照先が見つからない・メディアの取得失敗は行番号付きで報告される（他の行は続行）

型ごとの書き方

例

「記事」（title / slug / body / author / category / coverImage / publishedAt）へ2件を取り込むCSVです。著者とカテゴリは名前で、画像はURLのままです。

title,slug,body,author,category,coverImage,publishedAt
"はじめての移行",first-post,"## 見出し
本文です。",山田 花子,お知らせ;ブログ,https://old-cms.example.com/uploads/hero.jpg,2026-09-01
"2件目の記事",second-post,"本文2",山田 花子,ブログ,https://old-cms.example.com/uploads/second.png,2026-09-03

各コンテンツの種類の一覧画面にある「サンプルCSVをダウンロード」を使うと、その種類のヘッダー行と書き方の例がそのまま手に入ります。

2つの取り込み経路

既存の種類へ入れる

種類の一覧画面（/entries?contentType=...）→ ヘッダー右端の「…」→「CSVインポート」。 列名は種類のシステム名（apiId）に一致させます。承認フローは通らず、その場で下書きとして追加されます。

新しい種類をCSVから作る

「移行」画面（/migrations）にアップロードすると、列名と値から各列の型を推論して種類の雛形を作ります。 日付らしい列は日付、少数の値を繰り返す列は選択肢、画像・PDF・動画のURLだけの列はメディア、として提案されます。内容を確認して実行すると、種類の作成と取り込みが1回で終わります（「元に戻す」で取り消し可）。

AIエージェントに作らせる

Claude CodeやCursorにTesseraのMCPを接続していれば、CSVへの変換をそのまま頼めます。ポイントは「仕様を先に取得させる」ことです。

Tessera の MCP で get_csv_import_spec を contentTypeApiId="blogPost" で呼び、
その仕様（ヘッダー行・型ごとの書き方・区切り文字）に合わせて、
添付の JSON（旧CMSの書き出し）を UTF-8 の CSV に変換してください。
参照は名前のまま、画像は URL のままで構いません。

1. エージェントが get_csv_import_spec でヘッダー行と型ごとの書き方を取得します。
2. 旧CMSの書き出し（JSON・XML・CSV）を、その仕様に合わせて変換します。
3. できたCSVを一覧画面から取り込みます。エージェントに直接 create_entry で入れさせることもできますが、件数が多い場合はCSV経由の方が行単位のエラー報告と確認の区切りがあるぶん安全です。

MCPを接続していないAI（Web閲覧ができるチャット）には、このページのURL（https://tesseracms.com/docs/csv-import）を渡して「この仕様に合わせて」と頼んでください。サイトの /llms.txt にもエージェント向けの目次があります。

エラーの扱い

• 行ごとに独立して処理されます。1行の失敗で他の行は止まりません。
• 失敗した行は「行番号（ヘッダー行を1行目とする）＋理由」で表示されます。CSV側を直して、その行だけを再度取り込んでください。
• 主な理由: 必須項目の空欄、一意項目の重複、参照先が見つからない（名前の不一致）、選択肢に無い値、日付や数値として解釈できない、メディアURLの取得失敗（404・20MB超・SVG・内部アドレス）。
• ヘッダーに種類に存在しない列名があると、ファイル全体が拒否されます。

関連ドキュメント

• 移行ガイド（機能の概要）
• MCPサーバー（get_csv_import_spec / import_asset_from_url）
• メディアAPI