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 blob do Azure ou um bucket do Amazon S3.

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

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

Pré-requisitos

• LightIngest Obtenha o LightIngest de duas maneiras:

  • Faça o download dos binários LightIngest para o seu sistema operacional. Certifique-se de descompactar os binários após o download.

  • Instale o LightIngest como uma ferramenta .NET. Esse método requer que você tenha o .NET SDK versão 6.0 ou superior instalado em sua máquina. Em seguida, execute o seguinte comando:

    dotnet tool install -g Microsoft.Azure.Kusto.LightIngest
    

Executar LightIngest

Para executar LightIngest:

1. No prompt de comando, digite LightIngest seguido pelo argumento de linha de comando relevante.

   Sugestão

   Para obter uma lista de argumentos de linha de comando suportados, digite LightIngest /help.

2. Enter ingest- seguido da 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 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 de desempenho

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

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

Argumentos de linha de comando

Recursos específicos de blob do Azure

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

Exemplos de utilização

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 LightIngest por LightIngest nos exemplos.

Ingerir dados históricos com a propriedade CreationTime

Quando você carrega dados históricos de um sistema existente no Azure Data Explorer, todos os registros obtêm a mesma data de ingestão. Para particionar seus dados por tempo de criação em vez de tempo de ingestão, use o -creationTimePattern argumento. O -creationTimePattern argumento extrai a CreationTime propriedade do caminho de um ficheiro ou blob. 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 devem incluir:

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

Examples

• Um nome de blob que contém a data e hora da seguinte forma: historicalvalues19840101.parquet (a data é composta por 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 para -creationTimePattern argumento 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 para -creationTimePattern argumento 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 10 blobs na conta ACCOUNT, de armazenamento especificada, na pasta DIR, no contentor CONT e que correspondem ao padrão *.csv.gz
• O destino é o banco de dados DB, a tabela TABLEe o mapeamento MAPPING de ingestão é pré-criado no destino
• A ferramenta aguarda 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 da conta de armazenamento versus 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

Ingerir todos os blobs num contentor, não incluindo linhas de topo

• Ingerir todos os blobs na conta ACCOUNT de armazenamento especificada, na pasta DIR1/DIR2, no container CONT e correspondendo ao padrão *.csv.gz
• O destino é o banco de dados DB, a tabela TABLEe o mapeamento MAPPING de ingestão é pré-criado no destino
• Os blobs de origem contêm linha de cabeçalho, portanto, a ferramenta é instruída a soltar o primeiro registro de cada blob
• A ferramenta publica os dados para ingestão e não espera que as operações de ingestão sejam concluídas

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

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 publica os dados para ingestão e não espera que as operações de ingestão sejam concluídas

LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"

Ingerir 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 publica os dados para ingestão e não espera que as operações de ingestão sejam concluídas
• Gravar ficheiros de rastreio 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 gerida

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

• Conectar-se 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-se ao Armazenamento do 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-se ao Armazenamento do Azure para listar blobs de contêiner: use o argumento "-storageMi" para especificar uma identidade gerenciada instalada na VM cliente que tenha privilégios de lista no contêiner de armazenamento. Se você usar esse método, mas não o anterior (conectar-se ao armazenamento do Azure para baixar blobs), a identidade gerenciada também deve ter privilégios de leitura e um token é passado para o serviço Kusto para ser usado para a ingestão. Defina os três argumentos.