Utilizar o LightIngest para ingerir dados no Azure Data Explorer

  • Artigo

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

Executar LightIngest

Para executar LightIngest:

  1. 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.

  2. 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"