Usare LightIngest per inserire dati in Esplora dati di Azure

Articolo
07/16/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, da un contenitore di archiviazione BLOB di Azure o da 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 sui record in un secondo momento in base al momento in cui sono stati creati e non al momento in cui sono stati inseriti.

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ù leggero. Esistono due modi per ottenere LightIngest:
- Scaricare i file binari LightIngest 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 Esplora dati di Azure che gestirà l'inserimento. Racchiudere il stringa di connessione tra virgolette doppie e seguire la specifica stringa 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

Consigli sulle 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, è necessaria la dimensione dei dati non elaborati 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 del BLOB su dimensioni dei dati non compressi in byte.

Argomenti della riga di comando

Argomento	Type	Descrizione	Richiesto
	`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 della tabella Esplora dati di Azure di destinazione.	✔️
-sourcePath, -source	`string`	Percorso dei dati di origine, che può essere un percorso di 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 tra virgolette doppie. Per altre informazioni, vedere Stringa di connessione di archiviazione. Pass -sourcePath:; rappresenta per elencare gli elementi di archiviazione di Azure con autorizzazioni utente (autorizzazione richiesta dall'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, -ingestmi	`string`	ID client dell'identità gestita (assegnata dall'utente o assegnata dal sistema) installata nel servizio Kusto da scaricare dall'archiviazione. Usare "system" per l'identità assegnata dal sistema.
-connectToStorageWithManagedIdentity, -storageMi	`string`	ID client dell'identità gestita (assegnata dall'utente o assegnata dal sistema) installata sul lato client da elencare dall'archiviazione.
-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 di Microsoft Entra ID.
-prefisso	`string`	Quando i dati di origine da inserire risiedono nell'archivio BLOB, questo prefisso URL viene condiviso da tutti i BLOB, escluso il nome del contenitore. Ad esempio, se i dati sono in `MyContainer/Dir1/Dir2`, il prefisso deve essere `Dir1/Dir2`. È consigliabile racchiudere questo valore tra virgolette doppie.
-modello	`string`	Modello in base al quale vengono prelevati file/BLOB di origine. Supporta i caratteri jolly. Ad esempio: `"*.csv"`. È consigliabile racchiudere questo valore tra 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 tra virgolette doppie.
-format, -f	`string`	Formato dati di origine. Deve essere uno dei formati supportati
-ingestionMappingPath, -mappingPath	`string`	Percorso di un file locale per il mapping delle colonne di inserimento. Vedere Mapping dei dati.
-ingestionMappingRef, -mappingRef	`string`	Nome di un mapping di colonna di inserimento creato in precedenza nella tabella. Vedere Mapping dei dati.
-creationTimePattern	`string`	Se impostato, viene usato per estrarre la proprietà CreationTime dal file o dal percorso DEL BLOB. Vedere Come inserire dati con `CreationTime`.
-ignoreFirstRow, -ignoreFirst	`bool`	Se impostato, il primo record di ogni file/BLOB viene ignorato. Ad esempio, se i dati di origine hanno intestazioni.
-cartellino	`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.
-compression, -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 elaborati. Calcolata come dimensione originale divisa per dimensione compressa.
-limit, -l	integer	Se impostato, limita l'inserimento ai primi N file.
-listOnly, -list	`bool`	Se impostato, visualizza solo gli elementi selezionati per l'inserimento.
-ingestTimeout	integer	Timeout in minuti per il completamento di tutte le operazioni di inserimento. Il valore predefinito è `60`.
-forceSync	`bool`	Se impostato, forza l'inserimento sincrono. Il valore predefinito è `false`.
-interattivo	`bool`	Se impostato su `false`, non richiede la conferma degli argomenti. Per i flussi automatici e gli ambienti non interattivi. Il valore predefinito è `true`.
-dataBatchSize	integer	Imposta il limite di dimensioni totali (MB, non compresso) di ogni operazione di inserimento.
-filesInBatch	integer	Imposta il limite di conteggio di 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 switch).

Funzionalità specifiche del BLOB di Azure

Se usato con i BLOB di Azure, LightIngest usa determinate proprietà di 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 dell'ora di creazione in Kusto. Utile per scenari di backfilling

Esempi di utilizzo

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

Inserire dati cronologici con la proprietà CreationTime

Quando si caricano dati cronologici dal sistema esistente ad Azure Esplora dati, tutti i record ricevono la stessa data di inserimento. Per abilitare il partizionamento dei dati in base all'ora 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 DEL BLOB. Il modello non deve riflettere l'intero percorso dell'elemento, ma solo la sezione che racchiude il timestamp che si vuole usare.

I valori degli argomenti devono includere:

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

Importante

Quando si specifica che l'ora di creazione deve essere sottoposta a override, assicurarsi che la Lookback proprietà nei criteri di unione extent effettivi della tabella di destinazione sia allineata ai valori nei percorsi di file o BLOB.

Esempi

Nome blob che contiene 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'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

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

Il valore per -creationTimePattern l'argomento 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 trovare la corrispondenza con il modello *.csv.gz
La destinazione è il database DB, la tabella TABLEe il mapping di inserimento MAPPING viene precreato nella destinazione
Lo strumento attende il completamento delle operazioni di inserimento
Prendere nota delle 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 trovare la corrispondenza con il modello *.csv.gz
La destinazione è il database DB, la tabella TABLEe il mapping di inserimento MAPPING viene precreato nella destinazione
I BLOB di origine contengono una riga di intestazione, quindi viene richiesto allo strumento di eliminare il primo record di ogni BLOB
Lo strumento invia 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, che corrispondono al modello *.json
La destinazione è il database DB, la tabella TABLEe il mapping di inserimento è definito nel file locale MAPPING_FILE_PATH
Lo strumento invia 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, che corrispondono al modello *.json
La destinazione è il database DB, la tabella TABLEe il mapping di inserimento è definito nel file locale MAPPING_FILE_PATH
Lo strumento invia i dati per l'inserimento e non attende il completamento delle operazioni di inserimento
I file di traccia di diagnostica vengono scritti localmente 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"

Eseguire l'autenticazione con un'identità gestita

Esistono tre azioni eseguite da LightIngest che possono usare l'identità gestita per l'autenticazione. L'uso dell'identità gestita in ogni passaggio non richiede l'uso dell'identità gestita in altri passaggi. Per ogni azione, viene specificato l'argomento della riga di comando correlato.

Connettersi al cluster Kusto: per accodare l'inserimento, lo strumento usa un stringa di connessione. Usare l'argomento "-mi" per specificare un'identità gestita installata nella macchina virtuale client con privilegi di inserimento nel database di destinazione.
Connettersi a Archiviazione di Azure per scaricare i BLOB: usare "-ingestmi" per specificare un'identità gestita installata nel servizio Kusto con privilegi di lettura nel contenitore di archiviazione.
Connettersi a Archiviazione di Azure per elencare i BLOB del contenitore: usare l'argomento "-storageMi" per specificare un'identità gestita installata nella macchina virtuale client con privilegi di elenco nel contenitore di archiviazione. Se si usa questo metodo ma non quello precedente (connettersi all'archiviazione di Azure per scaricare i BLOB), l'identità gestita deve avere privilegi di lettura e un token verrà passato al servizio Kusto da usare per l'inserimento. È quindi consigliabile impostare tutti e tre gli argomenti.

Condividi tramite