data migration desktop tool

Outil de migration de données de bureau Azure Cosmos DB

Pour accéder à la version archivée de l'outil, accédez à la branche Archive .

---

• Outil de migration de données de bureau Azure Cosmos DB
  • Aperçu
  • Documentation des extensions
  • Architecture
  • Structure du projet
  • Commencer
    • Cloner le référentiel de code source
    • Construire la solution
  • Tutoriel : Migration de JSON vers Cosmos DB
    • Prérequis du logiciel de didacticiel
    • Tâche 1 : provisionner un exemple de base de données et un conteneur à l'aide de l'émulateur Azure Cosmos DB comme destination (récepteur)
    • Tâche 2 : Préparer les documents sources JSON
    • Tâche 3 : Configurer la configuration de la migration des données
  • Utiliser la ligne de commande
  • Création d'extensions

Aperçu

L'outil de migration de données de bureau Azure Cosmos DB est un projet open source contenant une application de ligne de commande qui fournit des fonctionnalités d'importation et d'exportation pour Azure Cosmos DB.

Installation rapide

Pour utiliser l'outil, téléchargez le dernier fichier zip pour votre plate-forme (win-x64, mac-x64 ou linux-x64) à partir des versions et extrayez tous les fichiers vers l'emplacement d'installation souhaité. Pour commencer une opération de transfert de données, remplissez d'abord le fichier migrationsettings.json avec les paramètres appropriés pour votre source de données et votre récepteur (voir les instructions détaillées ci-dessous ou consultez des exemples), puis exécutez l'application à partir d'une ligne de commande : dmt.exe sous Windows ou dmt sur d'autres plateformes.

Documentation des extensions

Plusieurs extensions sont fournies dans ce référentiel. Retrouvez la documentation d'utilisation et de configuration de chacun en utilisant les liens fournis :

1. Azure Cosmos DB

2. API de table Azure

3. JSON

4. MongoDB

5. Serveur SQL

6. Parquet

7. CSV

8. Stockage de fichiers

9. Stockage Blob Azure

10. AWS S3

11. Recherche cognitive Azure

Architecture

L’outil de migration de données de bureau Azure Cosmos DB est un exécutable léger qui exploite le Managed Extensibility Framework (MEF). MEF permet une mise en œuvre découplée du projet principal et de ses extensions. L'application principale est un exécutable de ligne de commande chargé de composer les extensions requises au moment de l'exécution en les chargeant automatiquement à partir du dossier Extensions de l'application. Une extension est une bibliothèque de classes qui inclut l'implémentation d'un système en tant que source et (éventuellement) récepteur pour le transfert de données. Le projet d'application principal ne contient aucune référence directe à une implémentation d'extension. Au lieu de cela, ces projets partagent une interface commune.

Structure du projet

Le projet principal de l’outil de migration de données Cosmos DB est un exécutable de ligne de commande C#. L'application principale sert de conteneur de composition pour les extensions Source et Sink requises. Par conséquent, l’utilisateur de l’application doit placer uniquement l’assembly de bibliothèque de classes Extension souhaité dans le dossier Extensions avant d’exécuter l’application. De plus, le projet principal comporte un projet de tests unitaires pour tester le comportement de l'application, tandis que les projets d'extension contiennent des tests d'intégration concrets qui s'appuient sur des systèmes externes.

Ce projet a adopté le code de conduite Microsoft Open Source. Pour plus d’informations, consultez la FAQ sur le code de conduite ou contactez [email protected] pour toute question ou commentaire supplémentaire.

Commencer

Cloner le référentiel de code source

1. À partir d'une invite de commande, exécutez la commande suivante dans un dossier de travail vide qui hébergera le code source.

git clone https://github.com/AzureCosmosDB/data-migration-desktop-tool.git

Construire la solution

1. À l’aide de Visual Studio 2022, ouvrez CosmosDbDataMigrationTool.sln .

2. Créez le projet à l'aide du raccourci clavier Ctrl + Shift + B ( Cmd + Shift + B sur un Mac). Cela construira tous les projets d'extension en cours ainsi que l'application Core en ligne de commande. Les assemblys de build des projets d’extension sont écrits dans le dossier Extensions de la build de l’application Core . De cette façon, toutes les options d'extension sont disponibles lorsque l'application est exécutée.

Tutoriel : Migration de JSON vers Cosmos DB

Ce didacticiel explique comment utiliser l'outil de migration de données de bureau Azure Cosmos DB pour déplacer des données JSON vers Azure Cosmos DB. Ce didacticiel utilise l'émulateur Azure Cosmos DB.

Prérequis du logiciel de didacticiel

1. Visual Studio 2022
2. Kit de développement logiciel .NET 6.0
3. Émulateur Azure Cosmos DB ou ressource Azure Cosmos DB.

Tâche 1 : provisionner un exemple de base de données et un conteneur à l'aide de l'émulateur Azure Cosmos DB comme destination (récepteur)

1. Lancez l'application d'émulation Azure Cosmos DB et ouvrez https://localhost:8081/_explorer/index.html dans un navigateur.

2. Sélectionnez l'option Explorateur dans le menu de gauche. Choisissez ensuite le lien Nouvelle base de données situé sous l'en-tête Tâches courantes .

   

3. Dans le panneau Nouvelle base de données , saisissez datamigration dans le champ ID de base de données , puis sélectionnez OK .

   

4. Si la base de données de migration de données n'apparaît pas dans la liste des bases de données, sélectionnez l'icône Actualiser .

   

5. Développez le menu points de suspension à côté de la base de données de migration de données et sélectionnez Nouveau conteneur .

   

6. Dans le panneau Nouveau conteneur , saisissez btcdata dans le champ ID du conteneur et /id dans le champ Clé de partition . Sélectionnez le bouton OK .

   

   Remarque : lors de l'utilisation de l'outil de migration de données Cosmos DB, il n'est pas nécessaire que le conteneur existe au préalable, il sera créé automatiquement à l'aide de la clé de partition spécifiée dans la configuration du récepteur.

Tâche 2 : Préparer les documents sources JSON

1. Localisez le fichier docs/resources/sample-data.zip . Extrayez les fichiers dans n’importe quel dossier souhaité. Ces fichiers servent de données JSON à migrer vers Cosmos DB.

Tâche 3 : Configurer la configuration de la migration des données

1. Chaque extension contient un document README qui décrit la configuration de la migration des données. Dans ce cas, recherchez la configuration pour JSON (Source) et Cosmos DB (Sink).

2. Dans l'Explorateur de solutions Visual Studio, développez le projet Microsoft.Data.Transfer.Core et ouvrez migrationsettings.json . Ce fichier fournit un exemple de structure du fichier de paramètres. À l’aide de la documentation liée ci-dessus, configurez les sections SourceSettings et SinkSettings . Assurez-vous que le paramètre FilePath correspond à l’emplacement où les exemples de données sont extraits. Le paramètre ConnectionString se trouve sur l’écran de démarrage rapide de l’émulateur Cosmos DB en tant que chaîne de connexion principale . Enregistrez le fichier.

   Remarque : Les termes alternatifs Target et Destination peuvent être utilisés à la place de Sink dans les fichiers de configuration et les paramètres de ligne de commande. Par exemple, "Target" et "TargetSettings" seraient également valides dans l'exemple ci-dessous.

   {
       "Source" : " JSON " ,
       "Sink" : " Cosmos-nosql " ,
       "SourceSettings" : {
           "FilePath" : " C: \ btcdata \ simple_json.json "
       },
       "SinkSettings" : {
           "ConnectionString" : " AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDj... " ,
           "Database" : " datamigration " ,
           "Container" : " btcdata " ,
           "PartitionKeyPath" : " /id " ,
           "RecreateContainer" : false ,
           "IncludeMetadataFields" : false
       }
   }

   

3. Assurez-vous que le projet Cosmos.DataTransfer.Core est défini comme projet de démarrage, puis appuyez sur F5 pour exécuter l'application.

4. L'application effectue ensuite la migration des données. Après quelques instants, le processus indiquera Transfert de données terminé. ou Le transfert de données a échoué .

Remarque : les propriétés Source et Sink doivent correspondre au DisplayName défini dans le code des extensions.

Utiliser la ligne de commande

1. Téléchargez la dernière version ou assurez-vous que le projet est construit.

2. Le dossier Extensions contient les plug-ins disponibles pour une utilisation dans la migration. Chaque extension se trouve dans un dossier portant le nom de la source de données. Par exemple, l'extension Cosmos DB se trouve dans le dossier Cosmos . Avant d'exécuter l'application, vous pouvez ouvrir le dossier Extensions et supprimer tous les dossiers des extensions qui ne sont pas requis pour la migration.

3. À la racine du dossier de construction, recherchez le fichier migrationsettings.json et mettez à jour les paramètres comme indiqué dans la documentation de l'extension. Exemple de fichier (similaire au tutoriel ci-dessus) :

   {
       "Source" : " JSON " ,
       "Sink" : " Cosmos-nosql " ,
       "SourceSettings" : {
           "FilePath" : " C: \ btcdata \ simple_json.json "
       },
       "SinkSettings" : {
           "ConnectionString" : " AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDj... " ,
           "Database" : " datamigration " ,
           "Container" : " btcdata " ,
           "PartitionKeyPath" : " /id " ,
           "RecreateContainer" : false ,
           "IncludeMetadataFields" : false
       }
   }

Remarque : migrationsettings.json peut également être configuré pour exécuter plusieurs opérations de transfert de données avec une seule commande d'exécution. Pour ce faire, incluez une propriété Operations composée d'un tableau d'objets qui incluent les propriétés SourceSettings et SinkSettings en utilisant le même format que ceux indiqués ci-dessus pour les opérations uniques. Des détails et des exemples supplémentaires peuvent être trouvés dans cet article de blog.

4. Exécutez le programme à l'aide de la commande suivante :

   Utiliser Windows

   dmt.exe

   Remarque : utilisez l'option --settings avec un chemin de fichier pour spécifier un fichier de paramètres différent (en remplaçant le fichier migrationsettings.json par défaut). Cela facilite l'automatisation de l'exécution de différentes tâches de migration dans une boucle de programmation.

   Utiliser macOS

   ./dmt

   Remarque : Avant d'exécuter l'outil sur macOS, vous devrez suivre les instructions d'Apple pour ouvrir une application Mac provenant d'un développeur non identifié.

Création d'extensions

1. Décidez du type d'extension que vous souhaitez créer. Il existe 3 types d'extensions différents et chacun d'entre eux peut être implémenté pour lire des données, écrire des données ou les deux.

   1. Extension DataSource/DataSink : convient aux sources de données qui incluent à la fois un format de données et un stockage natifs. La plupart des bases de données entrent dans cette catégorie et généralement votre extension sera écrite à l'aide d'un SDK spécifique à ce type de base de données. Par exemple, SQL Server utilise des données structurées sous forme de tables et est accessible via des pilotes qui gèrent la communication sous-jacente avec la base de données.
   2. Extension de stockage de fichiers binaires : concerne uniquement le stockage de fichiers binaires et est indépendante du format de fichier spécifique. Les exemples incluent les fichiers sur le disque local ou les fournisseurs de stockage cloud blob. Ce type d'extension peut être utilisé par n'importe quelle extension de format de fichier.
   3. Extension de format de fichier : gère la traduction des données pour un format de fichier binaire spécifique, mais est indépendante du stockage. Les exemples incluent JSON ou Parquet. Ce type d'extension peut être combiné avec n'importe quelle extension de stockage de fichiers binaires pour créer plusieurs extensions DataSource/DataSink.

2. Ajoutez un nouveau dossier dans le dossier Extensions avec le nom de votre extension.

3. Créez le projet d'extension et un projet de test qui l'accompagne.

   • La convention de dénomination des projets d’extension est Cosmos.DataTransfer.<Name>Extension .
   • Les projets d’extension doivent utiliser le framework .NET 6 et le type d’application console . Un fichier Program.cs doit être inclus afin de créer le projet de console. Un projet d’application console est requis pour que la build inclue les packages référencés NuGet.

   Les extensions de stockage de fichiers binaires ne sont utilisées qu'en combinaison avec d'autres extensions et doivent donc être placées dans une bibliothèque de classes .NET 6 sans la configuration de débogage supplémentaire nécessaire ci-dessous.

4. Ajoutez les nouveaux projets à la solution CosmosDbDataMigrationTool .

5. Afin de faciliter le débogage local, la sortie de la construction de l'extension ainsi que toutes les dépendances doivent être copiées dans le dossier CoreCosmos.DataTransfer.CorebinDebugnet6.0Extensions . Pour configurer le projet afin qu'il soit automatiquement copié, ajoutez les modifications suivantes.

   • Ajoutez un profil de publication au dossier nommé LocalDebugFolder avec un emplacement cible de ......CoreCosmos.DataTransfer.CorebinDebugnet6.0Extensions
   • Pour publier à chaque fois que le projet est généré, modifiez le fichier .csproj pour ajouter une nouvelle étape post-construction :

   < Target Name = " PublishDebug " AfterTargets = " Build " Condition = " '$(Configuration)' == 'Debug' " >
      < Exec Command = " dotnet publish --no-build -p:PublishProfile=LocalDebugFolder " />
   </ Target >

6. Ajoutez des références au package NuGet System.ComponentModel.Composition et au projet Cosmos.DataTransfer.Interfaces .

7. Les extensions peuvent implémenter soit IDataSourceExtension pour lire des données, soit IDataSinkExtension pour écrire des données. Les classes implémentant ces interfaces doivent inclure un niveau de classe System.ComponentModel.Composition.ExportAttribute avec le type d'interface implémenté comme paramètre. Cela permettra au plugin d'être récupéré par l'application principale.

   • Les extensions Binary File Storage implémentent les interfaces IComposableDataSource ou IComposableDataSink . Pour être utilisés avec différents formats de fichiers, les projets contenant les formateurs doivent référencer le projet de l'extension et ajouter un nouveau CompositeSourceExtension ou CompositeSinkExtension faisant référence aux extensions de stockage et de formateur.
   • Les extensions de format de fichier implémentent les interfaces IFormattedDataReader ou IFormattedDataWriter . Afin d'être utilisable, chacun doit également déclarer un ou plusieurs CompositeSourceExtension ou CompositeSinkExtension pour définir les emplacements de stockage disponibles pour le format. Cela nécessitera l'ajout de références aux projets d'extension de stockage et l'ajout d'une déclaration pour chaque combinaison format de fichier/stockage. Exemple:

      [ Export ( typeof ( IDataSinkExtension ) ) ]
     public class JsonAzureBlobSink : CompositeSinkExtension < AzureBlobDataSink , JsonFormatWriter >
     {
         public override string DisplayName => " JSON-AzureBlob " ;
     }

   7. Les paramètres requis par l'extension peuvent être récupérés à partir de n'importe quelle source de configuration .NET standard dans l'application principale à l'aide de l'instance IConfiguration transmise aux méthodes ReadAsync et WriteAsync . Les paramètres sous SourceSettings / SinkSettings seront inclus ainsi que tous les paramètres inclus dans les fichiers JSON spécifiés par SourceSettingsPath / SinkSettingsPath .

8. Implémentez votre extension pour lire et/ou écrire à l'aide de l'interface générique IDataItem qui expose les propriétés de l'objet sous la forme d'une liste de paires clé-valeur. En fonction de la structure spécifique du type de stockage de données implémenté, vous pouvez choisir de prendre en charge les objets et les tableaux imbriqués ou uniquement les propriétés plates de niveau supérieur.

   Les extensions de stockage de fichiers binaires ne concernent que le stockage générique et ne fonctionnent donc qu'avec des instances Stream représentant des fichiers entiers plutôt qu'avec IDataItem individuels.