data migration desktop tool
2.1.6
Para acessar a versão arquivada da ferramenta, navegue até a ramificação Arquivo .
A Ferramenta de Migração de Dados de Área de Trabalho do Azure Cosmos DB é um projeto de código aberto que contém um aplicativo de linha de comando que fornece funcionalidade de importação e exportação para o Azure Cosmos DB.
Para usar a ferramenta, baixe o arquivo zip mais recente para sua plataforma (win-x64, mac-x64 ou linux-x64) em Releases e extraia todos os arquivos para o local de instalação desejado. Para iniciar uma operação de transferência de dados, primeiro preencha o arquivo migrationsettings.json com as configurações apropriadas para sua fonte de dados e coletor (consulte as instruções detalhadas abaixo ou revise os exemplos) e, em seguida, execute o aplicativo a partir de uma linha de comando: dmt.exe no Windows ou dmt em outras plataformas.
Várias extensões são fornecidas neste repositório. Encontre a documentação para uso e configuração de cada um usando os links fornecidos:
Banco de dados do Azure Cosmos
API de Tabela do Azure
JSON
MongoDB
Servidor SQL
Parquete
CSV
Armazenamento de arquivos
Armazenamento de Blobs do Azure
AWS S3
Pesquisa Cognitiva do Azure
A Ferramenta de Migração de Dados de Desktop do Azure Cosmos DB é um executável leve que aproveita a Estrutura de Extensibilidade Gerenciada (MEF). O MEF permite a implementação dissociada do projeto principal e suas extensões. O aplicativo principal é um executável de linha de comando responsável por compor as extensões necessárias em tempo de execução, carregando-as automaticamente da pasta Extensões do aplicativo. Uma extensão é uma biblioteca de classes que inclui a implementação de um sistema como fonte e (opcionalmente) coletor para transferência de dados. O projeto principal do aplicativo não contém referências diretas a nenhuma implementação de extensão. Em vez disso, estes projetos partilham uma interface comum.
O projeto principal da ferramenta de migração de dados Cosmos DB é um executável de linha de comando C#. O aplicativo principal serve como contêiner de composição para as extensões Source e Sink necessárias. Portanto, o usuário do aplicativo precisa colocar apenas o assembly da biblioteca de classes Extension desejado na pasta Extensions antes de executar o aplicativo. Além disso, o projeto principal possui um projeto de teste unitário para exercitar o comportamento da aplicação, enquanto os projetos de extensão contêm testes concretos de integração que dependem de sistemas externos.
Este projeto adotou o Código de Conduta de Código Aberto da Microsoft. Para obter mais informações, consulte as Perguntas frequentes sobre o Código de Conduta ou entre em contato com [email protected] com perguntas ou comentários adicionais.
git clone https://github.com/AzureCosmosDB/data-migration-desktop-tool.git Usando o Visual Studio 2022, abra CosmosDbDataMigrationTool.sln .
Crie o projeto usando o atalho de teclado Ctrl + Shift + B ( Cmd + Shift + B em um Mac). Isso criará todos os projetos de extensão atuais, bem como o aplicativo Core da linha de comando. Os assemblies de construção dos projetos de extensão são gravados na pasta Extensões da construção do aplicativo Core . Desta forma, todas as opções de extensão estarão disponíveis quando o aplicativo for executado.
Este tutorial descreve como usar a ferramenta de migração de dados de área de trabalho do Azure Cosmos DB para mover dados JSON para o Azure Cosmos DB. Este tutorial usa o emulador do Azure Cosmos DB.
Inicie o aplicativo emulador do Azure Cosmos DB e abra https://localhost:8081/_explorer/index.html em um navegador.
Selecione a opção Explorer no menu esquerdo. Em seguida, escolha o link Novo banco de dados encontrado abaixo do título Tarefas comuns .
Na folha Novo banco de dados , insira datamigration no campo ID do banco de dados e selecione OK .
Se o banco de dados de migração de dados não aparecer na lista de bancos de dados, selecione o ícone Atualizar .
Expanda o menu de reticências próximo ao banco de dados de migração de dados e selecione Novo contêiner .
Na folha Novo contêiner , insira btcdata no campo ID do contêiner e /id no campo Chave de partição . Selecione o botão OK .
Observação : ao usar a ferramenta Cosmos DB Data Migration, o contêiner não precisa existir anteriormente; ele será criado automaticamente usando a chave de partição especificada na configuração do coletor.
Cada extensão contém um documento README que descreve a configuração para a migração de dados. Nesse caso, localize a configuração para JSON (Fonte) e Cosmos DB (Sink).
No Visual Studio Solution Explorer, expanda o projeto Microsoft.Data.Transfer.Core e abra Migrationsettings.json . Este arquivo fornece um exemplo de estrutura do arquivo de configurações. Usando a documentação vinculada acima, configure as seções SourceSettings e SinkSettings . Certifique-se de que a configuração FilePath seja o local onde os dados de amostra são extraídos. A configuração ConnectionString pode ser encontrada na tela de início rápido do emulador do Cosmos DB como Primary Connection String . Salve o arquivo.
Nota : Os termos alternativos Destino e Destino podem ser usados no lugar de Sink em arquivos de configuração e parâmetros de linha de comando. Por exemplo,
"Target"e"TargetSettings"também seriam válidos no exemplo abaixo.
{
"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
}
}
Certifique-se de que o projeto Cosmos.DataTransfer.Core esteja definido como o projeto de inicialização e pressione F5 para executar o aplicativo.
O aplicativo então executa a migração de dados. Após alguns instantes, o processo indicará Transferência de dados concluída. ou Falha na transferência de dados .
Nota : As propriedades
SourceeSinkdevem corresponder ao DisplayName definido no código das extensões.
Baixe a versão mais recente ou certifique-se de que o projeto foi compilado.
A pasta Extensões contém os plug-ins disponíveis para uso na migração. Cada extensão está localizada em uma pasta com o nome da fonte de dados. Por exemplo, a extensão Cosmos DB está localizada na pasta Cosmos . Antes de executar o aplicativo, você pode abrir a pasta Extensões e remover quaisquer pastas de extensões que não sejam necessárias para a migração.
Na raiz da pasta de compilação, localize migraçãosettings.json e atualize as configurações conforme documentado na documentação da extensão. Arquivo de exemplo (semelhante ao tutorial acima):
{
"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 : migraçãosettings.json também pode ser configurado para executar várias operações de transferência de dados com um único comando de execução. Para fazer isso, inclua uma propriedade
Operationsque consiste em uma matriz de objetos que inclui propriedadesSourceSettingseSinkSettingsusando o mesmo formato mostrado acima para operações únicas. Detalhes e exemplos adicionais podem ser encontrados nesta postagem do blog.
Execute o programa usando o seguinte comando:
Usando o Windows
dmt.exeNota : Use a opção
--settingscom um caminho de arquivo para especificar um arquivo de configurações diferente (substituindo o arquivo migraçãosettings.json padrão). Isto facilita a automatização da execução de diferentes trabalhos de migração num ciclo programático.
Usando macOS
./dmtObservação : antes de executar a ferramenta no macOS, você precisará seguir as instruções da Apple sobre como abrir um aplicativo Mac de um desenvolvedor não identificado.
Decida que tipo de extensão você deseja criar. Existem 3 tipos diferentes de extensões e cada uma delas pode ser implementada para ler dados, gravar dados ou ambos.
Adicione uma nova pasta na pasta Extensões com o nome da sua extensão.
Crie o projeto de extensão e um projeto de teste que o acompanha.
Cosmos.DataTransfer.<Name>Extension .As extensões de armazenamento de arquivos binários são usadas apenas em combinação com outras extensões, portanto devem ser colocadas em uma biblioteca de classes .NET 6 sem a configuração de depuração adicional necessária abaixo.
Adicione os novos projetos à solução CosmosDbDataMigrationTool .
Para facilitar a depuração local, a saída da compilação da extensão, juntamente com quaisquer dependências, precisa ser copiada para a pasta CoreCosmos.DataTransfer.CorebinDebugnet6.0Extensions . Para configurar o projeto para cópia automática, adicione as seguintes alterações.
LocalDebugFolder com um local de destino de ......CoreCosmos.DataTransfer.CorebinDebugnet6.0Extensions< Target Name = " PublishDebug " AfterTargets = " Build " Condition = " '$(Configuration)' == 'Debug' " >
< Exec Command = " dotnet publish --no-build -p:PublishProfile=LocalDebugFolder " />
</ Target > Adicione referências ao pacote System.ComponentModel.Composition NuGet e ao projeto Cosmos.DataTransfer.Interfaces .
As extensões podem implementar IDataSourceExtension para ler dados ou IDataSinkExtension para gravar dados. As classes que implementam essas interfaces devem incluir um System.ComponentModel.Composition.ExportAttribute de nível de classe com o tipo de interface implementada como parâmetro. Isso permitirá que o plugin seja escolhido pelo aplicativo principal.
IComposableDataSource ou IComposableDataSink . Para serem utilizados com diferentes formatos de arquivo, os projetos que contêm os formatadores devem referenciar o projeto da extensão e adicionar novos CompositeSourceExtension ou CompositeSinkExtension referenciando as extensões de armazenamento e formatador.IFormattedDataReader ou IFormattedDataWriter . Para ser utilizável, cada um também deve declarar um ou mais CompositeSourceExtension ou CompositeSinkExtension para definir locais de armazenamento disponíveis para o formato. Isso exigirá a adição de referências a projetos de extensão de armazenamento e a adição de uma declaração para cada combinação de formato de arquivo/armazenamento. Exemplo: [ Export ( typeof ( IDataSinkExtension ) ) ]
public class JsonAzureBlobSink : CompositeSinkExtension < AzureBlobDataSink , JsonFormatWriter >
{
public override string DisplayName => " JSON-AzureBlob " ;
}IConfiguration passada para os métodos ReadAsync e WriteAsync . As configurações em SourceSettings / SinkSettings serão incluídas, bem como quaisquer configurações incluídas nos arquivos JSON especificados por SourceSettingsPath / SinkSettingsPath . Implemente sua extensão para leitura e/ou gravação usando a interface genérica IDataItem que expõe as propriedades do objeto como uma lista de pares de valores-chave. Dependendo da estrutura específica do tipo de armazenamento de dados que está sendo implementado, você pode optar por suportar objetos e matrizes aninhados ou apenas propriedades planas de nível superior.
As extensões de armazenamento de arquivos binários se preocupam apenas com armazenamento genérico, portanto, funcionam apenas com instâncias
Streamque representam arquivos inteiros, em vez deIDataItemindividuais.
