data migration desktop tool

Herramienta de migración de datos de escritorio de Azure Cosmos DB

Para acceder a la versión archivada de la herramienta, navegue hasta la rama Archivo .

---

• Herramienta de migración de datos de escritorio de Azure Cosmos DB
  • Descripción general
  • Documentación de extensión
  • Arquitectura
  • Estructura del proyecto
  • Empezando
    • Clonar el repositorio de código fuente
    • Construya la solución
  • Tutorial: Migración de JSON a Cosmos DB
    • Requisitos previos del software de tutorial
    • Tarea 1: Aprovisionar una base de datos y un contenedor de ejemplo mediante el emulador de Azure Cosmos DB como destino (receptor)
    • Tarea 2: preparar documentos fuente JSON
    • Tarea 3: Configurar la configuración de migración de datos
  • Usando la línea de comando
  • Creando extensiones

Descripción general

La herramienta de migración de datos de escritorio de Azure Cosmos DB es un proyecto de código abierto que contiene una aplicación de línea de comandos que proporciona funcionalidad de importación y exportación para Azure Cosmos DB.

Instalación rápida

Para utilizar la herramienta, descargue el archivo zip más reciente para su plataforma (win-x64, mac-x64 o linux-x64) desde Versiones y extraiga todos los archivos a la ubicación de instalación deseada. Para comenzar una operación de transferencia de datos, primero complete el archivo migrationsettings.json con la configuración adecuada para su fuente y receptor de datos (consulte las instrucciones detalladas a continuación o revise los ejemplos) y luego ejecute la aplicación desde una línea de comando: dmt.exe en Windows o dmt en otras plataformas.

Documentación de extensión

En este repositorio se proporcionan varias extensiones. Encuentre la documentación para el uso y configuración de cada uno utilizando los enlaces proporcionados:

1. Azure Cosmos DB

2. API de tabla de Azure

3. JSON

4. MongoDB

5. Servidor SQL

6. Parquet

7. CSV

8. Almacenamiento de archivos

9. Almacenamiento de blobs de Azure

10. AWS S3

11. Búsqueda cognitiva de Azure

Arquitectura

La herramienta de migración de datos de escritorio de Azure Cosmos DB es un ejecutable ligero que aprovecha Managed Extensibility Framework (MEF). MEF permite la implementación desacoplada del proyecto principal y sus extensiones. La aplicación principal es un ejecutable de línea de comandos responsable de componer las extensiones requeridas en tiempo de ejecución cargándolas automáticamente desde la carpeta Extensiones de la aplicación. Una extensión es una biblioteca de clases que incluye la implementación de un sistema como fuente y (opcionalmente) receptor para la transferencia de datos. El proyecto de aplicación principal no contiene referencias directas a ninguna implementación de extensión. En cambio, estos proyectos comparten una interfaz común.

Estructura del proyecto

El proyecto principal de la herramienta de migración de datos Cosmos DB es un ejecutable de línea de comandos de C#. La aplicación principal sirve como contenedor de composición para las extensiones Source y Sink requeridas. Por lo tanto, el usuario de la aplicación necesita colocar solo el conjunto de biblioteca de clases de extensión deseado en la carpeta Extensiones antes de ejecutar la aplicación. Además, el proyecto principal tiene un proyecto de prueba unitaria para ejercitar el comportamiento de la aplicación, mientras que los proyectos de extensión contienen pruebas de integración concretas que dependen de sistemas externos.

Este proyecto ha adoptado el Código de conducta de código abierto de Microsoft. Para obtener más información, consulte las preguntas frecuentes sobre el Código de conducta o comuníquese con [email protected] si tiene alguna pregunta o comentario adicional.

Empezando

Clonar el repositorio de código fuente

1. Desde un símbolo del sistema, ejecute el siguiente comando en una carpeta de trabajo vacía que albergará el código fuente.

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

Construya la solución

1. Con Visual Studio 2022, abra CosmosDbDataMigrationTool.sln .

2. Cree el proyecto usando el método abreviado de teclado Ctrl + Shift + B ( Cmd + Shift + B en una Mac). Esto creará todos los proyectos de extensión actuales, así como la aplicación Core de línea de comandos. Los ensamblados de compilación de proyectos de extensión se escriben en la carpeta Extensiones de la compilación de la aplicación principal . De esta manera, todas las opciones de extensión están disponibles cuando se ejecuta la aplicación.

Tutorial: Migración de JSON a Cosmos DB

En este tutorial se describe cómo usar la herramienta de migración de datos de escritorio de Azure Cosmos DB para mover datos JSON a Azure Cosmos DB. En este tutorial se utiliza el emulador de Azure Cosmos DB.

Requisitos previos del software de tutorial

1. Estudio visual 2022
2. SDK de .NET 6.0
3. Emulador de Azure Cosmos DB o recurso de Azure Cosmos DB.

Tarea 1: Aprovisionar una base de datos y un contenedor de ejemplo mediante el emulador de Azure Cosmos DB como destino (receptor)

1. Inicie la aplicación del emulador de Azure Cosmos DB y abra https://localhost:8081/_explorer/index.html en un explorador.

2. Seleccione la opción Explorador en el menú de la izquierda. Luego elija el enlace Nueva base de datos que se encuentra debajo del encabezado Tareas comunes .

   

3. En la hoja Nueva base de datos , ingrese datamigration en el campo Id. de base de datos y luego seleccione Aceptar .

   

4. Si la base de datos de migración de datos no aparece en la lista de bases de datos, seleccione el ícono Actualizar .

   

5. Expanda el menú de puntos suspensivos junto a la base de datos de migración de datos y seleccione Nuevo contenedor .

   

6. En la hoja Nuevo contenedor , ingrese btcdata en el campo Id. de contenedor y /id en el campo Clave de partición . Seleccione el botón Aceptar .

   

   Nota : Cuando se utiliza la herramienta de migración de datos de Cosmos DB, no es necesario que el contenedor exista previamente; se creará automáticamente utilizando la clave de partición especificada en la configuración del receptor.

Tarea 2: preparar documentos fuente JSON

1. Localice el archivo docs/resources/sample-data.zip . Extraiga los archivos a cualquier carpeta que desee. Estos archivos sirven como datos JSON que se migrarán a Cosmos DB.

Tarea 3: Configurar la configuración de migración de datos

1. Cada extensión contiene un documento README que describe la configuración para la migración de datos. En este caso, ubique la configuración para JSON (Fuente) y Cosmos DB (Receptor).

2. En el Explorador de soluciones de Visual Studio, expanda el proyecto Microsoft.Data.Transfer.Core y abra migraciónsettings.json . Este archivo proporciona un esquema de ejemplo de la estructura del archivo de configuración. Utilizando la documentación vinculada anteriormente, configure las secciones SourceSettings y SinkSettings . Asegúrese de que la configuración de FilePath sea la ubicación donde se extraen los datos de muestra. La configuración ConnectionString se puede encontrar en la pantalla de inicio rápido del emulador Cosmos DB como Cadena de conexión principal . Guarde el archivo.

   Nota : Los términos alternativos Destino y Destino se pueden usar en lugar de Receptor en archivos de configuración y parámetros de línea de comando. Por ejemplo, "Target" y "TargetSettings" también serían válidos en el siguiente ejemplo.

   {
       "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. Asegúrese de que el proyecto Cosmos.DataTransfer.Core esté configurado como proyecto de inicio y luego presione F5 para ejecutar la aplicación.

4. Luego, la aplicación realiza la migración de datos. Después de unos momentos, el proceso indicará que la transferencia de datos se completó. o La transferencia de datos falló .

Nota : Las propiedades Source y Sink deben coincidir con el nombre para mostrar establecido en el código de las extensiones.

Usando la línea de comando

1. Descargue la última versión o asegúrese de que el proyecto esté creado.

2. La carpeta Extensiones contiene los complementos disponibles para usar en la migración. Cada extensión se encuentra en una carpeta con el nombre de la fuente de datos. Por ejemplo, la extensión Cosmos DB se encuentra en la carpeta Cosmos . Antes de ejecutar la aplicación, puede abrir la carpeta Extensiones y eliminar las carpetas de las extensiones que no sean necesarias para la migración.

3. En la raíz de la carpeta de compilación, ubique migraciónsettings.json y actualice la configuración como se documenta en la documentación de la extensión. Archivo de ejemplo (similar al tutorial anterior):

   {
       "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
       }
   }

Nota : migraciónsettings.json también se puede configurar para ejecutar múltiples operaciones de transferencia de datos con un solo comando de ejecución. Para hacer esto, incluya una propiedad Operations que consista en una matriz de objetos que incluyan las propiedades SourceSettings y SinkSettings usando el mismo formato que los que se muestran arriba para operaciones individuales. Se pueden encontrar detalles y ejemplos adicionales en esta publicación de blog.

4. Ejecute el programa usando el siguiente comando:

   Usando ventanas

   dmt.exe

   Nota : utilice la opción --settings con una ruta de archivo para especificar un archivo de configuración diferente (anulando el archivo migratoriosettings.json predeterminado). Esto facilita la automatización de la ejecución de diferentes trabajos de migración en un bucle programático.

   Usando MacOS

   ./dmt

   Nota : antes de ejecutar la herramienta en macOS, deberá seguir las instrucciones de Apple sobre cómo abrir una aplicación para Mac de un desarrollador no identificado.

Creando extensiones

1. Decide qué tipo de extensión quieres crear. Hay 3 tipos diferentes de extensiones y cada una de ellas se puede implementar para leer datos, escribir datos o ambos.

   1. Extensión DataSource/DataSink: apropiada para fuentes de datos que incluyen tanto un formato de datos nativo como almacenamiento. La mayoría de las bases de datos entran en esta categoría y, por lo general, su extensión se escribirá utilizando un SDK específico para ese tipo de base de datos. Por ejemplo, SQL Server utiliza datos estructurados como tablas y se accede a ellos a través de controladores que manejan la comunicación subyacente con la base de datos.
   2. Extensión de almacenamiento de archivos binarios: solo se ocupa del almacenamiento de archivos binarios y es independiente del formato de archivo específico. Los ejemplos incluyen archivos en discos locales o proveedores de almacenamiento de blobs en la nube. Este tipo de extensión puede ser utilizado por cualquier extensión de formato de archivo.
   3. Extensión de formato de archivo: maneja la traducción de datos para un formato de archivo binario específico, pero es independiente del almacenamiento. Los ejemplos incluyen JSON o Parquet. Este tipo de extensión se puede combinar con cualquier extensión de Binary File Storage para crear múltiples extensiones DataSource/DataSink.

2. Agregue una nueva carpeta en la carpeta Extensiones con el nombre de su extensión.

3. Cree el proyecto de extensión y un proyecto de prueba adjunto.

   • La convención de nomenclatura para proyectos de extensión es Cosmos.DataTransfer.<Name>Extension .
   • Los proyectos de extensión deben utilizar el marco .NET 6 y el tipo de aplicación de consola . Se debe incluir un archivo Program.cs para poder compilar el proyecto de consola. Se requiere un proyecto de aplicación de consola para que la compilación incluya paquetes a los que se hace referencia NuGet.

   Las extensiones de almacenamiento de archivos binarios solo se usan en combinación con otras extensiones, por lo que deben colocarse en una biblioteca de clases .NET 6 sin la configuración de depuración adicional necesaria a continuación.

4. Agregue los nuevos proyectos a la solución CosmosDbDataMigrationTool .

5. Para facilitar la depuración local, el resultado de la compilación de la extensión junto con las dependencias debe copiarse en la carpeta CoreCosmos.DataTransfer.CorebinDebugnet6.0Extensions . Para configurar el proyecto para que se copie automáticamente, agregue los siguientes cambios.

   • Agregue un perfil de publicación a la carpeta denominada LocalDebugFolder con una ubicación de destino de ......CoreCosmos.DataTransfer.CorebinDebugnet6.0Extensions
   • Para publicar cada vez que se compila el proyecto, edite el archivo .csproj para agregar un nuevo paso posterior a la compilación:

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

6. Agregue referencias al paquete NuGet System.ComponentModel.Composition y al proyecto Cosmos.DataTransfer.Interfaces .

7. Las extensiones pueden implementar IDataSourceExtension para leer datos o IDataSinkExtension para escribir datos. Las clases que implementan estas interfaces deben incluir un System.ComponentModel.Composition.ExportAttribute de nivel de clase con el tipo de interfaz implementado como parámetro. Esto permitirá que la aplicación principal recoja el complemento.

   • Las extensiones de Binary File Storage implementan las interfaces IComposableDataSource o IComposableDataSink . Para usarse con diferentes formatos de archivo, los proyectos que contienen los formateadores deben hacer referencia al proyecto de la extensión y agregar nuevas CompositeSourceExtension o CompositeSinkExtension que hagan referencia a las extensiones de almacenamiento y formateador.
   • Las extensiones de formato de archivo implementan las interfaces IFormattedDataReader o IFormattedDataWriter . Para que sean utilizables, cada uno también debe declarar una o más CompositeSourceExtension o CompositeSinkExtension para definir las ubicaciones de almacenamiento disponibles para el formato. Esto requerirá agregar referencias a proyectos de extensión de almacenamiento y agregar una declaración para cada combinación de formato de archivo/almacenamiento. Ejemplo:

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

   7. La configuración que necesita la extensión se puede recuperar desde cualquier fuente de configuración .NET estándar en la aplicación principal mediante el uso de la instancia IConfiguration pasada a los métodos ReadAsync y WriteAsync . Se incluirán las configuraciones en SourceSettings / SinkSettings así como cualquier configuración incluida en los archivos JSON especificados por SourceSettingsPath / SinkSettingsPath .

8. Implemente su extensión para leer y/o escribir usando la interfaz genérica IDataItem que expone las propiedades del objeto como una lista de pares clave-valor. Dependiendo de la estructura específica del tipo de almacenamiento de datos que se implemente, puede optar por admitir matrices y objetos anidados o solo propiedades planas de nivel superior.

   Las extensiones de Binary File Storage solo se ocupan del almacenamiento genérico, por lo que solo funcionan con instancias Stream que representan archivos completos en lugar de IDataItem individuales.