Usare LightIngest per inserire dati in Esplora dati di Azure

Articolo
01/23/2024

LightIngest è un'utilità della riga di comando per l'inserimento di dati ad hoc in Azure Esplora dati. L'utilità può eseguire il pull dei dati di origine da una cartella locale, un contenitore di archiviazione BLOB di Azure o un bucket Amazon S3.

LightIngest è più utile quando si vuole inserire una grande quantità di dati, perché non esiste alcun vincolo di tempo per la durata dell'inserimento. È utile anche quando si desidera eseguire query in un secondo momento in base all'ora in cui sono state create e non al momento in cui sono state inserite.

Per un esempio di come generare automaticamente un comando LightIngest, vedere inserire dati cronologici.

Nota

L'inserimento supporta file di dimensione massima di 6 GB. È consigliabile inserire file di dimensione compresa tra 100 MB e 1 GB.

Prerequisiti

Più chiaro. Esistono due modi per ottenere la luce più chiara:
- Scaricare i file binari più leggeri per il sistema operativo. Assicurarsi di decomprimere i file binari dopo il download.
- Installare LightIngest come strumento .NET. Questo metodo richiede che nel computer sia installato .NET SDK versione 6.0 o successiva. Eseguire poi il comando seguente:
```
dotnet tool install -g Microsoft.Azure.Kusto.LightIngest
```

Eseguire lightingest

Per eseguire LightIngest:

Al prompt dei comandi immettere LightIngest seguito dall'argomento della riga di comando pertinente.

Suggerimento

Per un elenco di argomenti della riga di comando supportati, immettere LightIngest /help.

Immettere ingest- seguito dal stringa di connessione al cluster di Azure Esplora dati che gestirà l'inserimento. Racchiudere la stringa di connessione in virgolette doppie e seguire la specifica delle stringhe di connessione Kusto.

Ad esempio:

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

Raccomandazioni per le prestazioni

Per gestire al meglio il carico di inserimento e il ripristino da errori temporanei, usare l'endpoint di inserimento in https://ingest-{yourClusterNameAndRegion}.kusto.windows.net.
Per prestazioni ottimali di inserimento, le dimensioni dei dati non elaborate sono necessarie in modo che LightIngest possa stimare le dimensioni non compresse dei file locali. Tuttavia, LightIngest potrebbe non essere in grado di stimare correttamente le dimensioni non elaborate dei BLOB compressi senza prima scaricarli. Pertanto, quando si inseriscono BLOB compressi, impostare la rawSizeBytes proprietà sui metadati BLOB su dimensioni dei dati non compresse in byte.

Argomenti della riga di comando

Argomento	Tipo	Descrizione	Obbligatoria
	`string`	Un stringa di connessione Kusto che specifica l'endpoint Kusto che gestisce l'inserimento. Questo valore deve essere racchiuso tra virgolette doppie.	✔️
-database, -db	`string`	Nome del database di Azure Esplora dati di destinazione.
-tavolo	`string`	Nome tabella di Azure di destinazione Esplora dati.	✔️
-sourcePath, -source	`string`	Percorso dei dati di origine, che può essere un percorso file locale, l'URI radice di un contenitore BLOB di Azure o l'URI di un bucket Amazon S3. Se i dati vengono archiviati in BLOB di Azure, l'URI deve includere la chiave dell'account di archiviazione o la firma di accesso condiviso. Se i dati si trovano in un bucket S3, l'URI deve includere la chiave delle credenziali. È consigliabile racchiudere questo valore in virgolette doppie. Per altre informazioni, vedere Stringhe di connessione di archiviazione. Pass -sourcePath:; rappresentazione per elencare gli elementi di archiviazione di Azure con autorizzazioni utente (autorizzazione richiesta utente).	✔️
-managedIdentity, -mi	`string`	ID client dell'identità gestita (assegnata dall'utente o assegnata dal sistema) da usare per la connessione. Usare "system" per l'identità assegnata dal sistema.
-ingestWithManagedIdentity, -imgestmi	`string`	ID client dell'identità gestita (assegnata dall'utente o assegnata dal sistema) da usare per la connessione. Usare "system" per l'identità assegnata dal sistema.
-connectToStorageWithUserAuth, -storageUserAuth	`string`	Eseguire l'autenticazione al servizio di archiviazione dell'origine dati con le credenziali utente. Le opzioni per questo valore sono `PROMPT` o `DEVICE_CODE`.
-connectToStorageLoginUri, -storageLoginUri	`string`	Se `-connectToStorageWithUserAuth` è impostato, è possibile specificare facoltativamente un URI di accesso Microsoft Entra ID.
-Prefisso	`string`	Quando i dati di origine da inserire si trovano nell'archiviazione BLOB, questo prefisso URL viene condiviso da tutti i BLOB, escluso il nome del contenitore. Ad esempio, se i dati si trovano in `MyContainer/Dir1/Dir2`, il prefisso deve essere `Dir1/Dir2`. È consigliabile racchiudere questo valore in virgolette doppie.
-Modello	`string`	Modello in base al quale vengono selezionati file/BLOB di origine. Supporta caratteri jolly. Ad esempio: `"*.csv"`. È consigliabile racchiudere questo valore in virgolette doppie.
-zipPattern	`string`	Espressione regolare da usare quando si selezionano i file in un archivio ZIP da inserire. Tutti gli altri file nell'archivio verranno ignorati. Ad esempio: `"*.csv"`. È consigliabile racchiudere questo valore in virgolette doppie.
-format, -f	`string`	Formato dati di origine. Deve essere uno dei formati supportati
-inserimentoMappingPath, -mappingPath	`string`	Percorso di un file locale per il mapping di colonne di inserimento. Vedere mapping dei dati.
-inserimentoMappingRef, -mappingRef	`string`	Nome di un mapping di colonna di inserimento creato in precedenza nella tabella. Vedere mapping dei dati.
-creationTimePattern	`string`	Quando impostato, viene usato per estrarre la proprietà CreationTime dal file o dal percorso BLOB. Vedere Come inserire i dati usando `CreationTime`.
-ignoreFirstRow, -ignoreFirst	`bool`	Se impostato, il primo record di ogni file/BLOB viene ignorato. Ad esempio, se i dati di origine hanno intestazioni.
-tag	`string`	Tag da associare ai dati inseriti. Sono consentite più occorrenze
-dontWait	`bool`	Se impostato su `true`, non attende il completamento dell'inserimento. Utile quando si inseriscono grandi quantità di file/BLOB.
-compressione, -cr	double	Hint per il rapporto di compressione. Utile quando si inseriscono file/BLOB compressi per consentire ad Azure Esplora dati valutare le dimensioni dei dati non elaborate. Calcolata come dimensione originale divisa in base alle dimensioni compresse.
-limit, -l	numero intero	Se impostato, limita l'inserimento ai primi file N .
-listOnly, -list	`bool`	Se impostato, visualizza solo gli elementi selezionati per l'inserimento.
-ingestTimeout	numero intero	Timeout in minuti per tutto il completamento delle operazioni di inserimento. Il valore predefinito è `60`.
-forceSync	`bool`	Se impostato, forza l'inserimento sincrono. Il valore predefinito è `false`.
-Interattiva	`bool`	Se impostato su `false`, non richiede la conferma degli argomenti. Per i flussi non automatici e gli ambienti non interattivi. Il valore predefinito è `true`.
-dataBatchSize	numero intero	Imposta il limite totale di dimensioni (MB, non compresso) di ogni operazione di inserimento.
-filesInBatch	numero intero	Imposta il limite di conteggio file/BLOB di ogni operazione di inserimento.
-devTracing, -trace	`string`	Se impostato, i log di diagnostica vengono scritti in una directory locale (per impostazione predefinita, `RollingLogs` nella directory corrente o possono essere modificati impostando il valore del commutatore).

Funzionalità specifiche del BLOB di Azure

Se usato con BLOB di Azure, LightIngest usa determinate proprietà dei metadati BLOB per aumentare il processo di inserimento.

Proprietà Metadata	Utilizzo
`rawSizeBytes`, `kustoUncompressedSizeBytes`	Se impostato, verrà interpretato come dimensione dei dati non compressi
`kustoCreationTime`, `kustoCreationTimeUtc`	Interpretato come timestamp UTC. Se impostato, verrà usato per eseguire l'override del tempo di creazione in Kusto. Utile per gli scenari di riempimento di backfilling

Esempi di utilizzo

Gli esempi seguenti presuppongono che siano stati installati file binari lightingest per il sistema operativo. Se è stato installato LightIngest come strumento .NET, sostituire LightIngest con LightIngest negli esempi.

Inserire dati cronologici con la proprietà CreationTime

Quando si caricano dati cronologici dal sistema esistente in Azure Esplora dati, tutti i record ricevono la stessa data di inserimento. Per abilitare il partizionamento dei dati in base al tempo di creazione e non al tempo di inserimento, è possibile usare l'argomento -creationTimePattern . L'argomento -creationTimePattern estrae la CreationTime proprietà dal file o dal percorso BLOB. Il modello non deve riflettere l'intero percorso dell'elemento, solo la sezione che racchiude il timestamp da usare.

I valori degli argomenti devono includere:

Testo costante immediatamente precedente al formato timestamp, racchiuso tra virgolette singole (prefisso)
Formato timestamp, nella notazione .NET DateTime standard
Testo costante immediatamente dopo il timestamp (suffisso).

Importante

Quando si specifica che il tempo di creazione deve essere sottoposto a override, assicurarsi che la Lookback proprietà nel criterio di unione Extents della tabella di destinazione sia allineata ai valori nei percorsi di file o BLOB.

esempi

Nome BLOB che contiene il valore datetime come indicato di seguito: historicalvalues19840101.parquet (il timestamp è quattro cifre per l'anno, due cifre per il mese e due cifre per il giorno del mese),

Il valore per -creationTimePattern l'argomento fa parte del nome file: "'historicalvalues'yyMMdd'.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

Per un URI BLOB che fa riferimento alla struttura gerarchica di cartelle, ad esempio https://storageaccount/mycontainer/myfolder/2002/12/01/blobname.extension,

Il valore dell'argomento -creationTimePattern fa parte della struttura di cartelle: "'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

Inserimento di BLOB tramite una chiave dell'account di archiviazione o un token di firma di accesso condiviso

Inserire 10 BLOB nell'account ACCOUNTdi archiviazione specificato, nella cartella DIR, nel contenitore CONTe nella corrispondenza del modello *.csv.gz
La destinazione è database DB, tabella TABLEe il mapping MAPPING di inserimento viene precreato nella destinazione
Lo strumento attende fino al completamento delle operazioni di inserimento
Si notino le diverse opzioni per specificare il database di destinazione e la chiave dell'account di archiviazione e il token di firma di accesso condiviso

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

Inserimento di tutti i BLOB in un contenitore, non incluse le righe di intestazione

Inserire tutti i BLOB nell'account ACCOUNTdi archiviazione specificato, nella cartella DIR1/DIR2, nel contenitore CONTe nella corrispondenza del modello *.csv.gz
La destinazione è database DB, tabella TABLEe il mapping MAPPING di inserimento viene precreato nella destinazione
I BLOB di origine contengono una riga di intestazione, quindi lo strumento viene incaricato di eliminare il primo record di ogni BLOB
Lo strumento pubblica i dati per l'inserimento e non attende il completamento delle operazioni di inserimento

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

Inserimento di tutti i file JSON da un percorso

Inserire tutti i file nel percorso PATH, corrispondente al modello *.json
La destinazione è database DB, tabella TABLEe il mapping di inserimento viene definito nel file locale MAPPING_FILE_PATH
Lo strumento pubblica i dati per l'inserimento e non attende il completamento delle operazioni di inserimento

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

Inserimento di file e scrittura di file di traccia di diagnostica

Inserire tutti i file nel percorso PATH, corrispondente al modello *.json
La destinazione è database DB, tabella TABLEe il mapping di inserimento viene definito nel file locale MAPPING_FILE_PATH
Lo strumento pubblica i dati per l'inserimento e non attende il completamento delle operazioni di inserimento
I file di traccia di diagnostica vengono scritti in locale nella cartella 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"