microCMSから移行する

既存サイトの表示を確認しながら、スキーマ、コンテンツ、アプリの接続先の順に移します。現在のインポートは、microCMSのサービス全体を自動複製する機能ではありません。

1. スキーマを移す

microCMSでエクスポートしたスキーマJSONを用意し、genko.meのAPI作成画面（/w/your-workspace/new-api）、または対象APIの「スキーマ」（/w/your-workspace/apis/blog/schema）の「インポート」から読み込みます。取り込み結果のフィールドID、必須設定、複数選択を確認して保存してください。

自動変換するmicroCMSの種類は、text、textArea、richEditor、media、number、boolean、date、selectです。カスタムフィールドや、それ以外の種類はエラーになります。参照フィールドなどは移行先で設計し直してください。選択肢・複数選択と文字列／数値／真偽値の初期値は引き継ぎますが、対応外の設定は警告を確認し、必要な制約を設定し直します。

可能ならエンドポイント名とフィールドIDを移行元と揃えると、アプリの変更箇所を減らせます。blog と blogs は別のエンドポイントです。表示名から推測せず、管理画面に表示された実際の値を使います。

2. コンテンツを移す

対象APIのコンテンツ一覧（/w/your-workspace/apis/blog）で「コンテンツのインポートとエクスポート」の矢印アイコンから「インポート」を選びます。CSVは「入力用CSVをダウンロード」で取得した列名を使用してください。JSONは配列、またはentries／contents配列を持つ形式を受け付けます。ファイルは10MB以内、1回1,000件までです。詳しくはインポートとエクスポートを参照してください。

「取り込み後の状態」は既定で「下書き」です。公開する場合は「公開中」に変更します。元データの公開状態や予約日時をそのまま復元する手順ではありません。

リスト形式のコンテンツIDは新規発行されます。記事URLにIDを使っているサイトでは、旧IDと新IDの対応表を残し、旧URLから新URLへのリダイレクトを設定してください。参照フィールドも移行先のIDへ合わせます。オブジェクト形式は1件だけ取り込み、既存コンテンツがある場合はそのIDを維持して内容を置き換えます。

画像・ファイルの実体の移行は別途必要です。移行元のファイルをダウンロードし、genko.meへアップロードしてコンテンツに設定します。画像の代替テキストも照合してください。取り込んだURLだけを見て、画像の移行が完了したと判断しないでください。

3. アプリから接続する

Next.js App Routerでは、クイックスタートのCLIでスキーマとクライアントを生成します。すでにgenko.meへ接続済みなら、pullで同期してください。

一覧はList、記事詳細はViewに置き換えられます。既存のHTMLとCSSに合わせて部品の表示を調整します。カルーセルなどの独自UIにはclient.works.list()のようにSDKで取得したデータを渡す方法もあります。詳しくはList・Viewとコンテンツ取得を参照してください。

既存のクライアントを使っている箇所を切り替え、次の点を確認します。

移行中に旧画像URLを参照するコンテンツがある場合は、旧画像ドメインの許可も残します。

4. Webhookと本番環境を切り替える

microCMS用の署名検証処理はそのまま使えません。genko.meのX-Genko-Signatureとイベント形式に合わせて変更します。Webhookの署名検証と更新通知を参照してください。

ホスティング先にもGENKO_API_KEYと、Webhookを利用する場合はそのシークレットを設定します。ローカルの環境変数は自動では転送されません。Dockerのビルド時に記事を静的生成する構成では、ビルド時にもAPIキーを利用できる設定が必要です。キーをDockerfileやGitに直接記載しないでください。

5. 切り替えを確認する

公開件数、本文、選択肢、リンク、画像を移行元と照合し、本番で一覧と記事詳細を開きます。公開・更新・非公開化がサイトに反映されるかも確認してください。旧サービスの停止は、旧URLへのアクセスや画像参照が残っていないことを確認した後に行います。