Migrate Spreadsheet
PhpOffice/PhpSpreadsheetライブラリを使用してスプレッドシートファイルからデータをインポートするためのmigrateソースプラグインを提供します。
migrate_spreadsheet
インストール
composer require 'drupal/migrate_spreadsheet:^2.2'
composer require 'drupal/migrate_spreadsheet:^2.0'
概要
Migrate Spreadsheetは、様々なスプレッドシートファイル形式からDrupalへデータをインポートできるDrupalマイグレーションモジュールです。PhpOffice/PhpSpreadsheetライブラリを活用してスプレッドシートファイルを読み取り、解析する強力で柔軟なmigrateソースプラグインを提供します。
このモジュールは、Open Document Format（.ods）、Microsoft Excel形式（.xls、.xlsx）、CSV、SpreadsheetML（.xml）、SYLK（.slk）ファイルなど、幅広いスプレッドシート形式をサポートしています。データの開始位置、ヘッダー行、カラム選択、主キー定義を指定する設定オプションを通じて、きめ細かなデータ抽出制御が可能です。
このプラグインはExcelの内部日付形式を処理するため、PhpSpreadsheetの日付変換ユーティリティとの統合を提供し、日付と時刻の値をシームレスにマイグレーションできます。イテレーターベースのアーキテクチャにより、低メモリ使用量を維持しながら大規模なスプレッドシートを効率的に処理します。
Features
- スプレッドシートファイルからデータをインポートするためのMigrateソースプラグイン（id: 'spreadsheet'）
- 複数のファイル形式をサポート：Open Document Format（.ods）、Office Open XML（.xlsx）、BIFF 8（.xls）、BIFF 5（.xls）、SpreadsheetML（.xml）、SYLK（.slk）、CSV
- セル参照表記（例：A2、B3）でデータの開始位置を指定できる設定可能なデータ起点
- スプレッドシートヘッダーからカラム名をマッピングする柔軟なヘッダー行設定
- 選択的カラムインポート - スプレッドシートから抽出するカラムを正確に指定可能
- フィールドストレージスキーマ定義を持つ複合主キーのサポート
- 行位置を主キーまたは追加データフィールドとして使用するための行インデックス疑似カラム
- 数式計算サポート - 計算されたセル値は自動的に解決されます
- ファイルパスのストリームラッパーサポートにより、様々なストレージバックエンドからの読み取りが可能
- 大規模ファイル処理のための内部キャッシングを備えた効率的なイテレーターベースの処理
- PhpSpreadsheetのexcelToTimestamp()メソッドを使用した日付/時刻変換サポート
Use Cases
Excelスプレッドシートからのユーザーデータインポート
従業員情報を含む企業のExcelファイルからユーザーアカウントをマイグレーションします。スプレッドシートソースを設定して、「社員ID」「メールアドレス」「名」「姓」などのカラムをDrupalユーザーフィールドにマッピングします。社員IDを主キーとして使用し、マイグレーション状態の追跡とロールバックを可能にします。
CSVからの商品カタログマイグレーション
ECプラットフォームやERPシステムからエクスポートされたCSVの商品データをインポートします。SKU、タイトル、説明、価格などの商品カラムをCommerce Productフィールドにマッピングします。複合キーを使用して商品バリエーションを処理します。
LibreOffice Calc（.ods）からのコンテンツマイグレーション
LibreOffice Calcスプレッドシートに保存されたレガシーコンテンツをDrupalコンテンツタイプにマイグレーションします。スプレッドシートでの手動コンテンツ管理から構造化されたCMSへ移行する組織に有用です。
階層構造を持つタクソノミータームのインポート
カテゴリデータを含むスプレッドシートからタクソノミーボキャブラリを構築します。行インデックスをターム IDとして使用し、「親」カラムから親関係をマッピングしてターム階層を確立します。
定期的なデータ同期
定期的にエクスポートされるスプレッドシート（在庫更新、価格変更など）からの繰り返しインポートを設定します。主キーシステムにより、重複を作成せずに既存コンテンツを更新できます。
Excelからの日付フィールドの処理
日付が数値シリアル番号として保存されているExcelファイルから日付とdatetime値をマイグレーションします。プロセスパイプラインでPhpSpreadsheet Date::excelToTimestamp()コールバックを使用してExcelの日付形式をUnixタイムスタンプに変換し、必要に応じて目的の日付文字列形式にフォーマットします。
Tips
- 処理するカラムを制限するために常に'columns'設定を指定してください - これによりパフォーマンスと明確性が向上します
- スプレッドシートに自然な一意識別子がない場合は、'row_index_column'を使用して位置ベースのキーを生成します
- Excelは日付を数値（1900-01-01からの日数）として保存します。callbackプロセスプラグインでPhpOffice\PhpSpreadsheet\Shared\Date::excelToTimestampを使用して変換してください
- 'origin'設定はヘッダー行を除外します - ヘッダーが1行目でデータが2行目から始まる場合は、originを'A2'に設定します
- CSVファイルの場合、ワークシート名は通常、拡張子なしのファイル名か、PhpSpreadsheetが処理するため任意の文字列を使用できます
- イテレーターは数式の値を自動的に計算します - '=A1+B1'のようなセル参照は計算結果を返します
- 'file'パスでストリームラッパー（例：'private://imports/data.xlsx'）を使用して、非公開ディレクトリから読み取ることができます
- 大規模なスプレッドシートをマイグレーションする際、モジュールはファイル全体をメモリに読み込むのではなく、行ごとに効率的にデータを読み取ります
Technical Details
Troubleshooting 7
ファイルパスが正しいことを確認してください。パスはDrupalルートからの相対パスまたは絶対パスが使用できます。Webサーバーユーザーに対してファイルに適切な読み取り権限があることを確認してください。
'worksheet'設定は必須です。スプレッドシートファイルに表示されている正確なワークシート名を指定してください（大文字小文字を区別します）。
'columns'設定のカラム名がスプレッドシートのヘッダーセル値と完全に一致していることを確認してください。設定とスプレッドシートの両方で先頭/末尾の空白をチェックしてください。
'keys'が定義されていない場合、主キーとして使用される疑似カラムの名前を提供するために'row_index_column'を設定する必要があります。
各ヘッダーセルの値はヘッダー行内で一意である必要があります。すべてのヘッダーセルが異なる値を持つようにソーススプレッドシートを編集してください。
Excelは内部的に日付をシリアル番号として保存します。これらの値を変換するために、PhpOffice\PhpSpreadsheet\Shared\Date::excelToTimestampを使用するcallbackプロセスプラグインを追加してください。
指定されたoriginセル参照がワークシートのデータ範囲外にあります。origin座標がスプレッドシートの実際のデータ境界内にあることを確認してください。
Security Notes 3
- 潜在的に機密性の高いデータへの不正アクセスを防ぐため、スプレッドシートファイルは適切なファイル権限で安全な場所に保存してください
- ファイルパスにストリームラッパーを使用する場合、設定された場所がWeb経由で公開アクセスできないことを確認してください
- 信頼できないスプレッドシートソースからデータをマイグレーションする際は、評価される可能性のある悪意のある数式が含まれている可能性があるため注意してください