Inserimento da risorsa di archiviazione

  • Articolo

Il .ingest into comando inserisce i dati in una tabella "pull" dei dati da uno o più file di archiviazione cloud. Ad esempio, il comando può recuperare 1000 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 in scenari di produzione o di volumi elevati.

Autorizzazioni

Per eseguire questo comando, è necessario disporre almeno delle autorizzazioni Table Ingestor .

Sintassi

.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome Tipo Obbligatoria Descrizione
async string Se specificato, il comando restituisce immediatamente e continua l'inserimento in background. I risultati del comando includono un OperationId valore che può quindi essere usato con il .show operation comando 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 inserendo da una query di una tabella esterna.

Nota

È consigliabile usare valori letterali stringa offuscati per SourceDataPointer. Il servizio eseguirà lo scrubing delle credenziali nelle tracce interne e nei messaggi di errore.

Proprietà di inserimento

Importante

La tabella seguente elenca le proprietà supportate da Azure Esplora dati, le descrive e fornisce 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 format valore 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 tramite un oggetto criteri di mapping denominato. Definire il format valore 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 usare 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 Lookback proprietà nel criterio di unione extent effettivi della tabella di destinazione sia allineata al valore specificato. 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 è valida solo per i comandi .append e .set-or-append. Le uniche estensioni dello schema consentite includono colonne aggiuntive alla fine della tabella. Se lo schema della tabella originale è (a:string, b:int), un'estensione dello schema valida sarebbe (a:string, b:int, c:datetime, d:string), ma (a:string, c:datetime) non sarebbe valida
folder Per i comandi di inserimento da query , la cartella da assegnare alla tabella. Se la tabella esiste già, questa proprietà eseguirà l'override della cartella della tabella. with (folder="Tables/Temporary")
format Formato dati (vedere formati di dati supportati). with (format="csv")
ingestIfNotExists valore stringa che, se specificato, impedisce il completamento dell'inserimento se la tabella contiene già dati contrassegnati con un tag ingest-by: con lo stesso valore. In questo modo si garantisce un inserimento dati idempotente. Per altre informazioni, vedere Inserimento per 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, false si presuppone . with (ignoreFirstRecord=false)
policy_ingestiontime valore booleano che, se specificato, indica se abilitare i criteri del tempo di inserimento su una tabella creata da questo comando. Il valore predefinito è true. with (policy_ingestiontime=false)
recreate_schema valore booleano che, se specificato, indica se il comando può ricreare lo schema della tabella. Questa proprietà si applica solo al .set-or-replace comando . Questa proprietà ha la precedenza sulla extend_schema proprietà se entrambe sono impostate. with (recreate_schema=true)
tags Elenco di tag da associare ai dati inseriti, formattati come stringa JSON with (tags="['Tag1', 'Tag2']")
validationPolicy Stringa JSON che indica quali convalide eseguire durante l'inserimento di dati rappresentati usando il formato CSV. Per una spiegazione delle diverse opzioni, vedere Inserimento dati. with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (questo è in realtà il criterio predefinito)
zipPattern Utilizzare questa proprietà durante l'inserimento di 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 verranno ignorati. with (zipPattern="*.csv")

Autenticazione e autorizzazione

Ogni stringa di connessione di archiviazione indica il metodo di autorizzazione da usare per l'accesso alla risorsa di 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 dei dati dall'archiviazione esterna.

Metodo di autenticazione Archiviazione BLOB di Azure/Data Lake Storage Gen2 Data Lake Storage Gen1
Rappresentazione Lettore dei dati del BLOB di archiviazione Reader
Token di accesso condiviso Elenco + lettura Questo metodo di autenticazione non è supportato in Gen1.
token di accesso Microsoft Entra
Chiave di accesso dell'account di archiviazione Questo metodo di autenticazione non è supportato in Gen1.
Identità gestita Lettore dei dati del BLOB di archiviazione Reader

Restituisce

Il risultato del comando è una tabella con quanti record sono presenti partizioni di dati ("extent") generate dal comando. Se non sono state generate partizioni di dati, viene restituito un singolo record con un ID di estensione vuoto (con valore zero).

Nome Tipo Descrizione
ExtentId guid Identificatore univoco per la partizione di dati generata dal comando.
Elemento Caricato string Uno o più file di archiviazione correlati a questo record.
Durata timespan Tempo necessario per eseguire l'inserimento.
HasErrors bool Se questo record rappresenta un errore di inserimento o meno.
OperationId guid ID univoco che rappresenta l'operazione. Può essere usato con il .show operation comando .

Nota

Questo comando non modifica lo schema della tabella inserita. Se necessario, i dati sono "coerced" in questo schema durante l'inserimento, non l'altro modo in cui le colonne aggiuntive vengono ignorate e le colonne mancanti vengono considerate come valori Null.

Esempio

Archiviazione BLOB di Azure con firma di accesso condiviso

Nell'esempio seguente viene indicato al cluster di leggere due BLOB da Archiviazione BLOB di Azure come file CSV e inserire il contenuto nella tabella T. Rappresenta ... una firma di accesso condiviso di Archiviazione di Azure che consente l'accesso in lettura a ogni BLOB. Si noti anche l'uso di stringhe offuscate (davanti h ai valori stringa) 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

Nell'esempio seguente viene illustrato come leggere un file CSV da Archiviazione BLOB di Azure e inserire il contenuto nella tabella T usando l'autenticazione dell'identità gestita. Per altre informazioni sul metodo di autenticazione dell'identità gestita, vedere Panoramica dell'autenticazione dell'identità gestita.

.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 consiste nell'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 stringa solo per la parte privata del 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 (quindi non è necessario considerare l'URI di archiviazione come contenente un segreto). Mostra 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 segreto.

.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

Nell'esempio seguente viene inserito un singolo file da Amazon S3 usando un URL presigned.

.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
  with (format='csv')