Compartilhar via

Usar o LightIngest para ingerir dados no Azure Data Explorer

LightIngest é um utilitário de linha de comando para ingestão de dados ad hoc no Azure Data Explorer. O utilitário pode extrair dados de origem de uma pasta local, um contêiner de armazenamento de blobs do Azure ou um bucket do Amazon S3.

LightIngest é mais útil quando você deseja ingerir uma grande quantidade de dados, pois não há restrição de tempo na duração da ingestão. Ele também é útil quando você deseja consultar registros posteriormente de acordo com a hora em que foram criados, não pela hora em que foram ingeridos.

Para obter um exemplo de como gerar automaticamente um comando LightIngest, consulte ingerir dados históricos.

Observação

A ingestão dá suporte para um tamanho do arquivo máximo de 6 GB. A recomendação é ingerir arquivos entre 100 MB e 1 GB.

Pré-requisitos

Observação

Considere usar os comandos de ingestão por fila, porque eles não exigem a instalação de software.

Executar o LightIngest

Para executar o LightIngest:

  1. No prompt de comando, insira LightIngest seguido do argumento da linha de comando relevante.

    Dica

    Para obter uma lista de argumentos de linha de comando com suporte, insira LightIngest /help.

  2. Insira ingest- seguido pela cadeia de conexão para o cluster do Azure Data Explorer que gerencia a ingestão. Coloque a cadeia de conexão entre aspas duplas e siga a especificação de cadeias de conexão do Kusto.

    Por exemplo:

    LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -pattern:"*.csv.gz" -format:csv -limit:2 -ignoreFirst:true -cr:10.0 -dontWait:true

Recomendações do desempenho

  • Para gerenciar melhor a carga de ingestão e recuperar-se de erros transitórios, use o ponto de extremidade de ingestão em https://ingest-{yourClusterNameAndRegion}.kusto.windows.net.

  • Para obter um desempenho de ingestão ideal, o LightIngest precisa do tamanho bruto dos dados para que possa estimar o tamanho não compactado dos arquivos locais. No entanto, talvez o LightIngest não consiga estimar corretamente o tamanho bruto dos blobs compactados sem primeiro baixá-los. Portanto, ao ingerir blobs compactados, defina a propriedade rawSizeBytes nos metadados do blob como o tamanho dos dados descompactados em bytes.

Argumentos de linha de comando

Argumento Tipo Descrição Obrigatório
string Cadeia de conexão do Kusto especificando o ponto de extremidade do Kusto que processará a ingestão. Coloque esse valor entre aspas duplas. ✔️
-banco de dados, -db string Nome do banco de dados de destino do Azure Data Explorer.
-table string Nome da tabela de destino do Azure Data Explorer. ✔️
-sourcePath, -source string O local dos dados de origem, que pode ser um caminho de arquivo local, o URI raiz de um contêiner de blob do Azure ou o URI de um bucket do Amazon S3. Se os dados forem armazenados em blobs do Azure, o URI deverá incluir a chave da conta de armazenamento ou a SAS (Assinatura de Acesso Compartilhado). Se os dados estiverem em um bucket S3, o URI deverá incluir a chave de credencial. Coloque esse valor entre aspas duplas. Para saber mais, confira a página Cadeias de conexão. Passar -sourcePath:;impersonate para listar itens de armazenamento do Azure com permissões de usuário (autorização de prompt do usuário). ✔️
-identidadeGerenciada, -mi string ID do cliente da identidade gerenciada (atribuída pelo usuário ou atribuída pelo sistema) a ser usada para conexão. Use "system" para a identidade atribuída pelo sistema.
-azCli bool Se definido, usa a CLI do Azure para autenticar no serviço Kusto. A CLI do Azure deve ser instalada e conectada.
-ingestWithManagedIdentity, -ingestmi string ID do cliente da identidade gerenciada (atribuída pelo usuário ou atribuída pelo sistema) instalada no serviço Kusto para download do armazenamento. Use "system" para a identidade atribuída pelo sistema.
-connectToStorageWithManagedIdentity, -storageMi string ID do cliente da identidade gerenciada (atribuída pelo usuário ou atribuída pelo sistema) instalada no lado do cliente para listar do armazenamento.
-conectarAoArmazenamentoComAutenticacaoDoUsuario, -armazenamentoAutenticacaoDoUsuario string Autentique-se no serviço de armazenamento da fonte de dados com as credenciais do usuário. As opções para esse valor são PROMPT ou DEVICE_CODE.
-connectToStorageLoginUri, -storageLoginUri string Se -connectToStorageWithUserAuth estiver definido, você poderá fornecer opcionalmente um URI de entrada do Microsoft Entra ID.
-prefix string Quando os dados de origem a serem ingeridos residem no armazenamento de blobs, esse prefixo de URL é compartilhado por todos os blobs, excluindo o nome do contêiner.
Por exemplo, se os dados estiverem em MyContainer/Dir1/Dir2, o prefixo deverá ser Dir1/Dir2. Coloque esse valor entre aspas duplas.
-pattern string Padrão pelo qual arquivos de origem e blobs são escolhidos. Dá suporte a curingas. Por exemplo, "*.csv". Coloque esse valor entre aspas duplas.
-zipPattern string Expressão regular a ser usada na seleção dos arquivos em um arquivo ZIP a serem ingeridos. Todos os outros arquivos no arquivo são ignorados. Por exemplo, "*.csv". Coloque esse valor entre aspas duplas.
-format, -f string Formato dos dados de origem. Precisa ser um dos formatos compatíveis
-ingestionMappingPath, -mappingPath string Caminho para o arquivo local para o mapeamento de colunas de ingestão. Confira os mapeamentos de dados.
-ingestionMappingRef, -mappingRef string O nome de um mapeamento de coluna de ingestão criado anteriormente na tabela. Confira os mapeamentos de dados.
-creationTimePattern string Quando definido, é usado para extrair a propriedade CreationTime do caminho do arquivo ou do blob. Consulte Como ingerir dados usando CreationTime.
-ignoreFirstRow, -ignoreFirst bool Se definido, o primeiro registro de cada arquivo ou blob será ignorado. Por exemplo, se os dados de origem tiverem cabeçalhos.
-tag string As marcas a serem associadas aos dados ingeridos. Ocorrências múltiplas são permitidas
-dontWait bool Se definido como true, não aguarda a conclusão da ingestão. Útil ao ingerir grandes quantidades de arquivos e blobs.
-compactação, -cr double Dica de taxa de compactação. Útil para ajudar o Azure Data Explorer a avaliar o tamanho original dos dados ao ingerir arquivos e blobs compactados. Calculado como tamanho original dividido por tamanho compactado.
-limit, -l inteiro Se definido, limita a ingestão aos primeiros N arquivos.
-listOnly (somente lista), -list (lista) bool Se definido, exibe apenas os itens que seriam selecionados para ingestão.
-ingestTimeout inteiro Tempo limite em minutos para a conclusão de todas as operações de ingestão. Assume o padrão de 60.
-forceSync bool Se esse argumento for definido, ele forçará a ingestão síncrona. Assume o padrão de false.
-interactive bool Se definido como false, não solicitará confirmação de argumentos. Para fluxos autônomos e ambientes não interativos. O padrão é true.
-dataBatchSize inteiro Define o limite de tamanho total (MB, descompactado) de cada operação de ingestão.
-filesInBatch inteiro Define o limite de contagem de arquivos e blobs de cada operação de ingestão.
-devTracing, -trace string Se definido, os logs de diagnóstico são gravados em um diretório local (por padrão, RollingLogs no diretório atual ou podem ser modificados definindo o valor do comutador).

Funcionalidades específicas do blob do Azure

Quando você usa o LightIngest com blobs do Azure, ele utiliza determinadas propriedades de metadados de blob para aprimorar o processo de ingestão.

Propriedade de metadados Uso
rawSizeBytes, kustoUncompressedSizeBytes Se definido, LightIngest interpretará essas propriedades como o tamanho de dados descompactado
kustoCreationTime, kustoCreationTimeUtc LightIngest interpreta essas propriedades como timestamp UTC. Se definido, ele usará essas propriedades para substituir o tempo de criação no Kusto. Essa funcionalidade é útil para cenários de preenchimento retroativo

Exemplos de uso

Os exemplos a seguir pressupõem que você instalou binários LightIngest para seu sistema operacional. Se você instalou o LightIngest como uma ferramenta .NET, substitua LightIngestLightIngest nos exemplos.

Ingerir dados históricos com a propriedade CreationTime

Quando você carrega dados históricos de um sistema existente para o Azure Data Explorer, todos os registros obtêm a mesma data de ingestão. Para particionar seus dados por hora de criação em vez de tempo de ingestão, use o -creationTimePattern argumento. O argumento -creationTimePattern extrai a propriedade CreationTime do caminho do blob ou do arquivo. O padrão não precisa refletir todo o caminho do item, apenas a seção que inclui o carimbo de data/hora que você deseja usar.

Os valores de argumento precisam incluir:

  • Texto constante imediatamente antes do formato de carimbo de data/hora entre aspas simples (prefixo)
  • O formato de carimbo de data/hora, na notação DateTime padrão do .NET
  • Texto constante imediatamente após o carimbo de data/hora (sufixo).

Importante

Quando você especificar que o tempo de criação deve ser substituído, verifique se a sua Lookback propriedade na Extents merge policy efetiva da tabela de destino está alinhada com os valores em seus caminhos de arquivo ou blob.

Exemplos

  • Um nome de blob que contém o datetime da seguinte forma: historicalvalues19840101.parquet (o carimbo de data/hora é quatro dígitos para o ano, dois dígitos para o mês e dois dígitos para o dia do mês).

    O valor do argumento -creationTimePattern faz parte do nome do arquivo: "'historicalvalues'yyyyMMdd'.parquet'"

    LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -creationTimePattern:"'historicalvalues'yyyyMMdd'.parquet'"
 -pattern:"*.parquet" -format:parquet -limit:2 -cr:10.0 -dontWait:true

  • Para um URI de blob que se refere à estrutura hierárquica de pastas, como https://storageaccount/mycontainer/myfolder/2002/12/01/blobname.extension,

    O valor do argumento -creationTimePattern faz parte da estrutura de pastas: "'folder/'yyyy/MM/dd'/blob'"

      LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -creationTimePattern:"'mycontainer/myfolder/'yyyy/MM/dd'/'"
   -pattern:"*.csv.gz" -format:csv -limit:2 -ignoreFirst:true -cr:10.0 -dontWait:true

Ingerir blobs usando uma chave de conta de armazenamento ou um token SAS

  • Ingerir dez blobs na conta de armazenamento ACCOUNT especificada, na pasta DIR, no contêiner CONT e que correspondam ao padrão *.csv.gz
  • O destino é o banco de dados DB, a tabela TABLE e o mapeamento de ingestão MAPPING é criado previamente no destino
  • A ferramenta aguardará até que as operações de ingestão sejam concluídas
  • Observe as diferentes opções para especificar o banco de dados de destino e a chave de conta de armazenamento em comparação com o token SAS
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}"
  -prefix:"DIR"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -limit:10

LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True;Initial Catalog=DB"
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER}?{SAS token}"
  -prefix:"DIR"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -limit:10

Como ingerir todos os blobs de um contêiner, sem incluir as linhas de cabeçalho

  • Ingerir todos os blobs na conta de armazenamento ACCOUNT especificada, na pasta DIR1/DIR2, no contêiner CONT e que correspondam ao padrão *.csv.gz
  • O destino é o banco de dados DB, a tabela TABLE e o mapeamento de ingestão MAPPING é criado previamente no destino
  • Os blobs de origem contêm a linha de cabeçalho. Portanto, a ferramenta é instruída a remover o primeiro registro de cada blob
  • A ferramenta postará os dados para ingestão e não aguardará a conclusão das operações de ingestão
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER}?{SAS token}"
  -prefix:"DIR1/DIR2"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -ignoreFirstRow:true

Como ingerir todos os arquivos JSON de um caminho

  • Ingerir todos os arquivos no caminho PATH que correspondem ao padrão *.json
  • Defina o destino como banco de dados DB, tabela TABLEe defina o mapeamento de ingestão no arquivo local MAPPING_FILE_PATH
  • A ferramenta postará os dados para ingestão e não aguardará a conclusão das operações de ingestão
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"

Importar arquivos e gravar arquivos de rastreamento de diagnóstico

  • Ingerir todos os arquivos no caminho PATH que correspondem ao padrão *.json
  • Defina o destino como banco de dados DB, tabela TABLEe defina o mapeamento de ingestão no arquivo local MAPPING_FILE_PATH
  • A ferramenta postará os dados para ingestão e não aguardará a conclusão das operações de ingestão
  • Gravar arquivos de rastreamento de diagnóstico localmente na pasta LOGS_PATH
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"
  -trace:"LOGS_PATH"

Autenticar com identidade gerenciada

O LightIngest executa três ações que podem usar a identidade gerenciada para autenticação. O uso da identidade gerenciada em cada etapa não requer o uso da identidade gerenciada em outras etapas. Para cada ação, o argumento de linha de comando relacionado é fornecido.

  • Conectar ao cluster Kusto: para enfileirar a ingestão, a ferramenta usa uma cadeia de conexão. Use o argumento "-mi" para especificar uma identidade gerenciada instalada na VM cliente que tenha privilégios de ingestão no banco de dados de destino.

  • Conectar ao Armazenamento do Microsoft Azure para baixar blobs: use "-ingestmi" para especificar uma identidade gerenciada instalada no serviço Kusto que tenha privilégios de leitura no contêiner de armazenamento.

  • Conectar ao Armazenamento do Microsoft Azure para listar blobs de contêiner: use "-storageMi" para especificar uma identidade gerenciada instalada no serviço VM que tenha privilégios de leitura no contêiner de armazenamento. Se você usar esse método, mas não o anterior (conecte-se ao armazenamento do Azure para baixar blobs), a identidade gerenciada também deverá ter privilégios de leitura e um token será passado para o serviço Kusto a ser usado para a ingestão. Defina os três argumentos.

  • Last updated on