Migrate Source CSV
Drupal Migrate APIにCSVソースプラグインを提供し、CSVファイルからのマイグレーションを可能にします。
migrate_source_csv
インストール
composer require 'drupal/migrate_source_csv:8.x-3.7'
composer require 'drupal/migrate_source_csv:8.x-3.4'
概要
Migrate Source CSVは、DrupalのMigrate APIにソースプラグインを提供するコントリビュートモジュールで、CSVファイルをマイグレーションのデータソースとして使用できるようにします。このモジュールは、堅牢なCSVパース機能のためにLeague\CSV PHPライブラリを活用しています。
このモジュールは、カスタム区切り文字、囲み文字、エスケープシーケンスなど、さまざまなCSV形式をサポートする高度に設定可能なソースプラグインを提供します。ヘッダー行の有無にかかわらずファイルを処理し、単一キーと複合主キーの両方をサポートします。また、ソースファイル内の行位置を追跡するためのオプションのレコード番号付け機能も提供します。
このモジュールは、レガシーシステムやスプレッドシートアプリケーションからCSV形式でエクスポートされたデータをコンテンツマイグレーションするシナリオで不可欠です。Drupalのマイグレーションフレームワークとシームレスに統合され、DrushやMigrate Plusモジュールなどのツールと組み合わせて、強化されたマイグレーション管理に使用できます。
Features
- CSVファイルからデータを読み込むDrupal Migrate API用CSVソースプラグイン
- さまざまなCSV形式を処理するためのカスタム区切り文字、囲み文字、エスケープシーケンスのサポート
- ヘッダーなしファイルのサポートを含む設定可能なヘッダー行位置
- カラム名とラベルの手動指定を可能にするフィールド定義オーバーライド
- 複数のカラムをユニーク識別子として使用する複合主キーサポート
- ソースファイル内の行位置を追跡するためのオプションの自動レコード番号付け
- さまざまなファイルソースからの読み込みを可能にするファイルストリームサポート
- 堅牢で効率的なCSVパースのためのLeague\CSVライブラリとの統合
- migration_lookupシナリオ用の/dev/nullを使用した空ソースサポート
Use Cases
スプレッドシートエクスポートからのユーザーデータのマイグレーション
CSVとしてデータをエクスポートするレガシーシステムからユーザーをマイグレーションする場合、エクスポートされたユーザーファイルへのパスでcsvソースプラグインを設定します。ユニーク識別子カラム（メールアドレスやユーザーIDなど）をids設定として指定します。マイグレーションのprocessセクションでCSVカラムをDrupalユーザーフィールドにマッピングします。
外部システムからの製品カタログのインポート
eコマースサイトでは、在庫管理システムからエクスポートされた製品データをインポートするためにcsvソースを使用します。ソースがパイプ区切りやタブ区切り形式を使用している場合は、カスタム区切り文字を設定します。ドキュメント化のために人間が読みやすいラベルを提供するためにfields設定を使用します。
複合キーを使用したコンテンツマイグレーション
ソースデータが複合キーとして複数のカラムを使用する場合（例：言語コード＋コンテンツID）、ids配列に複数の値を設定します。プラグインは、各ソースレコードを一意に識別するために、指定されたすべてのカラムを一緒に使用します。
ヘッダーなしファイルの処理
ヘッダー行がないCSVファイルの場合、header_offsetをnullに設定し、fields設定を使用してカラム名を定義します。各フィールド定義には、プロセスマッピングでカラム識別子として使用される'name'プロパティが最低限必要です。
カスタム行処理のための拡張
前処理ロジックを追加するために、CSVクラスを拡張するカスタムソースプラグインを作成します。initializeIterator()メソッドをオーバーライドして、行の変換、フィルタリング、または追加の行を生成します。テストモジュールcsv_source_yield_testがこのパターンを実演しています。
レコード番号を識別子として使用
ソースCSVに自然なユニーク識別子がない場合、create_record_numberを有効にして連番の行番号を生成します。このフィールドをids設定の一部として設定し、行位置をマイグレーション識別子として使用します。
Tips
- 本番環境ではCSVファイルに絶対パスを使用するか、hook_migration_plugins_alter()を使用してモジュールの場所に基づいてパスを動的に構築してください。
- 大きなCSVファイルの場合、League\CSVライブラリはイテレータを通じて効率的にメモリを処理しますが、非常に大きなファイルはデバッグを容易にするために分割することを検討してください。
- 最初にdrush migrate:importの--limitオプションを使用して、データの小さなサブセットでマイグレーションをテストしてください。
- マイグレーショングループ、設定エンティティ、マイグレーションUIなどの追加機能のために、Migrate Plusモジュールを使用してください。
- デバッグ時、fields()メソッドの出力はソースプラグインがカラム名をどのように解釈しているかを示します。マッピングが正しくないように見える場合はこれを確認してください。
- /dev/nullパスは特別に処理され、空のソースを提供します。これは実際にデータをマイグレーションせずにソースが必要なmigration_lookup操作に便利です。
- Drupalのファイルシステム内に保存されているCSVファイルには、ファイルストリームラッパー（例：public://、private://）の使用を検討してください。
Technical Details
Hooks 1
hook_migration_plugins_alter
マイグレーションプラグインの定義を変更するために使用できます。例えば、CSVマイグレーションのソースパスを変更するなど。テストモジュールは、CSVソースファイルの絶対パスを設定するためにこのパターンを実演しています。
Troubleshooting 7
マイグレーションYAMLのソース設定に、CSVファイルへの絶対パスまたは有効なファイルストリームURIを指す'path'キーが含まれていることを確認してください。
各行を一意に識別するカラム名を含む'ids'配列をソース設定に追加してください。例: ids: [id] または ids: [language, content_id]
これらの設定オプションが正確に1文字であることを確認してください。基盤となるCSVライブラリは複数文字の区切り文字をサポートしていません。
ファイルパスが正しく、ファイルが存在することを確認してください。絶対パスまたはDrupalストリームラッパーを使用してください。ファイルのパーミッションを確認してください。
ファイルのパーミッションを確認し、WebサーバーユーザーがCSVファイルへの読み取りアクセス権を持っていることを確認してください。
ヘッダー行を使用している場合、header_offsetが正しく設定されていることを確認してください（最初の行の場合は0）。header_offsetが間違っていると、カラム名がヘッダーではなくデータ値になります。必要に応じてfields設定を使用してカラム名をオーバーライドしてください。
delimiter設定がファイル形式と一致していることを確認してください。よくある問題には、タブ区切りファイルにカンマ区切りを使用する、またはその逆があります。
Security Notes 3
- CSVソースファイルに機密データが含まれている場合、Web URLからアクセスできないようにしてください。ファイルはWebルートの外部に保存するか、private://ストリームラッパーを使用してください。
- マイグレーションのprocessフェーズでデータを検証およびサニタイズしてください。特にユーザーが提供したCSVファイルの場合は重要です。
- path設定にはファイルパスとストリームを受け入れるため注意してください。本番環境ではマイグレーション設定を作成または変更できるユーザーを制限してください。