Integrar o Azure Data Explorer com o Azure Data Factory
O ADF (Azure Data Factory) é um serviço de integração de dados baseado em nuvem que permite integrar diferentes armazenamentos de dados e realizar atividades sobre os dados. O ADF permite criar fluxos de trabalho controlados por dados para orquestrar e automatizar a movimentação e a transformação dos dados. O Azure Data Explorer é um dos armazenamentos de dados com suporte do Azure data Factory.
Atividades do Azure Data Factory para o Azure Data Explorer
Várias integrações com o Azure Data Factory estão disponíveis para usuários do Azure Data Explorer:
Atividade de cópia
A Atividade Copy do Azure Data Factory é usada para transferir dados entre armazenamentos de dados. O Azure Data Explorer tem suporte como uma origem na qual os dados são copiados do Azure Data Explorer para qualquer armazenamento de dados com suporte e um coletor, no qual os dados são copiados de qualquer armazenamento de dados com suporte para o Azure Data Explorer. Para obter mais informações, confira Copiar dados de/para o Azure Data Explorer usando o Azure Data Factory. Para obter um passo a passo detalhado, consulte carregar dados do Azure Data Factory no Azure Data Explorer. O Azure Data Explorer é compatível com o Azure IR (Integration Runtime), usado quando os dados são copiados dentro do Azure e o IR auto-hospedado, usado ao copiar dados de/para armazenamentos de dados situados no local ou em uma rede com controle de acesso, como uma Rede Virtual do Azure. Para obter mais informações, consulte qual IR usar.
Dica
Ao usar a atividade Copy e criar um Serviço vinculado ou um conjunto de dados, selecione o armazenamento de dados Azure Data Explorer (Kusto) e não o armazenamento de dados antigo Kusto.
Atividade de pesquisa
A atividade de pesquisa é usada para executar consultas no Azure Data Explorer. O resultado da consulta será retornado como a saída da atividade de pesquisa e poderá ser usado na próxima atividade do pipeline, conforme descrito na documentação de Pesquisa do ADF.
Além do limite de tamanho de resposta de 5.000 linhas e 2 MB, a atividade também tem um tempo limite de consulta de 1 hora.
Atividade Command
A atividade Command permite a execução de comandos de gerenciamento do Azure Data Explorer. Ao contrário das consultas, os comandos de gerenciamento podem modificar dados ou metadados. Alguns dos comandos de gerenciamento são direcionados para ingerir dados no Azure Data Explorer, usando comandos como .ingestou .set-or-append) ou copiar dados do Azure Data Explorer para armazenamentos de dados externos usando comandos como .export.
Para obter um passo a passo detalhado da atividade de comando, consulte usar a atividade de comando do Azure Data Factory para executar comandos de gerenciamento do Azure Data Explorer. Usar um comando de gerenciamento para copiar dados pode, às vezes, ser uma opção mais rápida e barata do que a atividade Copy. Para determinar quando usar a atividade Command versus a atividade Copy, confira Selecionar entre as atividades Copy e Command ao copiar dados.
Copiar em massa de um modelo de banco de dados
O Cópia em massa de um banco de dados para o Azure Data Explorer usando o modelo do Azure Data Factory é um pipeline predefinido do Azure Data Factory. O modelo é usado para criar vários pipelines por banco de dados ou por tabela para agilizar a cópia de dados.
Fluxos de dados de mapeamento
Os fluxos de dados de mapeamento do Azure Data Factory são transformações de dados visualmente projetadas que permitem aos engenheiros de dados desenvolver uma lógica de transformação de dados gráficos sem escrever nenhum código. Para criar um fluxo de dados e ingerir dados no Azure Data Explorer, use o seguinte método:
- Crie o fluxo de dados de mapeamento.
- Exporte os dados para o Blob do Azure.
- Defina a Grade de Eventos ou a atividade Copy do ADF para ingerir os dados para o Azure Data Explorer.
Selecionar entre as atividades Copy e Command do Azure Data Explorer ao copiar dados
Esta seção ajuda você a selecionar a atividade correta para suas necessidades de cópia de dados.
Ao copiar dados de/para o Azure Data Explorer, há duas opções disponíveis no Azure Data Factory:
- Atividade Copy.
- Atividade de comando do Azure Data Explorer, que executa um dos comandos de gerenciamento que transferem dados no Azure Data Explorer.
Copie dados do Azure Data Explorer
Você pode copiar dados do Azure Data Explorer usando a atividade Copy ou o comando .export. O comando .export executa uma consulta e, em seguida, exporta os resultados dessa consulta.
Confira a tabela a seguir para obter uma comparação da atividade Copy e do comando .export para copiar dados do Azure Data Explorer.
| Atividade de cópia | Comando .export | |
|---|---|---|
| Descrição do fluxo | O ADF executa uma consulta em Kusto, processa o resultado e o envia para o armazenamento de dados de destino. (Armazenamento de dados do coletor do ADF > do Azure Data Explorer>) |
O ADF envia um .export comando de gerenciamento para o Azure Data Explorer, que executa o comando e envia os dados diretamente para o armazenamento de dados de destino. (** Armazenamento de dados do coletor do Azure Data Explorer > **) |
| Armazenamentos de dados de destino com suporte | Uma ampla variedade de armazenamentos de dados com suporte | ADLSv2, Blob do Azure, Banco de Dados SQL |
| Desempenho | Centralizado |
|
| Limites do servidor | Os limites de consulta podem ser estendidos/desabilitados. Por padrão, as consultas do ADF contêm:
|
Por padrão, estende ou desabilita os limites de consulta:
|
Dica
Se o destino da sua cópia for um dos armazenamentos de dados com suporte pelo comando .export e se nenhum dos recursos da atividade Copy for crucial para suas necessidades, selecione o comando .export.
Copiando dados para o Azure Data Explorer
Você pode copiar dados para o Azure Data Explorer usando a atividade Copy ou comandos de ingestão, como ingerir da consulta (.set-or-append, .set-or-replace, .set, .replace) e ingerir do armazenamento [.ingest]).
Confira a tabela a seguir para obter uma comparação da atividade Copy e os comandos de ingestão para copiar dados ao Azure Data Explorer.
| Atividade de cópia | Ingestão de consulta.set-or-append / .set-or-replace / .set / .replace |
Ingestão do armazenamento .ingest |
|
|---|---|---|---|
| Descrição do fluxo | O ADF obtém os dados do armazenamento de dados de origem, converte-os em um formato tabular e faz as alterações necessárias no mapeamento de esquema. Em seguida, o ADF carrega os dados nos Blobs do Azure, divide-os em partes e baixa os Blobs para ingerir na tabela do Azure Data Explorer. (Armazenamento > de dados de origem, blobs > do Azure do ADF>, Azure Data Explorer) |
Esses comandos podem executar uma consulta ou um .show comando e ingerir os resultados da consulta em uma tabela (Azure Data Explorer > , Azure Data Explorer). |
Esse comando ingere dados em uma tabela por meio da "extração" dos dados de um ou mais artefatos de armazenamento em nuvem. |
| Armazenamentos de dados de origem com suporte | variedade de opções | ADLS Gen 2, Blob do Azure, SQL (usando o plug-in sql_request()), Azure Cosmos DB (usando o plug-in cosmosdb_sql_request) e qualquer outro armazenamento de dados que forneça APIs HTTP ou Python. | Sistema de arquivos, Armazenamento de Blobs do Azure, ADLS Gen1, ADLS Gen2 |
| Desempenho | As ingestões são enfileiradas e gerenciadas, o que garante ingestões de tamanho pequeno e assegura alta disponibilidade fornecendo balanceamento de carga, novas tentativas e tratamento de erro. |
|
|
| Limites do servidor |
|
|
|
Dica
- Ao copiar dados do ADF para o Azure Data Explorer use os comandos
ingest from query. - Para conjuntos de dados grandes (>1 GB), use a atividade Copy.
Permissões necessárias
A tabela a seguir lista as permissões necessárias para várias etapas na integração com o Azure Data Factory.
| Etapa | Operação | Nível mínimo de permissões | Observações |
|---|---|---|---|
| Criar um serviço vinculado | Navegação pelo banco de dados | visualizador de banco de dados O usuário conectado usando o ADF deve estar autorizado a ler os metadados do banco de dados. |
O usuário pode fornecer o nome do banco de dados manualmente. |
| Teste a conexão | monitor de banco de dados ou ingestão de tabela A entidade de serviço deve ser autorizada a executar comandos .show no nível do banco de dados ou ingestão no nível da tabela. |
|
|
| Criando um conjunto de dados | Navegação pela tabela | monitor de banco de dados O usuário conectado usando o ADF deve estar autorizado a executar comandos .show no nível do banco de dados. |
O usuário pode fornecer o nome da tabela manualmente. |
| Criando um conjunto de dados ou uma Atividade Copy | Visualizar dados | visualizador de banco de dados A entidade de serviço deve estar autorizada a ler metadados do banco de dados. |
|
| Importar esquema | visualizador de banco de dados A entidade de serviço deve estar autorizada a ler metadados do banco de dados. |
Quando o Azure Data Explorer é a origem de uma cópia de tabela para tabela, o ADF importa o esquema automaticamente, mesmo que o usuário não tenha importado o esquema explicitamente. | |
| Azure Data Explorer como coletor | Criar um mapeamento de coluna por nome | monitor de banco de dados A entidade de serviço deve estar autorizada a executar comandos .show no nível do banco de dados. |
|
|
ingestor de tabela ou administrador de banco de dados A entidade de serviço deve estar autorizada a fazer alterações em uma tabela. |
||
| Ingestão de dados | ingestor de tabela ou administrador de banco de dados A entidade de serviço deve estar autorizada a fazer alterações em uma tabela. |
||
| Azure Data Explorer como origem | Executar consulta | visualizador de banco de dados A entidade de serviço deve estar autorizada a ler metadados do banco de dados. |
|
| Comando da Kusto | De acordo com o nível de permissões de cada comando. |
Desempenho
Se o Azure Data Explorer for a origem e você usar a atividade Lookup, Copy ou Command que contém uma consulta where, confira melhores práticas recomendadas de consulta para obter informações de desempenho e Documentação do ADF para a atividade Copy.
Esta seção aborda o uso da atividade Copy em que o Azure Data Explorer é o coletor. A taxa de transferência estimada para o coletor de Azure Data Explorer é de 11 a 13 MBps. A tabela a seguir detalha os parâmetros que influenciam o desempenho do coletor do Azure Data Explorer.
| Parâmetro | Observações |
|---|---|
| Proximidade geográfica dos componentes | Coloque todos os componentes na mesma região:
|
| Número de DIUs | Uma VM para cada quatro DIUs usadas pelo ADF. Aumentar os DIUs só ajuda se sua origem for um repositório baseado em arquivo com vários arquivos. Cada VM, em seguida, processará um arquivo diferente em paralelo. Portanto, copiar um único arquivo grande tem uma latência maior do que copiar vários arquivos menores. |
| Quantidade e SKU do cluster do Azure Data Explorer | O alto número de nós do Azure Data Explorer aumenta o tempo de processamento de ingestão. O uso de SKUs de desenvolvimento limitará gravemente o desempenho |
| Parallelism | Para copiar uma grande quantidade de dados de um banco de dados, particione seus dados e use um loop ForEach que copia cada partição em paralelo ou use o modelo Cópia em massa do banco de dados para o Azure Data Explorer. Observação: Configurações>grau de paralelismo na atividade Copy não é relevante para o Azure Data Explorer. |
| Complexidade do processamento de dados | A latência varia de acordo com o formato do arquivo de origem, o mapeamento da coluna e a compactação. |
| VM que executa o seu runtime de integração |
|
Dicas e armadilhas comuns
Monitorar o andamento da atividade
Ao monitorar o progresso da atividade, a propriedade Dados gravados pode ser maior do que a propriedade Dados lidos porque os Dados lidos são calculados de acordo com o tamanho do arquivo binário, enquanto os Dados gravados são calculados de acordo com o tamanho na memória, depois que os dados são desserializados e descompactados.
Ao monitorar o andamento da atividade, você pode ver que os dados são gravados no coletor do Azure Data Explorer. Ao consultar a tabela do Azure Data Explorer, você verá que os dados não chegaram. Isso ocorre porque há dois estágios ao copiar para o Azure Data Explorer.
- O primeiro estágio lê os dados de origem, divide-os em partes de 900 MB e carrega cada parte em um Blob do Azure. O primeiro estágio é visto pela exibição de andamento da atividade do ADF.
- O segundo estágio começa quando todos os dados são carregados nos Blobs do Azure. Os nós do cluster baixam os blobs e ingerem os dados na tabela do coletor. Então, os dados são vistos na sua tabela do Azure Data Explorer.
Falha ao ingerir arquivos CSV devido ao escape incorreto
O Azure Data Explorer espera que os arquivos CSV se alinhem com a RFC 4180. Ela espera:
- Os campos que contêm caracteres que exigem escape (como " e novas linhas) devem começar e terminar com um caractere ", sem espaço em branco. Todos os caracteres " dentro do campo têm escape duplicando o caractere " (""). Por exemplo, "Olá, ""mundo""" é um arquivo CSV válido com apenas um registro e apenas um campo ou coluna com o conteúdo Olá, "mundo".
- Todos os registros do arquivo devem ter o mesmo número de colunas e campos.
O Azure Data Factory permite o caractere de barra invertida (escape). Se você gerar um arquivo CSV com um caractere de barra invertida usando o Azure Data Factory, a ingestão do arquivo pelo Azure Data Explorer falhará.
Exemplo
Os seguintes valores de texto: Olá, "mundo"
ABC DEF
"ABC\D"EF
"ABC DEF
Devem aparecer em um arquivo CSV apropriado, da seguinte maneira: "Olá, ""mundo"""
"ABC DEF"
"""ABC\D""EF"
"""ABC DEF"
Usando o caractere de escape padrão (barra invertida), o CSV a seguir não funcionará com o Azure Data Explorer: "Olá, "mundo""
"ABC DEF"
""ABC\D"EF"
""ABC DEF"
Objetos JSON aninhados
Ao copiar um arquivo JSON para o Azure Data Explorer, observe que:
- Não há suporte para matrizes.
- Se a sua estrutura JSON contiver tipos de dados de objeto, o Azure Data Factory mesclará os itens filho do objeto e tentará mapear cada item filho para uma coluna diferente em sua tabela do Azure Data Explorer. Se você quiser que todo o item de objeto seja mapeado para uma única coluna no Azure Data Explorer:
- Faça a ingestão da linha JSON inteira em apenas uma coluna dinâmica no Azure Data Explorer.
- Edite manualmente a definição de pipeline usando o editor de JSON do Azure Data Factory. Em Mapeamentos
- Remova os vários mapeamentos que foram criados para cada item filho e adicione apenas um mapeamento que mapeie o tipo de objeto para a coluna da tabela.
- Após o colchete de fechamento, adicione uma vírgula seguida por:
"mapComplexValuesToString": true.
Especifique propriedades adicionais na hora de copiar para o Azure Data Explorer
Você pode adicionar propriedades de ingestão adicionais especificando-as na atividade de cópia no pipeline.
Para adicionar propriedades
No Azure Data Factory, selecione a ferramenta de lápis Criar.
Em Pipeline, selecione o pipeline no qual você deseja adicionar propriedades de ingestão adicionais.
Na tela Atividades, selecione a atividade Copiar dados.
Nos detalhes da atividade, selecione Coletor e expanda Propriedades adicionais.
Selecione Novo, selecione Adicionar nó ou Adicionar matriz, conforme necessário, e especifique o nome e o valor da propriedade de ingestão. Repita essa etapa se desejar adicionar mais propriedades.
Depois de concluir, salve e publique seu pipeline.