外部データインポート＆エクスポート プラグイン
Shopify・MakeShop・汎用CSV/JSONから商品データをEC-CUBEへ安全かつ爆速に取り込み、さらにEC-CUBE 4 標準CSVや各プラットフォーム形式への逆エクスポート、画像最適化、コレクション同期、Cron自動同期、ストレージクリーンアップまでを網羅したオールインワン・データ連携ソリューションです。
1. プラグイン概要と主な特長
本プラグイン（DataImport）は、外部ECプラットフォーム（Shopify、MakeShop）や独自基幹システムのCSV/JSONデータと、EC-CUBE 4系（4.2 / 4.3）との間で、商品データ・規格・カテゴリ・画像の双方向連携を安全かつ自動化するために設計されました。
マルチソース取込
Shopify商品CSV、Shopify公開ストアURL（products.json）、JSONファイル、MakeShop CSV、汎用CSV（列名自動判定）に完全対応。
分割非同期取込
大容量データもタイムアウトなく分割バッチ処理。画面上でリアルタイム進捗バーと作成/更新件数カウンターを表示。
事前プレビュー＆重複検証
取込前にDBを汚さず全件解析。完全新規、既存一致、SKU重複、価格不正をカラーバッジとアコーディオンで事前確認。
EC-CUBE 4 標準CSV出力
EC-CUBE標準の「商品CSV登録」に100%合致する25列CSVを出力。Shopify CSV/JSONやMakeShop形式へも高速ストリーミング出力可能。
画像インメモリ最適化
自動リサイズ、EXIF削除・天地自動回転、WebP自動変換、透過アルファ維持、1商品あたりの最大画像枚数制限を完備。
安全な取消（ロールバック）
誤インポート時も、その実行で新規作成された商品のみを一括安全削除。既存の更新データは完全に保護されます。
Cron 定期同期 & 差分同期
定期バッチによる自動同期。updated_at判定により未変更商品を早期スキップし、所要時間と負荷を極限まで削減。
安全装置 & 3種アラート
消失率上限（安全装置）で誤非公開を緊急停止。実行結果や異常をEmail、Slack、Chatworkへ即時自動通知。
ストレージ管理・孤立画像掃除
取消や削除でDBから参照されなくなったディスク上の不要画像ファイルをスキャンし、バックアップ退避付きで一括削除。
3. データインポート機能
商品データをEC-CUBEへ取り込むメイン画面です。手動CSVアップロードだけでなく、公開ShopifyストアURLからの直接取得にも対応しています。
3.1. データソースの選択
| データソース | 指定方法 | 説明 |
|---|---|---|
| Shopify（商品CSV） | .csv ファイル選択 | Shopify管理画面「商品 ＞ エクスポート」から出力された標準商品CSVをそのまま取り込みます。複数バリエーション・画像URL・タグ・コレクションに対応。 |
| Shopify URL（直接同期） | ストアURL入力 | https://example.myshopify.com を入力すると、公開エンドポイント（/products.json）から直接商品データをダウンロードして同期します。 |
| Shopify JSON | .json ファイル選択 | Shopify APIから取得した {"products": [...]} 形式のJSONファイルを取り込みます。 |
| MakeShop（商品一括登録CSV） | .csv ファイル選択 | MakeShop形式の商品一括登録CSV（独自商品コード、商品名、販売価格、PC用画像、カテゴリ、複数オプション等）を取り込みます。 |
| 汎用CSV（自動判定） | .csv ファイル選択 | 列名（商品コード・商品名・価格・在庫数・画像URL等）をインテリジェントに自動判定してマッピングします。 |
3.2. 取込モード & 既存商品の照合キー
| 取込モード | 動作内容 |
|---|---|
| 上書き更新 | 既存商品が見つかった場合は上書き更新し、存在しない商品は新規追加します（推奨・標準）。 |
| ⚡ 高速・価格＆在庫のみ更新 | 画像ダウンロード・説明文・カテゴリ登録をスキップし、既存商品の販売価格と在庫数のみを超高速で一括更新します。 |
| 新規作成のみ | 既存商品は変更せずスキップし、完全新規の商品のみを取り込みます。 |
| 重複時にエラー | 既存商品または重複が1件でも検出された場合、取込処理を安全に中断します。 |
| 重複時に別名作成 | 既存商品と重複した場合、商品コードおよび規格コードに連番サフィックス（例: CODE-copy）を付与して別商品として登録します。 |
Shopifyの場合は「自動判定（規格コード → 商品コード → 商品名）」または「規格コード」を推奨します。単一規格商品の場合は商品コードでの照合も正確に機能します。
3.3. 画像取込・最適化オプション
| オプション | 設定値・デフォルト | 説明 |
|---|---|---|
| 画像の更新方法 | 追加 / 入替 / スキップ | 「追加」は既存画像を残して空き枠へ登録。「入替」は既存画像を全削除して新しい画像のみを登録。「スキップ」は画像を変更しません。 |
| 最大画像取込枚数 | 無制限 / 1枚 / 3枚 / 5枚 / 10枚 / 20枚 | 1商品あたりに登録する画像枚数の上限を指定可能。サブ画像が多いストアでも不要なダウンロードを防ぎ、サーバー容量と時間を大幅に節約できます。 |
| 画像自動最適化 | 有効 / 無効 | 高解像度画像を自動縮小し、カメラの不要なEXIF情報を削除＆天地を正位置へ自動回転します。 |
| 最大画像幅 | 1600 px（推奨） | 指定した幅（800〜1920px）を超える場合のみ、アスペクト比を保ったまま縮小します。 |
| 次世代WebP形式変換 | 有効 / 無効 | JPEGやPNG画像を画質を維持したままWebP形式へ自動変換し、ファイルサイズを約30%削減します。透過アルファも保護されます。 |
3.4. プレビュー確認 & 分割非同期インポート実行
設定を入力後、「🔍 プレビュー確認」をクリックすると、データベースへの書き込みを行わずにデータ内容・価格・規格・既存重複状態を解析します。
画面上に「全体行数」「完全新規（緑）」「既存一致（青）」「問題あり（赤）」のバッジが表示されます。「バリアント詳細」ボタンで規格内訳も確認可能です。
ファイルを再選択することなく、プレビュー下部の「このプレビュー内容で取込を開始する」ボタンを押すと、分割非同期インポートが即座に開始されます。
4. データエクスポート機能
EC-CUBEに蓄積された商品データを、各種フォーマットで外部へ高速ストリーミング出力します。
4.1. サポートフォーマット
| フォーマット | 拡張子 | 仕様・特徴 |
|---|---|---|
| EC-CUBE 4 標準CSV | .csv | EC-CUBE 4の「商品CSV登録」に完全準拠した25列形式。バックアップや別のEC-CUBE 4ストアへのデータ移行に100%そのまま利用可能。 |
| Shopify 商品CSV | .csv | ShopifyのProduct CSV規格に完全準拠。Handle、Title、Option1/Option2、Variant SKU/Price、Image Srcなどを正しく出力。 |
| Shopify JSON | .json | Shopify API互換の構造化JSON形式（{"products": [...]}）で出力。外部API連携やプログラム処理に最適。 |
| MakeShop CSV | .csv | 国内主要カートMakeShopの商品一括登録フォーマット（独自商品コード、商品名、販売価格等）に変換出力。 |
| 汎用CSV | .csv | クリーンで可読性の高い汎用的な標準列構成（商品ID、コード、商品名、価格、在庫数、カテゴリ、画像等）で出力。 |
4.2. 絞り込み条件と出力オプション
- カテゴリ階層指定: 特定の親カテゴリ配下（サブカテゴリも自動網羅）の商品のみを絞り込み。
- 公開ステータス: すべて / 公開のみ / 非公開のみ。
- 在庫状態: すべて / 在庫あり（無制限含む） / 在庫なし（0点以下）。
- キーワード検索: 商品名、商品コード、検索ワードによる部分一致。
- 画像URL形式: 「完全URL（
https://ドメイン/html/upload/...）」または「ファイル名のみ」。Shopifyへインポートする場合は完全URLが必須です。 - 文字コード: UTF-8（BOM付き）（Microsoft Excelで開いても文字化けしない推奨設定）、Shift_JIS（Windows専用）、UTF-8（BOMなし）。
5. Shopifyコレクション取込機能
Shopifyの公開コレクション（collections.json）を取得し、EC-CUBEの「商品カテゴリ」階層として取り込む専用機能です。
https://example.com を入力し、「URL確認」または「コレクション読込 / プレビュー」をクリックします。
取り込むコレクションを特定のカテゴリ配下にサブカテゴリとして階層化したい場合は、プルダウンから親カテゴリを選択します。
「コレクションに所属する既存商品を自動で紐付ける」にチェックを入れると、各コレクション内の商品を検索し、EC-CUBE上の既存商品へ該当カテゴリを自動で関連付けます。
6. 取込履歴・取消（ロールバック）
メニュー「データ連携」→「取込履歴」では、過去に実行されたすべてのインポートセッション（手動取込、Shopify URL直接同期、Cron自動同期）が一覧管理されます。
6.1. 取込結果ログ詳細モーダル
各履歴の「🔍 ログ詳細」ボタンをクリックすると、ポップアップモーダルが開き、そのセッションで処理されたすべての商品明細（商品コード、商品名、ステータス、エラーメッセージ）を閲覧・検索できます。
6.2. 安全な取消（ロールバック）機能
対象履歴の「取消」ボタンをクリックすると、そのインポートによって新規作成された商品のみをデータベースから一括削除します。
すでに存在していた商品の上書き更新データは保護されるため、店舗運営のデータを壊すことなく安全にリカバリーが可能です。
7. 孤立画像クリーンアップ & ストレージ最適化
取込の取消、画像入替更新、または通常の商品削除によって、データベース（dtb_product_image）から参照されなくなったにもかかわらずサーバーディスク内に残留している不要な物理画像ファイル（ゴミファイル）を検出し、安全に削除します。
操作手順
- 「取込履歴」画面の下部にある 「ストレージ管理・孤立画像クリーンアップ」 パネルを開きます。
- 「🔍 孤立画像スキャン」 ボタンをクリックします。ディスク内の実ファイルとDBの登録状態を高速照合します。
- スキャン結果として「総容量」「有効利用量」「削減可能容量（孤立画像）」が表示されます。
- 安全のため「削除前にバックアップフォルダへ退避する（推奨）」にチェックを入れた状態で「孤立画像をクリーンアップ」を実行します。
8. 自動定期同期 & 障害通知
Shopifyの公開ストアURLから、指定したスケジュール間隔で最新の商品・価格・在庫を自動でバックグラウンド同期する機能です。
8.1. 高速化と安全機能
- ⚡ 高速同期モード: 画像や説明文をスキップし、価格と在庫数のみを更新（所要時間を90%以上短縮）。
- 差分同期モード (updated_at判定): Shopifyの
updated_atを判定し、前回以降に変更があった商品のみを取得・更新。時計ズレ防止バッファも完備。 - 連携元消失商品の自動処理: Shopify側で削除された商品を検知し、安全に「非公開」または「在庫0」に変更。
- 安全装置 (消失率上限 %): API障害等による大量の誤非公開を防ぐため、消失率が閾値（例: 30%）を超えた場合は自動非公開を即時停止します。
8.2. アラート通知設定
定期同期の完了時やエラー発生時に、指定したチャンネルへ自動で通知レポートを配信できます。「テスト通知を送信」ボタンで接続確認が可能です。
8.3. Crontab への登録手順
サーバーの crontab に以下のコマンドを1行追加します：
# 毎時0分に定期同期を実行
0 * * * * /usr/bin/php /var/www/html/bin/console eccube:data-import:cron >> /var/www/html/var/log/data_import_cron.log 2>&19. CLI コマンド完全リファレンス
SSH経由やバッチジョブで利用可能な全コンソールコマンドの一覧です：
| コマンド名 | 主な用途とオプション例 |
|---|---|
eccube:data-import:run | ファイルからの商品インポート。bin/console eccube:data-import:run path/to/file.csv --source=shopify --mode=update --max-images=5 |
eccube:data-import:shopify-url | Shopify URLからの直接同期。bin/console eccube:data-import:shopify-url https://example.com --incremental --fast-sync |
eccube:data-import:export | 商品データのエクスポート。bin/console eccube:data-import:export -f eccube_csv -o var/export/products.csv |
eccube:data-import:cron | Cron定期同期バッチ実行。bin/console eccube:data-import:cron --archive-missing |
eccube:data-import:shopify-collections | Shopifyコレクション取込。bin/console eccube:data-import:shopify-collections https://example.com --link-products |
eccube:data-import:cleanup-images | 孤立画像クリーンアップ。bin/console eccube:data-import:cleanup-images --dry-runbin/console eccube:data-import:cleanup-images --days=3 --backup |
eccube:data-import:optimize-images | 既存画像の一括最適化（リサイズ・WebP化）。bin/console eccube:data-import:optimize-images --max-width=1600 --webp |
eccube:data-import:cleanup | 一時CSVログ・キャッシュの定期クリーンアップ。bin/console eccube:data-import:cleanup --days=30 |
10. よくある質問・トラブルシューティング
Q. 大量の商品画像を取り込むとタイムアウトしませんか？
管理画面からの取込では「分割非同期インポート」が自動で有効になり、数件〜数十件ごとに小分けして順次処理するためタイムアウトは発生しません。さらに高速化したい場合は「1商品あたりの最大画像枚数（例: 3枚または5枚）」を設定することをお勧めします。
Q. エクスポートしたCSVをExcelで開くと文字化けします。
エクスポート設定の「文字コード」で 「UTF-8 (BOM付き)」 を選択して出力してください。Microsoft Excelでダブルクリックしても文字化けせず正常に開けます。
Q. 消失検知で手動登録した商品まで非公開になりませんか？
デフォルトの監視スコープは「同期済み管理商品のみ（推奨・安全）」に設定されています。本プラグインを通じて同期された商品のみが管理対象となり、手動で登録した他の店舗商品には一切干渉しませんのでご安心ください。