Contentfulで記事やアセットを一括エクスポート/インポートする方法

2021.11.24

ベルリンオフィスの小西です。

ヘッドレスCMSのContentfulで、投稿された記事や画像などのアセットを別のスペースに移行したり、一括でエクスポートしたいケースがあります。

Contentfulからインポート/エクスポートツールが公開されているので、CLIを使ってスペース内のリソースを丸ごと移行してみます。

CLIのインストール

npm

npm install -g contentful-cli

yarn

yarn global add contentful-cl

Management APIキーの取得

ダッシュボードから、Management APIキー(CMA)を取得します。

Management APIキーの一覧ページでは、所属するOrganizationに紐づく全てのAPIキーが表示されるのルので、わかりやすい名前をつけておいたほうが管理が楽になります。

「Generate」をクリックすると、生成されたキーが表示されます。

ウインドウを閉じるとキーは再表示できませんので、大切にメモっておきます。

注意

ContentfulのAPIキーには他に、Delivery API、Preview APIキーがありますが、Management APIの権限が最も強く、記事やアセット、アカウント設定の書き換えや削除が行えてしまいますので、キーの漏洩には気をつけてください。

エクスポート手順

既存のContentful スペースから記事とアセットを一括エクスポートしてみます。

エクスポート用の設定ファイルの作成

まずは、どのような設定でエクスポートを行うか指定する、jsonファイルを作ります。

例えば`config-export-sample.json`というタイトルで下記のような記述したファイルを作ります。

{
  "spaceId": "contentful_space_id_here",
  "environmentId": "master",
  "managementToken": "contentful_management_api_key_here",
  "saveFile": true,
  "contentFile": "export-sample.json",
  "includeDrafts": true,
  "includeArchived": true,
  "skipContentModel": false,
  "skipContent": false,
  "skipRoles": true,
  "skipWebhooks": true,
  "contentOnly": false,
  "downloadAssets": false,
  "host": "api.contentful.com",
  "rawProxy": false,
  "maxAllowedLimit": 1000,
  "errorLogFile": "/error.log",
  "useVerboseRenderer": false
}

contentFile として指定したのが、エクスポートされるファイル名です。

詳細な設定可能項目は下記に記載されています。

https://github.com/contentful/contentful-export/blob/master/example-config.json

エクスポートコマンド

上記のファイルの作成が完了したら、エクスポートしてみます。

下記のコマンドを、設定ファイルと同じディレクトリで実行してみてください。

contentful space export --config config-export-sample.json

エクスポート処理が無事完了したら export-sample.json というファイルが同じディレクトリにできているはずです。

インポート手順

今度は、先ほど取り出したデータを取り込んでみます。

インポート前の大事な注意点:

インポートの際の注意点があり、取り込み先のスペースで、取り込み元データと同じLocaleを手動で設定してあげなければいけません。

Contentfulのアカウント作成時、デフォルトではLocaleが en-US(アメリカ英語)になっています。

人によっては、ここを ja に変更したり、もしくは複数のlocaleを設定していたりするかと思います。

インポート先のスペースでも、全く同様のlocaleにあらかじめ設定しておく必要があります。

もしインポートデータとインポート先スペースのlocaleが一致しない場合、インポートはうまくいきません。

インポート用の設定ファイルの作成

エクスポートと同じく、config用のjsonファイルを用意します。

今度の記述はもう少しシンプルです。先ほど作成されたエクスポートファイルを取り込み元データとして指定します。

{
  "spaceId": "contentful_space_id_here",
  "managementToken": "contentful_management_api_key_here",
  "contentFile": "export-sample.json"
}

インポート用の詳細な設定可能項目は下記から確認できます。

https://github.com/contentful/contentful-import/blob/master/example-config.json

インポートコマンド

下記を設定ファイルと同じディレクトリで実行します。

contentful space import --config config-import-sample.json

画像や記事のレコード数によりますが、数分〜数十分(多すぎると1時間超えるかも)で完了するかと思います。

ちなみに、インポートもエクスポートも、設定ファイルを用意する代わりに、CLIでコマンド実行する際にオプションとしても指定できます。

例:

contentful space export --space-id contentful_space_id_here ...(略

指定できるオプションは下記で確認できます。

https://github.com/contentful/contentful-cli/tree/master/docs/space/export

エクスポート/インポートできない設定

下記の設定項目はCLIでの移行に対応していないので、ダッシュボードから手動で設定してあげてください。

  • Locale
  • App, Custom App
    • UI Extensionも同様ですが、Contentfulに追加した外部アプリは現時点で移行できないとのことです。
  • Roles, Custom Roles
    • Rolesのエクスポートは可能ですが、インポートはできません。

参考URL

https://github.com/contentful/contentful-cli/tree/master/docs/space/export

https://github.com/contentful/contentful-cli/tree/master/docs/space/import

https://github.com/contentful/contentful-export/blob/master/example-config.json

https://github.com/contentful/contentful-import/blob/master/example-config.json