Usar o LightIngest para ingerir dados no Azure Data Explorer

  • Artigo

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, de um contêiner de armazenamento de blobs do Azure ou de 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

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 da cadeia de conexão com o cluster do Azure Data Explorer que gerenciará 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 o desempenho ideal de ingestão, o tamanho dos dados brutos é necessário para que o LightIngest possa estimar o tamanho descompactado 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 Um kusto cadeia de conexão especificando o ponto de extremidade kusto que manipula a ingestão. Esse valor deve ser colocado entre aspas duplas. ✔️
-database, -db string O nome do banco de dados Data Explorer do Azure de destino.
-table string O nome da tabela de Data Explorer do Azure de destino. ✔️
-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. É recomendável colocar esse valor entre aspas duplas. Para obter mais informações, consulte Cadeias de conexão de armazenamento. Pass -sourcePath:; represente para listar itens de armazenamento do Azure com permissões de usuário (autorização de prompt do usuário). ✔️
-managedIdentity, -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 identidade atribuída pelo sistema.
-ingestWithManagedIdentity, -imgestmi 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 identidade atribuída pelo sistema.
-connectToStorageWithUserAuth, -storageUserAuth string Autentique-se no serviço de armazenamento de fonte de dados com credenciais de usuário. As opções para esse valor são PROMPT ou DEVICE_CODE.
-connectToStorageLoginUri, -storageLoginUri string Se -connectToStorageWithUserAuth estiver definido, você poderá, opcionalmente, fornecer um URI de logon 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. É recomendável colocar esse valor entre aspas duplas.
-pattern string Padrão pelo qual os blobs/os arquivos de origem são selecionados. Dá suporte a curingas. Por exemplo, "*.csv". É recomendável colocar 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 serão ignorados. Por exemplo, "*.csv". É recomendável colocar esse valor entre aspas duplas.
-format, -f string Formato dos dados de origem. Precisa ser um dos formatos compatíveis
-ingestionMappingPath, -mappingPath string Um caminho para um arquivo local para mapeamento de coluna de ingestão. Confira os mapeamentos de dados.
-ingestionMappingRef, -mappingRef string O nome de um mapeamento de coluna de ingestão que foi 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. Confira Como ingerir dados usando CreationTime.
-ignoreFirstRow, -ignoreFirst bool Se definido, o primeiro registro de cada arquivo/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/blobs.
-compression, -cr double Dica de taxa de compactação. Útil na ingestão de arquivos/blobs compactados para ajudar o Azure Data Explorer a avaliar o tamanho dos dados brutos. Calculado como tamanho original dividido por tamanho compactado.
-limit, -l inteiro Se definido, limita a ingestão aos primeiros N arquivos.
-listOnly, -list bool Se definido, exibe apenas os itens que teriam sido selecionados para ingestão.
-ingestTimeout Número 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.
-Interativo bool Se definido falsecomo , não solicitará a confirmação de argumentos. Para fluxos autônomos e ambientes não interativos. O padrão é true.
-dataBatchSize Número inteiro Define o limite de tamanho total (MB, descompactado) de cada operação de ingestão.
-filesInBatch Número inteiro Define o limite de contagem de arquivos/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 da opção).

Funcionalidades específicas do blob do Azure

Quando usado com blobs do Azure, o LightIngest usa determinadas propriedades de metadados de blob para aumentar o processo de ingestão.

Propriedade de metadados Uso
rawSizeBytes, kustoUncompressedSizeBytes Se esse argumento for definido, isso será interpretado como o tamanho de dados descompactados
kustoCreationTime, kustoCreationTimeUtc Interpretado como um carimbo de data/hora UTC. Se esse argumento for definido, ele será usado para substituir a hora de criação no Kusto. Útil para cenários de provisionamento

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

Ingerir dados históricos com a propriedade CreationTime

Quando você carrega dados históricos do sistema existente para o Azure Data Explorer, todos os registros recebem a mesma data de ingestão. Para habilitar o particionamento dos dados pela hora de criação e não pela hora de ingestão, use o argumento -creationTimePattern. 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 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

Ao especificar que a hora de criação deve ser substituída, verifique se a propriedade Lookback na Política de mesclagem de extensões efetiva da tabela de destino está alinhada com os valores nos caminhos de arquivo ou de 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

Como 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 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 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 posta os dados para ingestão e não aguarda 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 correspondam ao padrão *.json
  • O destino é o banco de dados DB, a tabela TABLE e o mapeamento de ingestão é definido no arquivo local MAPPING_FILE_PATH
  • A ferramenta posta os dados para ingestão e não aguarda 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"

Como ingerir arquivos e escrever arquivos de rastreamento de diagnóstico

  • Ingerir todos os arquivos no caminho PATH que correspondam ao padrão *.json
  • O destino é o banco de dados DB, a tabela TABLE e o mapeamento de ingestão é definido no arquivo local MAPPING_FILE_PATH
  • A ferramenta posta os dados para ingestão e não aguarda a conclusão das operações de ingestão
  • Os arquivos de rastreamento de diagnóstico são gravados 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"