.ingest into
Si applica a: ✅Microsoft Fabric✅Esplora dati di Azure
Il comando .ingest into inserisce i dati in una tabella "pull" dei dati da uno o più file di archiviazione cloud.
Ad esempio, il comando può recuperare 1.000 BLOB in formato CSV da Archiviazione BLOB di Azure, analizzarli e inserirli insieme in una singola tabella di destinazione.
I dati vengono aggiunti alla tabella senza influire sui record esistenti e senza modificare lo schema della tabella.
Nota
Questo metodo di inserimento è destinato all'esplorazione e alla creazione di prototipi. Non usarlo negli scenari di produzione o di volumi elevati.
Autorizzazioni
Per eseguire questo comando, è necessario disporre almeno autorizzazioni di Table Ingestor.
Sintassi
.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]
Altre informazioni sulle convenzioni di sintassi .
Parametri
| Nome | Digitare | Obbligatorio | Descrizione |
|---|---|---|---|
async |
string |
Se specificato, il comando restituisce immediatamente e continua l'inserimento in background. I risultati del comando includono un valore OperationId che può quindi essere usato con il comando .show operation per recuperare lo stato e i risultati del completamento dell'inserimento. |
|
| TableName | string |
✔️ | Nome della tabella in cui inserire i dati. Il nome della tabella è sempre relativo al database nel contesto. Se non viene fornito alcun oggetto di mapping dello schema, viene utilizzato lo schema del database nel contesto. |
| SourceDataLocator | string |
✔️ | Un singolo elenco delimitato da virgole di stringhe di connessione di archiviazione . Una singola stringa di connessione deve fare riferimento a un singolo file ospitato da un account di archiviazione. L'inserimento di più file può essere eseguito specificando più stringhe di connessione o l'inserimento da una query di una tabella esterna . |
Nota
È consigliabile usare valori letterali stringa offuscati per SourceDataLocators. Il servizio eseguirà lo scrub delle credenziali nelle tracce interne e nei messaggi di errore.
Proprietà di inserimento
Importante
Nell'inserimento in coda i dati vengono inseriti in batch usando le proprietà di inserimento. Le proprietà di mapping di inserimento più distinte usate, ad esempio valori ConstValue diversi, diventano più frammentate l'inserimento, il che può causare una riduzione delle prestazioni.
Nella tabella seguente sono elencate e descritte le proprietà supportate e vengono forniti esempi:
| Proprietà | Descrizione | Esempio |
|---|---|---|
ingestionMapping |
Valore stringa che indica come eseguire il mapping dei dati dal file di origine alle colonne effettive della tabella. Definire il valore format con il tipo di mapping pertinente. Vedere mapping dei dati. |
with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]")(deprecato: avroMapping, csvMapping, jsonMapping) |
ingestionMappingReference |
Valore stringa che indica come eseguire il mapping dei dati dal file di origine alle colonne effettive della tabella usando un oggetto criteri di mapping denominato. Definire il valore format con il tipo di mapping pertinente. Vedere mapping dei dati. |
with (format="csv", ingestionMappingReference = "Mapping1")(deprecato: avroMappingReference, csvMappingReference, jsonMappingReference) |
creationTime |
Valore datetime (formattato come stringa ISO8601) da utilizzare al momento della creazione degli extent di dati inseriti. Se non specificato, viene usato il valore corrente (now()). L'override del valore predefinito è utile quando si inseriscono dati meno recenti, in modo che i criteri di conservazione vengano applicati correttamente. Se specificato, assicurarsi che la proprietà |
with (creationTime="2017-02-13") |
extend_schema |
Valore booleano che, se specificato, indica al comando di estendere lo schema della tabella (il valore predefinito è false). Questa opzione si applica solo ai comandi .append e .set-or-append. Le uniche estensioni dello schema consentite hanno più colonne aggiunte alla tabella alla fine. |
Se lo schema della tabella originale è (a:string, b:int), un'estensione dello schema valida sarà (a:string, b:int, c:datetime, d:string), ma (a:string, c:datetime) non sarebbe valida |
folder |
Per comandi di inserimento da query, la cartella da assegnare alla tabella. Se la tabella esiste già, questa proprietà esegue l'override della cartella della tabella. | with (folder="Tables/Temporary") |
format |
Formato dei dati (vedere formati di dati supportati). | with (format="csv") |
ingestIfNotExists |
Valore stringa che, se specificato, impedisce l'inserimento se la tabella contiene già dati contrassegnati con un tag ingest-by: con lo stesso valore. In questo modo si garantisce l'inserimento dei dati idempotente. Per altre informazioni, vedere inserimento in base ai tag. |
Le proprietà with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') indicano che se i dati con il tag ingest-by:Part0001 esistono già, non completare l'inserimento corrente. Se non esiste già, questo nuovo inserimento deve avere questo tag impostato (nel caso in cui un inserimento futuro tenti di inserire nuovamente gli stessi dati). |
ignoreFirstRecord |
Valore booleano che, se impostato su true, indica che l'inserimento deve ignorare il primo record di ogni file. Questa proprietà è utile per i file in CSVe formati simili, se il primo record nel file è costituito dai nomi delle colonne. Per impostazione predefinita, si presuppone false. |
with (ignoreFirstRecord=false) |
policy_ingestiontime |
Valore booleano che, se specificato, descrive se abilitare i criteri di tempo di inserimento in una tabella creata da questo comando. Il valore predefinito è true. |
with (policy_ingestiontime=false) |
recreate_schema |
Valore booleano che, se specificato, descrive se il comando può ricreare lo schema della tabella. Questa proprietà si applica solo al comando .set-or-replace. Questa proprietà ha la precedenza sulla proprietà extend_schema se sono impostate entrambe. |
with (recreate_schema=true) |
tags |
Elenco di tag da associare ai dati inseriti, formattati come stringa JSON | with (tags="['Tag1', 'Tag2']") |
TreatGzAsUncompressed |
Valore booleano che, se impostato su true, indica che i file con estensione .gz non vengono compressi. Questo flag è talvolta necessario quando si inserisce da Amazon AWS S3. |
with (treatGzAsUncompressed=true) |
validationPolicy |
Stringa JSON che indica le convalide da eseguire durante l'inserimento di dati rappresentati usando il formato CSV. Per una spiegazione delle diverse opzioni, vedere di inserimento dati |
with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (criterio predefinito) |
zipPattern |
Utilizzare questa proprietà quando si inseriscono dati dall'archiviazione con un archivio ZIP. Si tratta di un valore stringa che indica l'espressione regolare da usare quando si selezionano i file nell'archivio ZIP da inserire. Tutti gli altri file nell'archivio vengono ignorati. | with (zipPattern="*.csv") |
Autenticazione e autorizzazione
Ogni stringa di connessione di archiviazione indica il metodo di autorizzazione da usare per l'accesso all'archiviazione. A seconda del metodo di autorizzazione, potrebbe essere necessario concedere all'entità le autorizzazioni per l'archiviazione esterna per eseguire l'inserimento.
Nella tabella seguente sono elencati i metodi di autenticazione supportati e le autorizzazioni necessarie per l'inserimento di dati da una risorsa di archiviazione esterna.
| Metodo di autenticazione | Archiviazione BLOB di Azure/Data Lake Storage Gen2 | Data Lake Storage Gen1 |
|---|---|---|
| rappresentazione | Lettore di dati BLOB di archiviazione | Lettore |
| token di accesso condiviso (SAS) | Elenco e lettura | Questo metodo di autenticazione non è supportato in Gen1. |
| token di accesso di Microsoft Entra | ||
| chiave di accesso dell'account di archiviazione | Questo metodo di autenticazione non è supportato in Gen1. | |
| 'identità gestita | Lettore di dati BLOB di archiviazione | Lettore |
Rendiconto
Il risultato del comando è una tabella con un numero di record pari a quello delle partizioni di dati ("extent") generate dal comando. Se non sono state generate partizioni di dati, viene restituito un singolo record con un ID extent vuoto (con valori zero).
| Nome | Digitare | Descrizione |
|---|---|---|
| ExtentId | guid |
Identificatore univoco per la partizione di dati generata dal comando . |
| ItemLoaded | string |
Uno o più file di archiviazione correlati a questo record. |
| Durata | timespan |
Tempo necessario per eseguire l'inserimento. |
| HasErrors | bool |
Indica se questo record rappresenta o meno un errore di inserimento. |
| OperationId | guid |
ID univoco che rappresenta l'operazione. Può essere usato con il comando .show operation. |
Nota
Questo comando non modifica lo schema della tabella in cui viene inserita. Se necessario, i dati vengono "forzati" in questo schema durante l'inserimento, non in altro modo (le colonne aggiuntive vengono ignorate e le colonne mancanti vengono considerate come valori Null).
Esempi
Archiviazione BLOB di Azure con firma di accesso condiviso
L'esempio seguente indica al database di leggere due BLOB da Archiviazione BLOB di Azure come file CSV e inserire il relativo contenuto nella tabella T. Il ... rappresenta una firma di accesso condiviso di Archiviazione di Azure che consente l'accesso in lettura a ogni BLOB. Le stringhe offuscate (il h davanti ai valori stringa) vengono usate per assicurarsi che la firma di accesso condiviso non venga mai registrata.
.ingest into table T (
h'https://contoso.blob.core.windows.net/container/file1.csv?...',
h'https://contoso.blob.core.windows.net/container/file2.csv?...'
)
Archiviazione BLOB di Azure con identità gestita
L'esempio seguente illustra come leggere un file CSV da Archiviazione BLOB di Azure e inserire il contenuto nella tabella T usando l'autenticazione dell'identità gestita. L'autenticazione usa l'ID identità gestita (ID oggetto) assegnato all'archiviazione BLOB di Azure in Azure. Per altre informazioni, vedere Creare un'identità gestita per i contenitori di archiviazione.
.ingest into table T ('https://StorageAccount.blob.core.windows.net/Container/file.csv;managed_identity=802bada6-4d21-44b2-9d15-e66b29e4d63e')
Azure Data Lake Storage Gen 2
L'esempio seguente è relativo all'inserimento di dati da Azure Data Lake Storage Gen 2 (ADLSv2). Le credenziali usate qui (...) sono le credenziali dell'account di archiviazione (chiave condivisa) e si usa l'offuscamento della stringa solo per la parte privata della stringa di connessione.
.ingest into table T (
'abfss://myfilesystem@contoso.dfs.core.windows.net/path/to/file1.csv;...'
)
Azure Data Lake Storage
L'esempio seguente inserisce un singolo file da Azure Data Lake Storage (ADLS). Usa le credenziali dell'utente per accedere ad ADLS, pertanto non è necessario considerare l'URI di archiviazione come contenente un segreto. Illustra anche come specificare le proprietà di inserimento.
.ingest into table T ('adl://contoso.azuredatalakestore.net/Path/To/File/file1.ext;impersonate')
with (format='csv')
Amazon S3 con una chiave di accesso
L'esempio seguente inserisce un singolo file da Amazon S3 usando un ID chiave di accesso e una chiave di accesso privata.
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/path/to/file.csv;AwsCredentials=AKIAIOSFODNN7EXAMPLE,wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY')
with (format='csv')
Amazon S3 con un URL prefirmato
L'esempio seguente inserisce un singolo file da Amazon S3 usando un URL prefirmato .
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
with (format='csv')