Utilizar o LightIngest para ingerir dados no Azure Data Explorer

Artigo
01/16/2024

LightIngest é um utilitário de linha de comandos 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 contentor de armazenamento de blobs do Azure ou de um registo do Amazon S3.

LightIngest é mais útil quando quer ingerir uma grande quantidade de dados, porque não existe uma restrição de tempo na duração da ingestão. Também é útil quando pretende consultar registos posteriormente de acordo com a hora em que foram criados e não a hora em que foram ingeridos.

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

Nota

A ingestão suporta um tamanho máximo de ficheiros de 6 GB. A recomendação é ingerir ficheiros entre 100 MB e 1 GB.

Pré-requisitos

LightIngest. Existem duas formas de obter o LightIngest:
- Transfira os binários LightIngest para o seu sistema operativo. Certifique-se de que deszipe os binários após a transferência.
- Instale o LightIngest como uma ferramenta .NET. Este método requer que tenha a versão 6.0 ou superior do SDK .NET instalada no seu computador. Em seguida, execute o seguinte comando:
```
dotnet tool install -g Microsoft.Azure.Kusto.LightIngest
```

Executar LightIngest

Para executar LightIngest:

Na linha de comandos, introduza LightIngest seguido do argumento de linha de comandos relevante.

Dica

Para obter uma lista de argumentos de linha de comandos suportados, introduza LightIngest /help.

Introduza ingest- seguido do cadeia de ligação para o cluster de Data Explorer do Azure que irá gerir a ingestão. Coloque o cadeia de ligação entre aspas e siga a especificação das cadeias de ligaçã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 gerir melhor a carga de ingestão e recuperar de erros transitórios, utilize o ponto final de ingestão em https://ingest-{yourClusterNameAndRegion}.kusto.windows.net.
Para um desempenho de ingestão ideal, o tamanho de dados não processados é necessário para que o LightIngest possa estimar o tamanho descomprimido dos ficheiros locais. No entanto, o LightIngest poderá não conseguir estimar corretamente o tamanho bruto dos blobs comprimidos sem os transferir primeiro. Por conseguinte, ao ingerir blobs comprimidos, defina a rawSizeBytes propriedade nos metadados do blob para descomprimir o tamanho dos dados em bytes.

Argumentos da linha de comandos

Argumento	Tipo	Descrição	Obrigatório
	`string`	Um Kusto cadeia de ligação especificar o ponto final do Kusto que processa a ingestão. Este valor deve estar entre aspas duplas.	✔️
-database, -db	`string`	O nome da base de dados Data Explorer do Azure de destino.
-table	`string`	O Azure de destino Data Explorer nome da tabela.	✔️
-sourcePath, -source	`string`	A localização dos dados de origem, que pode ser um caminho de ficheiro local, o URI de raiz de um contentor de blobs do Azure ou o URI de um registo Amazon S3. Se os dados estiverem armazenados nos blobs do Azure, o URI tem de incluir a chave da conta de armazenamento ou a Assinatura de Acesso Partilhado (SAS). Se os dados estiverem num registo S3, o URI tem de incluir a chave de credencial. Recomendamos que coloque este valor entre aspas duplas. Para obter mais informações, veja Cadeias de ligação de armazenamento. Pass -sourcePath:; representar para listar itens de armazenamento do Azure com permissões de utilizador (autorização de pedido de utilizador).	✔️
-managedIdentity, -mi	`string`	ID de cliente da identidade gerida (atribuída pelo utilizador ou atribuída pelo sistema) a utilizar para a ligação. Utilize "system" para a identidade atribuída pelo sistema.
-ingestWithManagedIdentity, -imgestmi	`string`	ID de cliente da identidade gerida (atribuída pelo utilizador ou atribuída pelo sistema) a utilizar para a ligação. Utilize "system" para a identidade atribuída pelo sistema.
-connectToStorageWithUserAuth, -storageUserAuth	`string`	Autentique-se no serviço de armazenamento da origem de dados com credenciais de utilizador. As opções para este valor são `PROMPT` ou `DEVICE_CODE`.
-connectToStorageLoginUri, -storageLoginUri	`string`	Se `-connectToStorageWithUserAuth` estiver definido, pode fornecer opcionalmente um URI de início de sessão Microsoft Entra ID.
-prefixo	`string`	Quando os dados de origem a ingerir residem no armazenamento de blobs, este prefixo de URL é partilhado por todos os blobs, excluindo o nome do contentor. Por exemplo, se os dados estiverem em `MyContainer/Dir1/Dir2`, o prefixo deve ser `Dir1/Dir2`. Recomendamos que coloque este valor entre aspas duplas.
-pattern	`string`	Padrão através do qual os ficheiros/blobs de origem são escolhidos. Suporta carateres universais. Por exemplo, `"*.csv"`. Recomendamos que coloque este valor entre aspas duplas.
-zipPattern	`string`	Expressão regular a utilizar ao selecionar os ficheiros num arquivo ZIP a ingerir. Todos os outros ficheiros no arquivo serão ignorados. Por exemplo, `"*.csv"`. Recomendamos que coloque este valor entre aspas duplas.
-format, -f	`string`	Formato de dados de origem. Tem de ser um dos formatos suportados
-ingestionMappingPath, -mappingPath	`string`	Um caminho para um ficheiro local para mapeamento de colunas de ingestão. Veja mapeamentos de dados.
-ingestionMappingRef, -mappingRef	`string`	O nome de um mapeamento de colunas de ingestão que foi criado anteriormente na tabela. Veja mapeamentos de dados.
-creationTimePattern	`string`	Quando definido, é utilizado para extrair a propriedade CreationTime do caminho do ficheiro ou do blob. Veja Como ingerir dados com `CreationTime`.
-ignoreFirstRow, -ignoreFirst	`bool`	Se estiver definido, o primeiro registo de cada ficheiro/blob é ignorado. Por exemplo, se a origem de dados tiver cabeçalhos.
-tag	`string`	Etiquetas para associar aos dados ingeridos. São permitidas várias ocorrências
-dontWait	`bool`	Se estiver definido como `true`, não aguarda a conclusão da ingestão. Útil ao ingerir grandes quantidades de ficheiros/blobs.
-compressão, -cr	double	Sugestão de rácio de compressão. Útil ao ingerir ficheiros/blobs comprimidos para ajudar o Azure Data Explorer avaliar o tamanho dos dados não processados. Calculado como tamanho original dividido por tamanho comprimido.
-limit, -l	número inteiro	Se estiver definido, limita a ingestão aos primeiros ficheiros N .
-listOnly, -list	`bool`	Se estiver definido, apenas apresenta 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. A predefinição é `60`.
-forceSync	`bool`	Se estiver definido, força a ingestão síncrona. A predefinição é `false`.
-interativo	`bool`	Se definido como `false`, não pede confirmação de argumentos. Para fluxos autónomos e ambientes não interativos. A predefinição é `true`.
-dataBatchSize	número inteiro	Define o limite de tamanho total (MB, descomprimido) de cada operação de ingestão.
-filesInBatch	número inteiro	Define o limite de contagem de ficheiros/blobs de cada operação de ingestão.
-devTracing, -trace	`string`	Se estiver definido, os registos de diagnóstico são escritos num diretório local (por predefinição, `RollingLogs` no diretório atual ou podem ser modificados ao definir o valor do comutador).

Capacidades específicas de blobs do Azure

Quando utilizado com blobs do Azure, LightIngest utiliza determinadas propriedades de metadados de blobs para aumentar o processo de ingestão.

Propriedade metadados	Utilização
`rawSizeBytes`, `kustoUncompressedSizeBytes`	Se estiver definido, será interpretado como o tamanho dos dados descomprimidos
`kustoCreationTime`, `kustoCreationTimeUtc`	Interpretado como carimbo de data/hora UTC. Se estiver definido, será utilizado para substituir a hora de criação no Kusto. Útil para cenários de backfilling

Exemplos de utilização

Os exemplos seguintes partem do princípio de que instalou binários LightIngest para o seu sistema operativo. Se tiver instalado o LightIngest como uma ferramenta .NET, substitua pelos LightIngestLightIngest exemplos.

Ingerir dados históricos com a propriedade CreationTime

Quando carrega dados históricos do sistema existente para o Azure Data Explorer, todos os registos recebem a mesma data de ingestão. Para ativar a criação de partições dos seus dados por hora de criação e não por tempo de ingestão, pode utilizar o -creationTimePattern argumento . O -creationTimePattern argumento extrai a CreationTime propriedade do caminho do ficheiro ou do blob. O padrão não precisa de refletir todo o caminho do item, apenas a secção que inclui o carimbo de data/hora que pretende utilizar.

Os valores do argumento têm de incluir:

Texto constante imediatamente antes do formato de carimbo de data/hora, entre plicas (prefixo)
O formato de carimbo de data/hora, na notação dateTime do .NET padrão
Texto constante imediatamente a seguir ao carimbo de data/hora (sufixo).

Importante

Ao especificar que a hora de criação deve ser substituída, certifique-se de que a Lookback propriedade na política de intercalação de Extensões efetiva da tabela de destino está alinhada com os valores nos caminhos do ficheiro ou do blob.

Exemplos

Um nome de blob que contém o datetime da seguinte forma: historicalvalues19840101.parquet (o carimbo de data/hora é de 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 -creationTimePattern argumento faz parte do nome de ficheiro: "'historicvalues'yyyMMdd'.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 de pastas hierárquica, como https://storageaccount/mycontainer/myfolder/2002/12/01/blobname.extension,

O valor do -creationTimePattern argumento faz parte da estrutura de pastas: "'pasta/'aaaa/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 com uma chave de conta de armazenamento ou um token de SAS

Ingerir 10 blobs na conta ACCOUNTde armazenamento especificada , na pasta DIR, no contentor CONTe corresponder ao padrão *.csv.gz
O destino é a base 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 terminem
Tenha em atenção as diferentes opções para especificar a base de dados de destino e a chave da conta de armazenamento vs. token de 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, sem incluir linhas de cabeçalho

Ingerir todos os blobs na conta ACCOUNTde armazenamento especificada , na pasta DIR1/DIR2, no contentor CONTe corresponder ao padrão *.csv.gz
O destino é a base 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, pelo que a ferramenta tem instruções para remover o primeiro registo de cada blob
A ferramenta publica os dados para ingestão e não aguarda 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 ficheiros JSON a partir de um caminho

Ingerir todos os ficheiros no caminho PATH, correspondendo ao padrão *.json
O destino é a base de dados DB, a tabela TABLEe o mapeamento de ingestão é definido no ficheiro local MAPPING_FILE_PATH
A ferramenta publica os dados para ingestão e não aguarda 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 ficheiros e escrever ficheiros de rastreio de diagnóstico

Ingerir todos os ficheiros no caminho PATH, correspondendo ao padrão *.json
O destino é a base de dados DB, a tabela TABLEe o mapeamento de ingestão é definido no ficheiro local MAPPING_FILE_PATH
A ferramenta publica os dados para ingestão e não aguarda que as operações de ingestão sejam concluídas
Os ficheiros de rastreio de diagnóstico são escritos 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"

Partilhar via