Esportare i dati nell'archiviazione cloud

Articolo
11/23/2024

Si applica a: ✅Microsoft Fabric✅Azure Esplora dati

Esegue una query e scrive il primo set di risultati in un archivio cloud esterno, specificato da un stringa di connessione di archiviazione.

Autorizzazioni

Per eseguire questo comando, è necessario disporre almeno delle autorizzazioni del Visualizzatore di database.

Sintassi

.export[] [compressedasync] to OutputDataFormat ( StorageConnectionString [, ...] ) [with ( PropertyName = PropertyValue [, ...] ] <| )Quesito

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome	Digita	Obbligatorio	Descrizione
`async`	`string`		Se specificato, il comando viene eseguito in modalità asincrona. Vedere la modalità asincrona.
`compressed`	`string`		Se specificato, gli artefatti di archiviazione di output vengono compressi come `.gz` file. Vedere la `compressionType` proprietà supportata per comprimere i file Parquet come snappy.
OutputDataFormat	`string`	✔️	Indica il formato dei dati degli artefatti di archiviazione scritti dal comando . I valori supportati sono: `csv`, `tsv`, `json`e `parquet`.
StorageConnectionString	`string`		Uno o più stringa di connessione di archiviazione che indicano la risorsa di archiviazione in cui scrivere i dati. È possibile specificare più stringa di connessione di archiviazione per le scritture scalabili. Ogni stringa di connessione deve indicare le credenziali da usare durante la scrittura nella risorsa di archiviazione. Ad esempio, quando si scrive in Archiviazione BLOB di Azure, le credenziali possono essere la chiave dell'account di archiviazione o una chiave di accesso condiviso con le autorizzazioni per leggere, scrivere ed elencare i BLOB.
PropertyName, PropertyValue	`string`		Elenco delimitato da virgole di coppie di proprietà chiave-valore. Vedere le proprietà supportate.

Nota

È consigliabile esportare i dati nella risorsa di archiviazione che si trova nella stessa area del database stesso. Sono inclusi i dati esportati in modo che possano essere trasferiti a un altro servizio cloud in altre aree. Le scritture devono essere eseguite localmente, mentre le letture possono verificarsi in remoto.

Proprietà supportate

Proprietà	Type	Descrizione
`includeHeaders`	`string`	Per `csv`/`tsv` l'output, controlla la generazione di intestazioni di colonna. Può essere una delle (impostazione predefinita; nessuna riga di `none` intestazione generata), `all` (generare una riga di intestazione in ogni artefatto di archiviazione) o `firstFile` (generare una riga di intestazione solo nel primo artefatto di archiviazione).
`fileExtension`	`string`	Indica la parte "estensione" dell'artefatto di archiviazione (ad esempio, `.csv` o `.tsv`). Se viene utilizzata la compressione, `.gz` viene aggiunta anche .
`namePrefix`	`string`	Indica un prefisso da aggiungere a ogni nome dell'artefatto di archiviazione generato. Se non specificato, viene usato un prefisso casuale.
`encoding`	`string`	Indica come codificare il testo: `UTF8NoBOM` (impostazione predefinita) o `UTF8BOM`.
`compressionType`	`string`	Indica il tipo di compressione da utilizzare. I possibili valori sono `gzip` o `snappy`. Il valore predefinito è `gzip`. `snappy` può (facoltativamente) essere usato per `parquet` il formato.
`distribution`	`string`	Hint di distribuzione (`single`, `per_node`, `per_shard`). Se il valore è uguale `single`a , un singolo thread scrive nell'archiviazione. In caso contrario, esportare le scritture da tutti i nodi che eseguono la query in parallelo. Vedere Valutare l'operatore plug-in. Il valore predefinito è `per_shard`.
`persistDetails`	`bool`	Indica che il comando deve rendere persistenti i risultati (vedere `async` flag). L'impostazione predefinita è `true` in esecuzione asincrona, ma può essere disattivata se il chiamante non richiede i risultati. Il valore predefinito è `false` nelle esecuzioni sincrone, ma può essere attivato anche in tali esecuzioni.
`sizeLimit`	`long`	Limite di dimensioni in byte di un singolo artefatto di archiviazione scritto (prima della compressione). Intervallo valido: da 100 MB (impostazione predefinita) a 4 GB.
`parquetRowGroupSize`	`int`	Rilevante solo quando il formato dati è Parquet. Controlla le dimensioni del gruppo di righe nei file esportati. La dimensione predefinita del gruppo di righe è 100.000 record.
`distributed`	`bool`	Disabilitare/abilitare l'esportazione distribuita. L'impostazione su false equivale all'hint di `single` distribuzione. Il valore predefinito è true.
`parquetDatetimePrecision`	`string`	Specifica la precisione da utilizzare durante l'esportazione di `datetime` valori in Parquet. I valori possibili sono millisecondi e microsecondi. Il valore predefinito è millisecondo.

Autenticazione e autorizzazione

Il metodo di autenticazione si basa sul stringa di connessione fornito e le autorizzazioni necessarie variano a seconda del metodo di autenticazione.

Nella tabella seguente sono elencati i metodi di autenticazione supportati e le autorizzazioni necessarie per l'esportazione dei dati nell'archiviazione esterna in base al tipo di archiviazione.

Metodo di autenticazione	Archiviazione BLOB di Azure/Data Lake Storage Gen2	Data Lake Storage Gen1
Rappresentazione	Collaboratore dati BLOB di archiviazione	Collaboratore
Token (SAS) di accesso condiviso	Scrittura	Scrittura
Token di accesso di Microsoft Entra	Nessuna autorizzazione aggiuntiva necessaria	Nessuna autorizzazione aggiuntiva necessaria
Chiave di accesso dell'account di archiviazione	Nessuna autorizzazione aggiuntiva necessaria	Nessuna autorizzazione aggiuntiva necessaria

Valori restituiti

I comandi restituiscono una tabella che descrive gli artefatti di archiviazione generati. Ogni record descrive un singolo artefatto e include il percorso di archiviazione dell'artefatto e il numero di record che contiene.

Percorso	NumRecords
http://storage1.blob.core.windows.net/containerName/export_1_d08afcae2f044c1092b279412dcb571b.csv	10
http://storage1.blob.core.windows.net/containerName/export_2_454c0f1359e24795b6529da8a0101330.csv	15

Modalità asincrona

Se il async flag viene specificato, il comando viene eseguito in modalità asincrona. In questa modalità, il comando viene restituito immediatamente con un ID operazione e l'esportazione dei dati continua in background fino al completamento. L'ID operazione restituito dal comando può essere usato per tenere traccia dello stato di avanzamento e infine dei risultati tramite i comandi seguenti:

.show operations: tenere traccia dello stato di avanzamento.
.show operation details: ottiene i risultati di completamento.

Ad esempio, dopo un completamento corretto, è possibile recuperare i risultati usando:

.show operation f008dc1e-2710-47d8-8d34-0d562f5f8615 details

Esempi

In questo esempio Kusto esegue la query e quindi esporta il primo recordset generato dalla query in uno o più BLOB CSV compressi, fino a 1 GB prima della compressione. Le etichette dei nomi di colonna vengono aggiunte come prima riga per ogni BLOB.

.export
  async compressed
  to csv (
    h@"https://storage1.blob.core.windows.net/containerName;secretKey",
    h@"https://storage1.blob.core.windows.net/containerName2;secretKey"
  ) with (
    sizeLimit=1000000000,
    namePrefix="export",
    includeHeaders="all",
    encoding="UTF8NoBOM"
  )
  <| 
  Logs | where id == "1234"

Errori durante i comandi di esportazione

I comandi di esportazione possono avere esito negativo temporaneo durante l'esecuzione. L'esportazione continua ritenta automaticamente il comando. I comandi di esportazione regolari (esportazione nell'archiviazione, esportazione in tabella esterna) non eseguono tentativi.

Quando il comando di esportazione ha esito negativo, gli artefatti già scritti nella risorsa di archiviazione non vengono eliminati. Questi artefatti rimangono nello spazio di archiviazione. Se il comando ha esito negativo, si supponga che l'esportazione sia incompleta, anche se sono stati scritti alcuni artefatti.
Il modo migliore per tenere traccia del completamento del comando e degli artefatti esportati al completamento corretto consiste nell'usare i .show operations comandi e .show operation details .

Errori di archiviazione

Per impostazione predefinita, i comandi di esportazione vengono distribuiti in modo che vi siano molte scritture simultanee nella risorsa di archiviazione. Il livello di distribuzione dipende dal tipo di comando di esportazione:

La distribuzione predefinita per il comando regolare .export è per_shard, ovvero tutti gli extent che contengono dati per esportare la scrittura nello spazio di archiviazione contemporaneamente.
La distribuzione predefinita per l'esportazione in comandi di tabella esterna è per_node, ovvero la concorrenza è il numero di nodi.

Quando il numero di extent/nodi è elevato, questo può causare un carico elevato nell'archiviazione che comporta una limitazione dell'archiviazione o errori di archiviazione temporanei. I suggerimenti seguenti possono superare questi errori (in base all'ordine di priorità):

Aumentare il numero di account di archiviazione forniti al comando di esportazione o alla definizione di tabella esterna (il carico verrà distribuito uniformemente tra gli account).
Ridurre la concorrenza impostando l'hint di distribuzione su per_node (vedere le proprietà del comando).
Ridurre la concorrenza del numero di nodi da esportare impostando la proprietà query_fanout_nodes_percent della richiesta client sulla concorrenza desiderata (percentuale di nodi). La proprietà può essere impostata come parte della query di esportazione. Ad esempio, il comando seguente limita il numero di nodi che scrivono nella risorsa di archiviazione contemporaneamente al 50% dei nodi:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_node"
    ) 
    <| 
    set query_fanout_nodes_percent = 50;
    ExportQuery
```
Ridurre la concorrenza del numero di thread che esportano in ogni nodo quando si usa l'esportazione per partizione impostando la proprietà query_fanout_threads_percent della richiesta client sulla concorrenza desiderata (percentuale di thread). La proprietà può essere impostata come parte della query di esportazione. Ad esempio, il comando seguente limita il numero di thread che scrivono nella risorsa di archiviazione contemporaneamente al 50% in ognuno dei nodi:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_shard"
    ) 
    <| 
    set query_fanout_threads_percent = 50;
    ExportQuery
```
Se si esporta in una tabella esterna partizionata, l'impostazione delle proprietà può ridurre la spread/concurrency concorrenza (vedere i dettagli nelle proprietà del comando.
Se nessuna delle operazioni precedenti è possibile disabilitare completamente la distribuzione impostando la distributed proprietà su false. Tuttavia, non è consigliabile farlo, perché può influire significativamente sulle prestazioni del comando.

Errori di autorizzazione

Gli errori di autenticazione o autorizzazione durante i comandi di esportazione possono verificarsi quando le credenziali fornite nella stringa di connessione di archiviazione non sono autorizzate a scrivere nell'archiviazione. Se si usa impersonate o un token di firma di accesso condiviso delegato dall'utente per il comando di esportazione, è necessario il ruolo Collaboratore ai dati dei BLOB di archiviazione per scrivere nell'account di archiviazione. Per altre informazioni, vedere Stringa di connessione di archiviazione.

Mapping dei tipi di dati

Mapping dei tipi di dati Parquet

In caso di esportazione, i tipi di dati Kusto vengono mappati ai tipi di dati Parquet usando le regole seguenti:

Tipo di dati Kusto	Tipo di dati Parquet	Annotazione Parquet	Commenti
`bool`	`BOOLEAN`
`datetime`	`INT64`	TIMESTAMP_MICROS
`dynamic`	`BYTE_ARRAY`	UTF-8	Serializzato come stringa JSON
`guid`	`BYTE_ARRAY`	UTF-8
`int`	`INT32`
`long`	`INT64`
`real`	`DOUBLE`
`string`	`BYTE_ARRAY`	UTF-8
`timespan`	`INT64`		Archiviato come tick (unità di 100 nanosecondi)
`decimal`	`FIXED_LENGTH_BYTE_ARRAY`	DECIMAL

Condividi tramite