コンテンツのインポート

インポート元

インポート元の一覧には、WordPressのインポート元が3つあります。

wordpress-com のOAuthによるインポート元はありません。WordPress.comのサイトでは、WXRのエクスポートか、互換性のあるEmDash Exporterの接続を使う必要があります。

WXRファイルのインポート

必要なコンテンツをWordPressでエクスポートでき、EmDash Exporterをインストールできない場合は、WXRを使います。

XMLには、添付ファイルのメタデータと元のURLが含まれ、メディアのデータそのものは含まれません。任意のメディアのコピーが終わるまで、WordPressにはアクセスできる状態にしておきます。

EmDash Exporterの接続

WordPressのサイトを管理していて、下書き、コメント、メニュー、対応している設定など、認証が必要なデータが必要な場合は、エクスポーターを使います。「ツール」→「EmDash Migration」で移行用のキーを生成するか、WordPressのユーザー名とアプリケーションパスワードで接続します。エクスポーターは emdash/v1 のAPIエンドポイントを通してデータを送信します。EmDashにデータベースへの直接のアクセスを与えるものではありません。

管理画面のインポートの流れ

管理画面は、次の段階を実行します。

1. 接続。 WXRファイルをアップロードするか、EmDash Exporterの移行用のキーを貼り付けるか、サイトのURLを入力します。
2. 分析。 投稿タイプ、必須のフィールド、投稿者、添付ファイル、スキーマの互換性を読み取ります。
3. 確認。 投稿タイプ、コレクションの対応づけ、投稿者、対応している追加の項目を選択します。
4. 準備。 足りないコレクションとフィールドを作成します。型に互換性のない既存のフィールドがあると、その対応づけはできません。
5. インポート。 コンテンツを変換して作成します。エクスポーターでの移行では、コンテンツ、コメント、最終処理のリクエストを、一定の大きさに区切って送ります。
6. メディアのコピー。 選択したWXRの添付ファイルをEmDashのストレージにダウンロードし、該当するURLを書き換えます。

WXRでの移行では、エクスポートに含まれる投稿、固定ページ、カスタム投稿タイプ、タクソノミー、再利用ブロック、投稿者またはゲストのバイライン、メディアをインポートできます。エクスポーターでの移行では、さらに、稼働中のWordPressのAPIから、コメント、メニュー、選択したサイト設定、対応しているSEOの値を取得できます。

分析結果の読み方

検出された投稿タイプごとに、確認画面には、提案されるコレクションと、次の4つのスキーマの状態のどれかが表示されます。

準備の段階は、追加だけをします。インポートに合わせるために、既存のフィールドの型を変えることはありません。

公開状態の対応

コンテンツのルートは、WordPressのインポートから2つの公開状態を保存します。

インポーターは、WordPressのレビュー待ち、非公開、予約済み、ゴミ箱の意味を引き継ぎません。これらのエントリーは、EmDashで公開する前に確認します。

コンテンツと識別子

WXRとエクスポーターのインポート元は、GutenbergのマークアップをPortable Textに変換します。post を posts、page を pages に、既知のカスタム投稿タイプをコレクションのスラッグに対応づけます。WordPress内部の投稿タイプは除外されます。再利用ブロック（wp_block）は、通常のエントリーではなく、EmDashのセクションとして扱われます。

インポートしたエントリーについて：

• WordPressの投稿のスラッグがある場合は、それがEmDashのスラッグになります。
• EmDashは独自のデータベースIDを生成します。
• 投稿者の対応づけによって、EmDashのユーザーが結び付けられます。対応づけていないWordPressの投稿者は、再利用できるゲストのバイラインにできます。
• WordPressのIDは、メニュー、コメント、アイキャッチ画像、翻訳などの関連を解決するために、一時的に使われます。既存のWXRのエントリーを検出するための、永続的な識別子ではありません。

skipExisting を指定してWXRをもう一度実行すると、既存のエントリーはコレクション、スラッグ、ロケールで照合されます。そのため、スラッグが変わっていると、別のエントリーが作られることがあります。エクスポーターでの移行も、同じスラッグとロケールによる照合を使い、スキップしたエントリーから、WordPressのIDとの関連の対応表を作り直します。

メディアのコピーと重複の判定

メディアの段階では、それぞれの添付ファイルのURLをダウンロードし、ダウンロードしたデータのSHA-1ハッシュを計算して、そのコンテンツのハッシュを持つ既存のメディアの行を探します。データが同一であれば、WordPressのURLが異なっていても、既存のメディアのレコードを再利用します。

ハッシュは sha1: の接頭辞を付けて保存されます。これは重複の判定のためのキーで、セキュリティのための署名ではありません。ファイル名が同じというだけで、2つのURLが重複として扱われることはありません。

メディアをコピーしたあと、インポーターは、Portable Text、テキスト、文字列、画像、ファイルのフィールドにある該当するURLを書き換えます。ダウンロードと、書き換えたページの確認が終わるまで、WordPressのオリジンはオンラインのままにしておきます。

やり直したときの動作

管理画面は、WXRのインポートについて、永続的な再開用のトークンを保存しません。リクエストが失敗した場合は、次のようにします。

• 「skip existing」を有効にして、分析とインポートをもう一度実行します。
• 既存のエントリーは、コレクション、スラッグ、ロケールでスキップされます。
• メディアの段階をもう一度実行しても、すでに保存されたファイルは問題ありません。データが同一のダウンロードは、コンテンツのハッシュで再利用されるためです。
• やり直す前に、途中まで適用されたスキーマの変更と、スラッグが変わったエントリーを確認します。

エクスポーターでの処理は、Workerの制限に収まるように区切られています。ブラウザーが、リクエストの間でカーソルと、WordPressからEmDashへの関連の対応表を保持します。ブラウザーがその状態を失った場合は、インポートをやり直します。コンテンツのページが処理されるにつれて、スキップされたエントリーから関連の対応表が作り直されます。

別の emdash import wordpress CLIは、変換したJSONファイルを出力先のディレクトリに書き出します。その --resume オプションは .wp-migration-progress.json を読み取り、そこに記録済みのWordPressの投稿と添付ファイルのIDをスキップします。このファイル変換の手順は、管理画面のデータベースへのインポートとは別のもので、管理画面のリクエストを再開できるようにするものではありません。

管理画面のAPIの仕様

これらのエンドポイントは、認証済みの管理画面のページで使われています。import:execute を持つ管理者のセッションと、X-EmDash-Request: 1 ヘッダーが必要です。成功時のレスポンスは通常、{ "success": true, "data": ... } のエンベロープを使います。エラーは { "success": false, "error": { "code", "message" } } を使います。

URLの調査

POST /_emdash/api/import/probe は、JSON { "url": "https://example.com" } を受け付けます。

data の値は { success: true, result } です。result には、url、isWordPress、bestMatch、allMatches が含まれます。単なるWordPressのREST APIとして一致した場合は、WXRのアップロードを勧めます。RESTからの直接のインポートが使えるようになるわけではありません。

WXRファイルの分析

POST /_emdash/api/import/wordpress/analyze は、file パートを含む multipart/form-data を受け付けます。data の値には、サイト、投稿タイプの分析、添付ファイルの概要、投稿者の概要、タクソノミーの件数、カスタムフィールドの提案が含まれます。

スキーマの準備

POST /_emdash/api/import/wordpress/prepare は、次の形のJSONを受け付けます。

{
  "postTypes": [
    {
      "name": "post",
      "collection": "posts",
      "fields": [
        {
          "slug": "title",
          "label": "Title",
          "type": "string",
          "required": true,
          "searchable": true
        }
      ]
    }
  ]
}

data の値には、success、collectionsCreated、fieldsCreated、コレクションごとの errors が含まれます。

WXRのインポートの実行

POST /_emdash/api/import/wordpress/execute は、次のものを含む multipart/form-data を受け付けます。

• file：WXRファイル
• config：postTypeMappings、skipExisting、任意の authorMappings、任意の importSections、インポート全体に適用する任意の locale を含むJSON文字列

data の値には、success、imported、skipped、errors、byCollection と、任意でセクションとタクソノミーの概要が含まれます。

メディアのコピー

POST /_emdash/api/import/wordpress/media は、JSON { "attachments": [...], "stream": true } を受け付けます。既定はストリーミングです。ストリーミングのレスポンスは改行区切りのJSONで、progress のレコードのあとに result のレコードが1つ続きます。通常のAPIのエンベロープは使いません。stream を false にすると、{ imported, failed, urlMap } を通常のエンベロープで囲んだ形で受け取ります。

メディアのURLの書き換え

POST /_emdash/api/import/wordpress/rewrite-urls は、JSON { "urlMap": { "old": "new" }, "collections": ["posts"] } を受け付けます。任意のコレクションの一覧で、書き換えの範囲を限定します。data の値には、更新したエントリーの数と書き換えたURLの数、エラーが含まれます。

エクスポーターのAPIの使用

POST /_emdash/api/import/wordpress-plugin/analyze は、JSON { "url", "token" } を受け付けます。token は、WordPressのユーザーとアプリケーションパスワードのBase64のBasic認証の値です。data の値は { success: true, analysis } です。

POST /_emdash/api/import/wordpress-plugin/execute は、url、token、config を含むJSONを受け付けます。管理画面は、phase（content、comments、finalize）も渡します。それぞれのレスポンスには、done、任意の次の cursor、部分的な result、更新された idMap、translationGroups、commentRoots を含む chunk オブジェクトが含まれます。管理画面は chunk の値をまとめ、蓄積した対応表を次のリクエストで送ります。

トラブルシューティング

サイトは検出されるが、直接インポートできない

wordpress-rest の結果は、調査のためだけのものです。WXRファイルをアップロードするか、EmDash Exporterをインストールしてから、もう一度サイトを調査します。

投稿タイプが非互換になる

確認画面で投稿タイプを展開し、衝突しているフィールドを探します。インポート先のコレクションを変えるか、「コンテンツタイプ」でそのフィールドを調整します。インポーターは既存のフィールドの型を置き換えません。

一部のメディアが失敗した

最後のメディアの結果に、失敗した元のURLが一覧で表示されます。それぞれのURLが公開されていること、まだ存在すること、プライベートネットワークのアドレスにリダイレクトしないことを確かめます。アクセスの問題を直してから、メディアの段階をやり直します。完了済みの、データが同一のファイルは再利用されます。

次のステップ

• 運営者向けの手順は、WordPressからの移行を参照してください。
• コンテンツをインポートしたあとは、WordPressテーマの移植に進みます。
• サイトが独自の動作に依存している場合は、WordPressプラグインの移植を参照してください。