Specifiche tecniche Data Migration Tool

Questa sezione descrive i dettagli sull'implementazione di Data Migration Tool e come estenderne la funzionalità.

Archivi

Per accedere al codice sorgente Data Migration Tool, consulta l'archivio GitHub.

Requisiti di sistema

I requisiti di sistema per Data Migration Tool sono gli stessi del Magento 2.

Struttura interna

Struttura della directory

Il diagramma seguente rappresenta la struttura di directory di Data Migration Tool:

├── etc                                    --- all configuration files
│   ├── opensource-to-opensource            --- configuration files for migration from Magento Open Source 1 to Magento Open Source 2
│   │   ├── 1.9.1.1
│   │   │   ├── config.xml.dist
│   │   │   └── map.xml.dist
│   │   ├── 1.9.2.0
│   │   │   ├── config.xml.dist
│   │   │   └── map.xml.dist
│   │   ├── ........
│   │   ├── class-map.xml.dist
│   │   ├── deltalog.xml.dist
│   │   └── settings.xml.dist
│   │   ├── ........
│   ├── opensource-to-commerce              --- configuration files for migration from Magento Open Source 1 to Adobe Commerce 2
│   ├── commerce-to-commerce                --- configuration files for migration from Adobe Commerce 1 to Adobe Commerce 2
│   ├── class-map.xsd
│   ├── config.xsd
│   ├── map.xsd
│   └── settings.xsd
├── src
│   └── Migration
│       ├── App                             --- application framework
│       ├── Console
│       ├── Handler                         --- handlers are used by map files
│       │   ├── AbstractHandler.php
│       │   ├── AddPrefix.php
│       │   ├── ConvertIp.php
│       │   ├── ........
│       ├── Logger
│       ├── Reader
│       ├── Mode
│       │   ├── AbstractMode.php
│       │   ├── Data.php
│       │   ├── Delta.php
│       │   └── Settings.php
│       ├── ResourceModel                   --- contains adapter for connection to data storage and classes to work with structured data
│       │   ├── Adapter
│       │   │   └── Mysql.php
│       │   ├── AbstractCollection.php
│       │   ├── AbstractResource.php
│       │   ├── AdapterInterface.php
│       │   ├── Destination.php
│       │   ├── Document.php
│       │   ├── Record.php
│       │   ├── Source.php
│       │   └── Structure.php
│       ├── Config.php
│       ├── Exception.php
│       └── Step                            --- functionality for migrating specific data
│           ├── Eav
│           │   ├── Data.php
│           │   ├── Helper.php
│           │   ├── InitialData.php
│           │   ├── Integrity.php
│           │   └── Volume.php
│           ├── Map
│           │   ├── Data.php
│           │   ├── Delta.php
│           │   ├── Helper.php
│           │   ├── Integrity.php
│           │   └── Volume.php
│           ├── UrlRewrite
│           │   ├── Version11300to2000.php
│           │   ├── Version11410to2000.php
│           │   └── Version191to2000.php
│           ├── ..........
└── tests
    ├── integration
    ├── static
    └── unit

Punto di ingresso

Lo script che esegue il processo di migrazione si trova in: magento-root/bin/magento.

Configurazione

Lo schema per il file di configurazione config.xsd si trova nella directory etc/. Il file di configurazione predefinito (config.xml.dist) viene creato per ogni versione del Magento 1.x. Si trova in una directory separata in etc/.

Il file di configurazione predefinito può essere sostituito da un file personalizzato (vedi sintassi comando).

Il file di configurazione ha la seguente struttura:

<config xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:noNamespaceSchemaLocation="config.xsd">
    <steps mode="settings">
        <step title="Settings step">
            <integrity>Migration\Step\Settings</integrity>
            <data>Migration\Step\Settings</data>
        </step>
    </steps>
    <steps mode="data">
        <step title="Map step">
            <integrity>Migration\Step\Map\Integrity</integrity>
            <data>Migration\Step\Map\Data</data>
            <volume>Migration\Step\Map\Volume</volume>
        </step>
        ...
    </steps>
    <steps mode="delta">
        <step title="Map step">
            <delta>Migration\Step\Map\Delta</delta>
            <volume>Migration\Step\Map\Volume</volume>
        </step>
        ...
    </steps>
    <source>
        <database host="localhost" name="magento1" user="root" password=""/>
    </source>
    <destination>
        <database host="localhost" name="magento2" user="root" password=""/>
    </destination>
    <options>
        <map_file>map-file.xml</map_file>
        <settings_map_file>settings-map-file.xml</settings_map_file>
        <bulk_size>100</bulk_size>
        <custom_option>custom_option_value</custom_option>
        <source_prefix />
        <dest_prefix />
        ...
    </options>
</config>

Modifica l'opzione del prefisso nel caso in cui il Magento sia stato installato con il prefisso nelle tabelle di database. Può essere impostata per i database del Magento 1 e del Magento 2. Utilizzate di conseguenza le opzioni di configurazione "source_prefix" e "dest_prefix".

I dati di configurazione sono accessibili con la classe \Migration\Config.

Passaggi operazioni disponibili

Attributi delle informazioni del database di Source

Attributi delle informazioni del database di destinazione

Connetti utilizzando il protocollo TLS

È inoltre possibile connettersi a un database utilizzando il protocollo TLS, ovvero le chiavi di crittografia pubbliche/private. Aggiungere i seguenti attributi facoltativi all'elemento database:

Ad esempio:

<source>
    <database host="localhost" name="magento1" user="root" ssl_ca="/path/to/file" ssl_cert="/path/to/file" ssl_key="/path/to/file"/>
</source>
<destination>
    <database host="localhost" name="magento2" user="root" ssl_ca="/path/to/file" ssl_cert="/path/to/file" ssl_key="/path/to/file"/>
</destination>

Interni del passaggio

Il processo di migrazione è costituito da passaggi.

Step è un'unità che fornisce le funzionalità necessarie per la migrazione di alcuni dati separati. Il passo può essere costituito da uno o più stadi (controllo di integrità, dati, controllo del volume e delta).

Per impostazione predefinita, sono disponibili diversi passaggi (Mappa, EAV, Riscritture URL e così via). Facoltativamente, puoi anche aggiungere passaggi personalizzati.

Le classi relative ai passi si trovano nella directory src/Migration/Step.

Per eseguire una classe Step, la classe deve essere definita nel file config.xml.

<config xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:noNamespaceSchemaLocation="config.xsd">
    <steps mode="mode_name">
        <step title="Step Name">
            <integrity>Migration\Step\StepName\Integrity</integrity>  <!-- integrity check stage of the step -->
            <data>Migration\Step\StepName\Data</data>
            <volume>Migration\Step\StepName\Volume</volume>
        </step>
        ...
    </steps>
    ...
</config>

Ogni classe stage deve implementare StageInterface.

class StageClass implements StageInterface
{
  /**
   * Perform the stage
   *
   * @return bool
   */
  public function perform()
  {
  }
}

Se la fase dati supporta il rollback, deve implementare l'interfaccia RollbackInterface.

La visualizzazione del passaggio in esecuzione è fornita dal componente ProgressBar di Symfony (vedere Barra di avanzamento). Accedere a questo componente in un passaggio come LogLevelProcessor.

I principali metodi di utilizzo sono:

$this->progress->start();
$this->progress->advance();
$this->progress->finish();

Fasi del passaggio

Controllo dell’integrità

Ogni fase deve verificare che la struttura dell’origine dati (Magento 1 per impostazione predefinita) e la struttura della destinazione dati (Magento 2) siano compatibili. In caso contrario, viene visualizzato un errore con entità non compatibili. Nel caso in cui i campi abbiano tipi di dati diversi (lo stesso campo ha un tipo di dati decimale nel Magento 1 e un numero intero nel Magento 2), viene visualizzato un messaggio di avvertenza (tranne quando era coperto nel file Mappa).

Trasferimento dati

Se il controllo di integrità è stato superato, il trasferimento dei dati è in esecuzione. Se compaiono errori, il rollback viene eseguito per ripristinare lo stato precedente del Magento 2. Se una classe step implementa l'interfaccia RollbackInterface, il metodo rollback viene eseguito in caso di errore.

Controllo volume

Dopo la migrazione dei dati, Controllo volume consente di verificare che tutti i dati siano stati trasferiti correttamente.

Consegna delta

La funzionalità Delta è responsabile della distribuzione del resto dei dati aggiunti dopo la migrazione principale.

Modalità di esecuzione

Lo strumento deve essere eseguito in tre diverse modalità, in particolare:

Ogni modalità dispone di un proprio elenco di passaggi da eseguire. Consulta config.xml

Modalità di migrazione delle impostazioni

La modalità di migrazione delle impostazioni di questo strumento viene utilizzata per trasferire le seguenti entità:

Tutta la configurazione dell'archivio mantiene i propri dati nella tabella core_config_data nel database. Il file settings.xml contiene le regole per questa tabella che vengono applicate durante il processo di migrazione. Questo file descrive le impostazioni che devono essere ignorate, rinominate o che devono modificare i relativi valori. Il file settings.xml ha la seguente struttura:

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:noNamespaceSchemaLocation="settings.xsd">
    <key>
        <ignore>
            <path>path/to/ignore*</path>
        </ignore>
        <rename>
            <path>path/to/rename</path>
            <to>new/path/renamed</to>
        </rename>
    <key>
    <value>
        <transform>
            <path>some/key/to/change</path>
            <handler class="Some\Handler\Class"/>
        </transform>
    </value>
</settings>

Nel nodo <key> sono presenti regole che funzionano con la colonna 'percorso' nella tabella core_config_data. <ignore> regole impediscono allo strumento di trasferire alcune impostazioni. In questo nodo è possibile utilizzare i caratteri jolly. Tutte le altre impostazioni non elencate nel nodo <ignore> sono state migrate. Se il percorso di un'impostazione è stato modificato nel Magento 2, deve essere aggiunto al nodo //key/rename, dove il percorso precedente indica nel nodo //key/rename/path e il nuovo percorso indica nel nodo //key/rename/to.

Nel nodo <value> sono presenti regole che funzionano con la colonna 'value' nella tabella core_config_data. Queste regole hanno lo scopo di trasformare il valore delle impostazioni da parte dei gestori (classi che implementano Migration\Handler\HandlerInterface) e di adattarlo per il Magento 2.

Modalità di migrazione dati

In questa modalità, la maggior parte dei dati viene migrata. Prima della migrazione dei dati, le fasi di controllo dell'integrità vengono eseguite per ogni fase. Se il controllo di integrità viene superato, Data Migration Tool installa le tabelle deltalog (con prefisso m2_cl_*) e i trigger corrispondenti nel database del Magento 1 ed esegue la fase di migrazione dei dati dei passaggi. Quando la migrazione viene completata senza errori, la verifica del volume verifica la coerenza dei dati. Se effettui la migrazione del negozio live, puoi visualizzare un messaggio di avviso. Non preoccuparti, la migrazione delta si occupa di questi dati incrementali. I passaggi di migrazione più importanti sono Map, URL Rewrite ed EAV.

Passaggio mappa

Il passaggio della mappa è responsabile del trasferimento della maggior parte dei dati dal Magento 1 al Magento 2. Questo passaggio legge le istruzioni dal file map.xml (che si trova nella directory etc/). Il file descrive le differenze tra le strutture di dati di origine (Magento 1) e destinazione (Magento 2). Se il Magento 1 contiene tabelle o campi che appartengono a un’estensione che non esiste nel Magento 2, queste entità possono essere posizionate qui per ignorarle mediante il passaggio mappa. In caso contrario, viene visualizzato un messaggio di errore.

Il file della mappa ha il formato successivo:

<?xml version="1.0" encoding="UTF-8"?>
<map xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:noNamespaceSchemaLocation="map.xsd">
    <source>
        <document_rules>
            <ignore>
                <document>some_document2</document>
            </ignore>
            <rename>
                <document>some_document</document>
                <to>some_dest_document</to>
            </rename>
            <log_changes>
                <document key="primary_key">some_dest_document</document>
            </log_changes>
        </document_rules>

        <field_rules>
            <move>
                <field>some_document1.field1</field>
                <to>some_document1.field2</to>
            </move>
            <ignore>
                <field>some_document3.field8</field>
            </ignore>
            <transform>
                <field>some_document1.field1</field>
                <handler class="\Migration\Handler\Convert">
                    <param name="map" value="[value1:value2;value3:value4;value5:value6;]" />
                </handler>
            </transform>
        </field_rules>
    </source>
    <destination>
        <document_rules>
            <ignore>
                <document>some_document8</document>
            </ignore>
        </document_rules>

        <field_rules>
            <transform>
                <field>some_document5.field3</field>
                <handler class="\Migration\Handler\SetValue">
                    <param name="value" value="10" />
                </handler>
            </transform>
        </field_rules>
    </destination>
</map>

Aree:

Opzioni:

Source operazioni disponibili:

Destinazione operazioni disponibili:

Caratteri jolly

Per ignorare documenti con parti simili (document_name_1, document_name_2), è possibile utilizzare la funzionalità dei caratteri jolly. Inserire il simbolo * invece della parte ripetuta (document_name_*) e questa maschera copre tutti i documenti di origine o di destinazione che soddisfano questa maschera.

Passaggio di riscrittura URL

Questo passaggio è complesso perché esistono molti algoritmi diversi sviluppati nel Magento 1 che non sono compatibili con il Magento 2. Per versioni diverse del Magento 1, possono esistere algoritmi diversi. Pertanto, nella cartella Step/UrlRewrite sono presenti classi sviluppate per alcune versioni specifiche di Magento, tra cui Migration\Step\UrlRewrite\Version191to2000. Può trasferire URL Riscrive i dati dal Magento 1.9.1 al Magento 2.

Passaggio EAV

Questo passaggio trasferisce tutti gli attributi (prodotto, cliente, RMA) dal Magento 1 al Magento 2. Utilizza il file map-eav.xml che contiene regole simili a quelle del file map.xml per casi specifici di elaborazione di dati.

Alcune delle tabelle elaborate nel passaggio:

Modalità di migrazione delta

Dopo la migrazione principale, i clienti della vetrina avrebbero potuto aggiungere dati aggiuntivi al database del Magento 1. Per tenere traccia di questi dati, lo strumento imposta i trigger del database per le tabelle all’inizio del processo di migrazione. Per ulteriori informazioni, vedere Eseguire la migrazione dei dati creati da estensioni di terze parti.

Origini dati

Per raggiungere le origini dati del Magento 1 e del Magento 2 e operare con i relativi dati (selezionare, aggiornare, inserire, eliminare), nella cartella Risorse sono presenti molte classi. Migration\ResourceModel\Source e Migration\ResourceModel\Destination sono classi principali. Tutti i passaggi di migrazione lo utilizzano per operare con i dati. Questi dati sono contenuti in classi come Migration\ResourceModel\Document, Migration\ResourceModel\Record, Migration\ResourceModel\Structure, ecc.

Di seguito è riportato un diagramma classi di queste classi:

Registrazione

Al fine di implementare l'output del processo di migrazione e controllare tutti i possibili livelli PSR logger, che viene utilizzato nel Magento, è applicato. La classe \Migration\Logger\Logger è stata implementata per fornire funzionalità di registrazione. Per utilizzare il logger, è necessario iniettarlo tramite l’iniezione di dipendenza del costruttore.

class SomeClass
{
    ...
    protected $logger;

    public function __construct(\Migration\Logger\Logger $logger)
    {
        $this->logger = $logger;
    }
    ...
}

Dopodiché puoi utilizzare questa classe per la registrazione di alcuni eventi:

$this->logger->info("Some information message");
$this->logger->debug("Some debug message");
$this->logger->error("Message about error operation");
$this->logger->warning("Some warning message");

È possibile personalizzare la posizione in cui scrivere le informazioni di registro. Per farlo, aggiungi un gestore al logger utilizzando il metodo pushHandler() del logger. Ogni gestore deve implementare l'interfaccia \Monolog\Handler\HandlerInterface. Per ora ci sono due gestori:

Inoltre, è possibile implementare qualsiasi gestore aggiuntivo. Nel framework di Magento è presente un set di gestori. Esempio di aggiunta di gestori al logger:

// $this->consoleHandler is the object of Migration\Logger\ConsoleHandler class
// $this->logger is the object of Migration\Logger\Logger class
$this->logger->pushHandler($this->consoleHandler);

Per impostare dati aggiuntivi per il logger (modalità corrente, nome tabella) è possibile utilizzare i processori logger. Esiste un processore esistente (MessageProcessor). Viene creato per aggiungere dati "aggiuntivi" per la registrazione dei messaggi e viene chiamato ogni volta che viene eseguito il metodo di registro. MessageProcessor ha protetto $extra var, che contiene valori vuoti per 'mode', 'stage', 'step' e 'table'. I dati aggiuntivi possono essere trasmessi al processore come secondo parametro (contesto) per il metodo log. Set di dati aggiuntivi al processore in AbstractStep->runStage (passaggio della modalità corrente, dello stage e del passaggio al processore) e classi di dati in cui è utilizzato logger->debug method (passaggio del nome della tabella di migrazione). Esempio di aggiunta di processori al logger:

// $this->processoris the object of Migration\Logger\messageProcessor class
// $this->logger is the object of Migration\Logger\Logger class
$this->logger->pushProcessor([$this->processor, 'setExtra']);
// As a second array value you need to pass method that should be executed when processor called

Esiste la possibilità di impostare il livello di dettaglio. Per ora ci sono tre livelli:

È possibile impostare il livello di registro di verifica per ogni gestore separatamente chiamando il metodo setLevel(). Se si desidera impostare il livello di dettaglio tramite il parametro della riga di comando, è necessario modificare l'opzione 'verbose' all'avvio dell'applicazione.

Puoi formattare i messaggi di registro con il formattatore monologo. Per utilizzare la funzionalità di formattazione, è necessario specificare il gestore di registro utilizzando il metodo setFormatter(). Attualmente, è disponibile una classe formattatore (MessageFormatter) che imposta un determinato formato (a seconda del livello di dettaglio) durante la gestione dei messaggi (tramite il metodo format() eseguito dal gestore).

La manipolazione del logger (aggiunta di gestori e processori) e l'elaborazione in modalità dettagliata vengono eseguite nel metodo process() della classe Migration\Logger\Manager. Il metodo viene chiamato all'avvio dell'applicazione.

Test automatici

Esistono tre tipi di test in Data Migration Tool:

Si trovano nella directory tests/ dello strumento, che corrisponde al tipo di test (gli unit test si trovano nella directory tests/unit). Per avviare il test, deve essere installato phpunit. Cambia la directory corrente con la directory di test e avvia phpunit. Ad esempio:

[10:32 AM]-[vagrant@debian-70rc1-x64-vbox4210]-[/var/www/magento2/vendor/magento/data-migration-tool]-[git master]
$ cd tests/unit

[10:33 AM]-[vagrant@debian-70rc1-x64-vbox4210]-[/var/www/magento2/vendor/magento/data-migration-tool/tests/unit]-[git master]
$ phpunit
PHPUnit 8.1.0 by Sebastian Bergmann.
....