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>
  • passaggi: descrive tutti i passaggi elaborati durante la migrazione

  • origine: configurazione per l’origine dati. Tipi di origine disponibili: database

  • destinazione: configurazione per la destinazione dati. Tipi di destinazione disponibili: database

  • options - elenco di parametri. Contiene i parametri obbligatori (map_file, settings_map_file, bulk_size) e facoltativi (custom_option, resource_adapter_class_name, prefix_source, prefix_dest, log_file)

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

Documento
Campo
step
Nodo di secondo livello all’interno del nodo Passaggi. La descrizione del passaggio pertinente deve essere specificata nell'attributo title.
integrity
Specifica la classe PHP responsabile del controllo dell'integrità. Confronta i nomi dei campi, i tipi e altre informazioni della tabella per verificare la compatibilità tra le strutture di dati dei Magenti 1 e 2.
data
Specifica la classe PHP responsabile del controllo dei dati. Trasferisce i dati tabella per tabella dal Magento 1 al Magento 2.
volume
Specifica la classe PHP responsabile del controllo del volume. Confronta il numero di record tra le tabelle per verificare che il trasferimento sia stato eseguito correttamente.
delta
Specifica la classe PHP responsabile del controllo delta. Trasferisce il delta dal Magento 1 al Magento 2 dopo la migrazione completa dei dati.

Attributi delle informazioni del database di Source

Documento
Campo
Obbligatorio
name
Nome del database del server del Magento 1.
host
Indirizzo IP host del server Magento 1.
port
Numero di porta del server del Magento 1.
no
user
Nome utente del server di database del Magento 1.
password
Password del server di database del Magento 1.
ssl_ca
Percorso del file dell’autorità di certificazione SSL.
no
ssl_cert
Percorso del file del certificato SSL.
no
ssl_key
Percorso del file di chiave SSL.
no

Attributi delle informazioni del database di destinazione

Documento
Campo
Obbligatorio
name
Nome del database del server di Magento 2.
host
Indirizzo IP host del server Magento 2.
port
Numero di porta del server del Magento 2.
no
user
Nome utente del server di database del Magento 2.
password
Password del server database di Magento 2.
ssl_ca
Percorso del file dell’autorità di certificazione SSL.
no
ssl_cert
Percorso del file del certificato SSL.
no
ssl_key
Percorso del file di chiave SSL.
no

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:

  • ssl_ca
  • ssl_cert
  • ssl_key

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:

  1. settings - migrazione delle impostazioni di sistema
  2. dati: migrazione principale dei dati
  3. delta: migrazione del resto dei dati aggiunti dopo la migrazione principale

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à:

  1. Siti web, store, visualizzazioni dello store.
  2. Configurazione dello store (principalmente Stores->Configurazione in M2 o System->Configurazione in M1)

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:

  • origine - contiene le regole del database di origine

  • destinazione - contiene le regole del database di destinazione

Opzioni:

  • ignora - il documento, il campo o il tipo di dati contrassegnato con questa opzione viene ignorato

  • rinomina: descrive le relazioni dei nomi tra documenti con un nome diverso. In un caso in cui il nome del documento di destinazione non corrisponde a quello del documento di origine, è possibile utilizzare l'opzione Rinomina per impostare il nome del documento di origine in modo simile al nome della tabella di destinazione

  • sposta - imposta la regola per spostare il campo specificato dal documento di origine al documento di destinazione. NOTA: il nome del documento di destinazione deve corrispondere al nome del documento di origine. Se i nomi dei documenti di origine e di destinazione sono diversi, è necessario utilizzare l'opzione Rinomina per il documento che contiene un campo spostato

  • transform - è un'opzione che consente agli utenti di migrare i campi in base al comportamento descritto nei gestori

  • gestore: descrive il comportamento di trasformazione dei campi. Per chiamare il gestore, è necessario specificare il nome di una classe del gestore in un tag <handler>. Utilizza il tag <param> con il nome del parametro e i dati del valore per trasmetterlo al gestore

Source operazioni disponibili:

Documento
Campo
ignora ridenominazione
ignora trasformazione di spostamento

Destinazione operazioni disponibili:

Documento
Campo
ignora
ignora trasformazione

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:

  • eav_attribute
  • eav_attribute_group
  • eav_attribute_set
  • eav_entity_attribute
  • catalog_eav_attribute
  • customer_eav_attribute
  • eav_entity_type

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:

Struttura dati strumento di migrazione

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:

  • ConsoleHandler: scrive i messaggi nella console

  • FileHandler: scrive i messaggi nel file di log impostato nell'opzione di configurazione "log_file"

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:

  • ERROR (scrive solo gli errori nel registro)
  • INFO (nel registro vengono scritte solo informazioni importanti, valore predefinito)
  • DEBUG (tutto è scritto)

È 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:

  • Statico
  • Unità
  • Integrazione

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.
....
recommendation-more-help
c2d96e17-5179-455c-ad3a-e1697bb4e8c3