Usar o LightIngest para ingerir dados no Azure Data Explorer

Artigo
07/18/2024

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

LightIngest. Há duas maneiras de obter o LightIngest:
- baixar binários LightIngest para seu sistema operacional. Descompacte os binários após o download.
- Instalar o LightIngest como uma ferramenta .NET. Esse método requer que você tenha o SDK do .NET versão 6.0 ou superior instalado em seu computador. Em seguida, execute o seguinte comando:
```
dotnet tool install -g Microsoft.Azure.Kusto.LightIngest
```

Executar o LightIngest

Para executar o LightIngest:

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.

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	Type	Descrição	Obrigatório
	`string`	Cadeia de conexão do Kusto especificando o ponto de extremidade do Kusto que processará a ingestão. Esse valor deve ser colocado entre aspas duplas.	✔️
-database, -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. É recomendável colocar 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).	✔️
-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 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 estar 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.
-connectToStorageWithUserAuth, -storageUserAuth	`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 logon da ID do Microsoft Entra.
-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`	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/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 na ingestão de grandes volumes 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	Número 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`.
-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	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/blob 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 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 LightIngest por LightIngest 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 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 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 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"

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 postará os dados para ingestão e não aguardará a conclusão das operações de ingestão
Os arquivos de rastreamento de diagnóstico serã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"

Autenticar com identidade gerenciada

Há três ações executadas pelo LightIngest 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ê estiver usando 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. Portanto, é recomendável definir todos os três argumentos.

Compartilhar via