データの受け渡し（ZIP）

「データの受け渡し」では、サイトのコンテンツ・コレクションを .magichtml.zip 形式の管理用ZIPに書き出したり、ZIPを取り込んで新しいリソースとして追加したりできます。サイトの複製や、MagicHTML 形式に対応した別のアプリケーションとのデータの移し替えに使います。取り込みは同期ではなくコピーで、取り込んだデータはそれぞれのシステムで独立して管理されます。

サイト画面の「データの受け渡し」から開きます。

書き出す

「管理用ZIPをダウンロード」を押すと、site.magichtml.zip がダウンロードされます。

• 書き出されるのは保存済みの下書きです。公開中の版ではありません。
• 値の中で /assets/<素材ID> や https://cms.magichtml.dev/assets/<素材ID> の形で参照されている素材が、ZIPに同梱されます。
• ほかのサイトの素材や、存在しない素材を参照している場合は書き出せません。
• 非公開項目の値も含まれるため、ZIPは管理用ファイルとして扱い、公開サイトのフォルダには置かないでください。

取り込む

取り込みは「内容の確認」と「取り込みの実行」の2段階です。

1. 「MagicHTML ZIP」でZIPファイルを選び、「内容を確認」を押します。
2. ZIPの検証が行われ、問題がなければ取り込む内容が表示されます。
   • パッケージ名、素材の件数
   • 各リソースの種類・名前・識別キー・項目数・レコード数
3. 内容を確認し、「内容を確認し、新規コピーとして取り込みます」にチェックして「下書きとして取り込む」を押します。

確認結果は 30分間 有効で、1回だけ使えます。確認した本人・確認したサイトでのみ使えます。期限が切れた場合は、ZIPを選び直してください。

取り込み後の状態

内容・項目・素材を確認したうえで、必要な素材を「公開」にし、各リソースを公開してください。接続元の登録も必要に応じて行ってください。

識別キーの重複

ZIP内のリソースと同じ識別キーのリソースが取り込み先のサイトにあると、取り込みは中止されます（一部だけ取り込まれることはありません）。上書きや統合はできないため、新しいサイトや空のサイトに取り込むか、既存のリソースを整理してから取り込んでください。

フォームは取り込まれません

フォームは別製品の Magic Form Cloud で管理します。ZIPにフォームが含まれていても、エラーにはならずにスキップされます。確認画面では「フォームは Magic Form Cloud で管理します（取り込みません）」と表示され、フォームの識別キーは重複チェックの対象にもなりません。書き出しにもフォームは含まれません。

制限

ZIPファイルは50 MBまでアップロードできます。それを超える場合は 413 で拒否されます。

同梱できる素材の形式は PNG・JPEG・WebP・GIF・PDF・テキスト・MP4・WebM・MP3・WAV です。ファイルの中身と宣言された形式が一致しない素材は取り込めません。

次のようなZIPは、内容の確認の段階でエラーになります。

• 対応していない形式・バージョン（対応バージョンは 1 と 2）
• 想定外のファイル・パス、シンボリックリンク、暗号化されたファイル
• チェックサムやサイズが一致しないファイル、宣言のない素材
• 「素材URL」型の値が / で始まるローカルパスのまま（素材を同梱していない）
• 項目定義や値が コンテンツとコレクション のルールに合わない

外部の http://・https:// のURLはそのまま取り込まれます（ファイルはダウンロードされません）。

管理APIでの受け渡し

管理API のトークンで、同じ操作ができます。

# 書き出し
curl -o site.magichtml.zip \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://cms.magichtml.dev/api/v1/sites/SITE_ID/interchange/export'

# 内容の確認
curl -X POST \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -F 'package=@site.magichtml.zip' \
  'https://cms.magichtml.dev/api/v1/sites/SITE_ID/interchange/preview'

確認のレスポンス例：

{
  "data": {
    "token": "（48文字のトークン）",
    "name": "ブランドサイト",
    "resources": [
      {"key": "news", "kind": "collection", "name": "お知らせ", "fields": 2, "records": 12, "skipped": false},
      {"key": "contact", "kind": "form", "name": "お問い合わせ", "fields": 3, "records": 0, "skipped": true}
    ],
    "skipped": ["contact"],
    "assets": 4,
    "expires_in_minutes": 30
  }
}

skipped は取り込まれないリソース（フォーム）の識別キーです。

# 取り込みの実行
curl -X POST \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"token": "TOKEN", "confirm": true}' \
  'https://cms.magichtml.dev/api/v1/sites/SITE_ID/interchange/import'

成功すると 201 で、作成されたリソースのIDが返ります。

{"data": {"resource_ids": ["..."]}}

識別キーの重複、ZIPの検証エラー、確認トークンの期限切れ・使用済みなどは 422 で返ります。パッケージに関するエラーのメッセージは errors.package に入ります。