インストール
composer require 'drupal/migrate_tools:^6.1'
概要
Migrate Toolsは、Drupal CoreのMigrate APIに不可欠なコンパニオンモジュールです。マイグレーションプロセスを管理するためのWebベースの管理インターフェースと強力なDrushコマンドの両方を提供します。
このモジュールにより、サイト管理者はマイグレーションのステータス確認、インポートとロールバックの実行、進捗の監視、マイグレーションメッセージの検査を、直感的なUIまたはコマンドラインから行うことができます。Migrate Plusモジュールとシームレスに連携し、マイグレーショングループによるEntityベースのマイグレーション管理を提供します。
主な機能には、大規模マイグレーション向けのバッチ処理サポート、ソースとデスティネーションを同期させる同期機能、DRYなマイグレーション定義のための共有設定、進捗インジケーター付きの包括的なログ機能が含まれます。
Features
- マイグレーショングループと個別のマイグレーションを、ステータス、カウント、最終インポートタイムスタンプとともに表示・管理するためのWeb UI
- インポート、ロールバック、停止、リセット、無効化、ステータス確認を含むすべてのマイグレーション操作のためのDrushコマンド
- タイムアウトの問題なくWeb UIから大規模マイグレーションを実行するためのバッチ処理サポート
- ソースデータに存在しなくなったデスティネーションレコードを自動的に削除する同期機能
- Drushコマンド実行中のリアルタイムステータス更新付きプログレスバー表示
- マイグレーション実行時のエラー、警告、通知を表示するマイグレーションメッセージビューア
- マイグレーションのデバッグのためのソース、プロセス、デスティネーションパイプライン検査ページ
- 複数のマイグレーション間で共通のマイグレーション設定を再利用できる共有設定システム
- マイグレーションの関係性と実行順序を表示する依存関係ツリーの可視化
- 特定のソースレコードをインポートまたはロールバックするためのIDリストフィルタリング
Use Cases
Drupal 7からDrupal 10へのコンテンツマイグレーション
Migrate ToolsをMigrate Upgradeと併用してマイグレーション設定を生成し、Drushコマンドを使用してコンテンツをインポートします。'drush migrate:status'で利用可能なマイグレーションを確認し、'drush migrate:import --all'で実行します。増分更新には'--update'フラグを使用します。
CSVファイルからのデータインポート
Migrate Source CSVモジュールと組み合わせて、CSVファイルを指すマイグレーション設定を作成します。UIの実行フォームを使用して、大きなファイルのバッチ処理でインポートを実行します。進捗を監視し、問題がないかメッセージを確認します。
環境間でのコンテンツ同期
migrate:importで'--sync'オプションを使用して、デスティネーションをソースと同期させます。これにより、ソースに存在しなくなったデスティネーションアイテムが削除され、ステージングサイトを本番データと同期させるのに便利です。
マイグレーション問題のデバッグ
管理UIを使用してソースフィールド、プロセスパイプライン、デスティネーション設定を検査します。メッセージタブでエラーと警告を確認します。'drush migrate:messages'を'--format=csv'とともに使用して、分析のために問題をエクスポートします。
開発中の部分的なマイグレーション実行
テストのために'--limit'を使用してアイテムのサブセットのみを処理します。'--idlist'を使用して特定のレコードをインポートします。大規模なマイグレーションで進捗を監視するために'--feedback'を使用します。
複数のマイグレーション間でのマイグレーション設定の共有
MODULE.migrate_shared_configuration.ymlまたはmigrate_shared_configuration/*.ymlファイルで共有設定を作成します。マイグレーションで'include'キーを使用して共有設定を参照し、共通のソース、プロセス、デスティネーション設定をDRYに保ちます。
Tips
- マイグレーションが'インポート中'または'ロールバック中'のステータスでスタックしている場合は'drush migrate:reset-status'を使用します
- '--sync'オプションは強力ですが破壊的です - ソースにないデスティネーションコンテンツを削除します
- 自動化スクリプトでは'--continue-on-failure'を使用して、1つのマイグレーションの失敗がバッチ全体を停止するのを防ぎます
- UIの実行フォームはバッチ処理を使用し、直接のPHP実行よりも大規模なマイグレーションに適しています
- 完全なUI機能のためにMigrate Plusモジュールをインストールしてください - ないとDrushコマンドのみが利用可能です
- インタラクティブな出力がサポートされていないCI/CD環境では'--skip-progress-bar'を使用します
- インポートを実行する前に'drush migrate:tree'でマイグレーションの依存関係を確認して実行順序を理解します
- '--idlist-delimiter'オプションを使用すると、ソースIDにコロンが含まれている場合にカスタム区切り文字を使用できます
Technical Details
Admin Pages 10
/admin/structure/migrate
システムで定義されているすべてのマイグレーショングループを一覧表示します。グループラベル、マシン名、説明、ソースタイプを表示します。各グループ内のマイグレーションの一覧表示、グループ設定の編集、グループの削除などの操作を提供します。
/admin/structure/migrate/add
新しいマイグレーショングループを作成するフォーム。マイグレーショングループは関連するマイグレーションをまとめて整理し、共通の設定を共有できます。
/admin/structure/migrate/manage/{migration_group}
既存のマイグレーショングループのラベル、説明、ソースタイプを含む設定を編集するフォーム。
/admin/structure/migrate/manage/{migration_group}/migrations
特定のマイグレーショングループ内のすべてのマイグレーションを一覧表示します。マイグレーションのステータス、合計ソース数、インポート済み数、未処理数、メッセージ数、最終インポートタイムスタンプを表示します。
/admin/structure/migrate/manage/{migration_group}/migrations/{migration}
グループの割り当て、説明、依存関係（必須とオプションの両方）を含む特定のマイグレーションの概要情報を表示します。
/admin/structure/migrate/manage/{migration_group}/migrations/{migration}/source
マイグレーションのソースプラグイン設定と利用可能なソースフィールドを表示します。ソースのクエリ/設定と、フィールドのマシン名と説明のテーブルを表示します。
/admin/structure/migrate/manage/{migration_group}/migrations/{migration}/process
ソースフィールドがどのようにマッピングされ、デスティネーションフィールドに変換されるかを示すプロセスパイプライン設定を表示します。
/admin/structure/migrate/manage/{migration_group}/migrations/{migration}/destination
デスティネーションタイプと利用可能なデスティネーションフィールドを含むデスティネーションプラグイン情報を表示します。
/admin/structure/migrate/manage/{migration_group}/migrations/{migration}/execute
インポート、ロールバック、停止、リセットを含むマイグレーション操作を実行するフォーム。既存アイテムの更新、依存関係の無視、アイテム数の制限、IDリストによるフィルタリングのオプションを提供します。
/admin/structure/migrate/manage/{migration_group}/migrations/{migration}/messages
マイグレーションインポート中に生成されたメッセージのページ分割されたリストを表示します。ソースID、重大度レベル、メッセージテキスト、デスティネーションID、行のステータスを表示します。
権限 1
Hooks 2
hook_migration_plugins_alter
モジュールがマイグレーションプラグイン定義を変更できるようにします。Migrate Toolsはこれを使用して共有設定の'include'ディレクティブを処理します。
hook_migrate_prepare_row
モジュールが処理前に行を変更できるようにします。Migrate Toolsはこれを使用して同期機能のためにソースIDを追跡します。
Drush Commands 9
drush migrate:status
グループ、マイグレーションID、ステータス、合計アイテム数、インポート済み数、未処理数、メッセージ数、最終インポートタイムスタンプを含む現在のステータスですべてのマイグレーションを一覧表示します。
drush migrate:import
1つ以上のマイグレーションインポート操作を実行します。未処理のソースレコードをDrupalデスティネーションEntityにインポートします。
drush migrate:rollback
1つ以上のマイグレーションによって作成されたデスティネーションEntityをロールバック（削除）します。
drush migrate:stop
アクティブなマイグレーション操作をクリーンに停止し、現在のアイテムが完了してから停止します。
drush migrate:reset-status
マイグレーションのステータスをアイドルにリセットします。マイグレーションがインポート中またはロールバック中のステータスでスタックしている場合に使用します。
drush migrate:disable
マイグレーションを無効化し、再度有効化されるまで実行を防止します。
drush migrate:messages
マイグレーションインポートに関連するメッセージ（エラー、警告、通知）を表示します。
drush migrate:fields-source
マイグレーションで利用可能なすべてのソースフィールドを、マシン名と説明とともに一覧表示します。
drush migrate:tree
どのマイグレーションが他のマイグレーションに依存しているかを示す依存関係ツリーを表示します。