Opname vanuit opslag

  • Artikel

Met de .ingest into opdracht worden gegevens opgenomen in een tabel door de gegevens op te halen uit een of meer cloudopslagbestanden. De opdracht kan bijvoorbeeld 1000 CSV-blobs ophalen uit Azure Blob Storage, deze parseren en ze samen opnemen in één doeltabel. Gegevens worden aan de tabel toegevoegd zonder dat dit van invloed is op bestaande records en zonder het schema van de tabel te wijzigen.

Notitie

Deze opnamemethode is bedoeld voor verkenning en prototypen. Gebruik het niet in productie- of scenario's met grote volumes.

Machtigingen

U moet ten minste Table Ingestor-machtigingen hebben om deze opdracht uit te voeren.

Syntax

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

Meer informatie over syntaxisconventies.

Parameters

Naam Type Vereist Beschrijving
async string Indien opgegeven, retourneert de opdracht onmiddellijk en wordt de opname op de achtergrond voortgezet. De resultaten van de opdracht bevatten een OperationId waarde die vervolgens kan worden gebruikt met de .show operation opdracht om de voltooiingsstatus en resultaten van de opname op te halen.
TableName string ✔️ De naam van de tabel waarin gegevens moeten worden opgenomen. De tabelnaam is altijd relatief ten opzichte van de database in context. Als er geen schematoewijzingsobject wordt opgegeven, wordt het schema van de database in context gebruikt.
SourceDataLocator string ✔️ Een enkele of door komma's gescheiden lijst met opslagverbindingsreeksen. Eén verbindingsreeks moet verwijzen naar één bestand dat wordt gehost door een opslagaccount. Opname van meerdere bestanden kan worden uitgevoerd door meerdere verbindingsreeksen op te geven of door op te nemen uit een query van een externe tabel.

Notitie

U wordt aangeraden verborgen letterlijke tekenreeksen te gebruiken voor SourceDataPointer. De service zal referenties in interne traceringen en foutberichten wissen.

Opname-eigenschappen

Belangrijk

De volgende tabel bevat de eigenschappen die worden ondersteund door Azure Data Explorer, beschrijft deze en geeft voorbeelden:

Eigenschap Beschrijving Voorbeeld
ingestionMapping Een tekenreekswaarde die aangeeft hoe gegevens uit het bronbestand moeten worden toegewezen aan de werkelijke kolommen in de tabel. Definieer de format waarde met het relevante toewijzingstype. Zie gegevenstoewijzingen. with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]")
(afgeschaft: avroMapping, csvMapping, jsonMapping)
ingestionMappingReference Een tekenreekswaarde die aangeeft hoe gegevens uit het bronbestand worden toegewezen aan de werkelijke kolommen in de tabel met behulp van een benoemd toewijzingsbeleidsobject. Definieer de format waarde met het relevante toewijzingstype. Zie gegevenstoewijzingen. with (format="csv", ingestionMappingReference = "Mapping1")
(afgeschaft: avroMappingReference, csvMappingReference, jsonMappingReference)
creationTime De datum/tijd-waarde (opgemaakt als een ISO8601 tekenreeks) die moet worden gebruikt bij het maken van de opgenomen gegevensbereiken. Als u dit niet opgeeft, wordt de huidige waarde (now()) gebruikt. Het overschrijven van de standaardwaarde is handig bij het opnemen van oudere gegevens, zodat het bewaarbeleid correct wordt toegepast. Wanneer dit is opgegeven, moet u ervoor zorgen dat de Lookback eigenschap in het effectieve samenvoegbeleid van de doeltabel is afgestemd op de opgegeven waarde. with (creationTime="2017-02-13")
extend_schema Een Booleaanse waarde die, indien opgegeven, de opdracht instrueert om het schema van de tabel uit te breiden (standaard ingesteld op false). Deze optie is alleen van toepassing op .append opdrachten en .set-or-append . De enige toegestane schema-extensies hebben extra kolommen toegevoegd aan de tabel aan het einde. Als het oorspronkelijke tabelschema is (a:string, b:int), is (a:string, b:int, c:datetime, d:string)een geldige schema-extensie , maar (a:string, c:datetime) niet geldig
folder Voor ingest-from-query-opdrachten , de map die aan de tabel moet worden toegewezen. Als de tabel al bestaat, overschrijft deze eigenschap de map van de tabel. with (folder="Tables/Temporary")
format De gegevensindeling (zie ondersteunde gegevensindelingen). with (format="csv")
ingestIfNotExists Een tekenreekswaarde die, indien opgegeven, voorkomt dat opname wordt uitgevoerd als de tabel al gegevens bevat die zijn getagd met een ingest-by: tag met dezelfde waarde. Dit zorgt voor idempotente gegevensopname. Zie ingest-by: tags voor meer informatie. De eigenschappen with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') geven aan dat als er al gegevens met de tag ingest-by:Part0001 bestaan, de huidige opname niet wordt voltooid. Als deze nog niet bestaat, moet deze tag voor deze nieuwe opname zijn ingesteld (voor het geval een toekomstige opname dezelfde gegevens opnieuw probeert op te nemen.)
ignoreFirstRecord Een Booleaanse waarde die, indien ingesteld op true, aangeeft dat de opname de eerste record van elk bestand moet negeren. Deze eigenschap is handig voor bestanden in CSVen vergelijkbare indelingen, als de eerste record in het bestand de kolomnamen zijn. false Standaard wordt ervan uitgegaan. with (ignoreFirstRecord=false)
policy_ingestiontime Een Booleaanse waarde die, indien opgegeven, beschrijft of het opnametijdbeleid moet worden ingeschakeld voor een tabel die met deze opdracht wordt gemaakt. De standaardwaarde is true. with (policy_ingestiontime=false)
recreate_schema Een Booleaanse waarde die, indien opgegeven, beschrijft of de opdracht het schema van de tabel opnieuw kan maken. Deze eigenschap is alleen van toepassing op de .set-or-replace opdracht. Deze eigenschap heeft voorrang op de extend_schema eigenschap als beide zijn ingesteld. with (recreate_schema=true)
tags Een lijst met tags die moeten worden gekoppeld aan de opgenomen gegevens, opgemaakt als een JSON-tekenreeks with (tags="['Tag1', 'Tag2']")
validationPolicy Een JSON-tekenreeks die aangeeft welke validaties moeten worden uitgevoerd tijdens de opname van gegevens die worden weergegeven in csv-indeling. Zie Gegevensopname voor een uitleg van de verschillende opties. with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (dit is eigenlijk het standaardbeleid)
zipPattern Gebruik deze eigenschap bij het opnemen van gegevens uit opslag met een ZIP-archief. Dit is een tekenreekswaarde die de reguliere expressie aangeeft die moet worden gebruikt bij het selecteren van de bestanden in het ZIP-archief die moeten worden opgenomen. Alle andere bestanden in het archief worden genegeerd. with (zipPattern="*.csv")

Verificatie en autorisatie

Elke opslag verbindingsreeks geeft de autorisatiemethode aan die moet worden gebruikt voor toegang tot de opslag. Afhankelijk van de autorisatiemethode moet aan de principal mogelijk machtigingen worden verleend voor de externe opslag om de opname uit te voeren.

De volgende tabel bevat de ondersteunde verificatiemethoden en de machtigingen die nodig zijn voor het opnemen van gegevens uit externe opslag.

Verificatiemethode Azure Blob Storage/Data Lake Storage Gen2 Data Lake Storage Gen1
Imitatie Lezer voor opslagblobgegevens Lezer
Sas-token (Shared Access) Lijst + lezen Deze verificatiemethode wordt niet ondersteund in Gen1.
Microsoft Entra toegangstoken
Toegangssleutel voor opslagaccount Deze verificatiemethode wordt niet ondersteund in Gen1.
Beheerde identiteit Lezer voor opslagblobgegevens Lezer

Retouren

Het resultaat van de opdracht is een tabel met zoveel records als er gegevensshards ('gebieden') zijn die door de opdracht zijn gegenereerd. Als er geen gegevensshards zijn gegenereerd, wordt één record geretourneerd met een lege (nulwaarde) bereik-id.

Naam Type Description
ExtentId guid De unieke id voor de gegevensshard die door de opdracht is gegenereerd.
ItemLoaded string Een of meer opslagbestanden die zijn gerelateerd aan deze record.
Duur timespan Hoe lang het duurde om opname uit te voeren.
HasErrors bool Of deze record een opnamefout vertegenwoordigt of niet.
OperationId guid Een unieke id die de bewerking vertegenwoordigt. Kan worden gebruikt met de .show operation opdracht .

Notitie

Met deze opdracht wordt het schema van de tabel waarin wordt opgenomen, niet gewijzigd. Indien nodig worden de gegevens in dit schema 'afgedwongen' tijdens de opname, niet andersom (extra kolommen worden genegeerd en ontbrekende kolommen worden behandeld als null-waarden).

Voorbeelden

Azure Blob Storage met Shared Access Signature

In het volgende voorbeeld wordt uw cluster geïnstrueerd om twee blobs uit Azure Blob Storage als CSV-bestanden te lezen en de inhoud ervan op te nemen in de tabel T. De ... vertegenwoordigt een Sas (Shared Access Signature) van Azure Storage die leestoegang tot elke blob biedt. Let ook op het gebruik van verborgen tekenreeksen (de h vóór de tekenreekswaarden) om ervoor te zorgen dat de SAS nooit wordt vastgelegd.

.ingest into table T (
    h'https://contoso.blob.core.windows.net/container/file1.csv?...',
    h'https://contoso.blob.core.windows.net/container/file2.csv?...'
)

Azure Blob Storage met een beheerde identiteit

In het volgende voorbeeld ziet u hoe u een CSV-bestand leest uit Azure Blob Storage en de inhoud ervan opneemt in de tabel T met behulp van verificatie van beheerde identiteiten. Zie Overzicht van verificatie van beheerde identiteiten voor meer informatie over de verificatiemethode voor beheerde identiteiten.

.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

Het volgende voorbeeld is voor het opnemen van gegevens uit Azure Data Lake Storage Gen 2 (ADLSv2). De referenties die hier worden gebruikt (...) zijn de opslagaccountreferenties (gedeelde sleutel) en we gebruiken tekenreeksen alleen voor het geheime deel van de verbindingsreeks.

.ingest into table T (
  'abfss://myfilesystem@contoso.dfs.core.windows.net/path/to/file1.csv;...'
)

Azure Data Lake Storage

In het volgende voorbeeld wordt één bestand uit Azure Data Lake Storage (ADLS) opgenomen. Er wordt gebruikgemaakt van de referenties van de gebruiker voor toegang tot ADLS (dus het is niet nodig om de opslag-URI te behandelen als die een geheim bevat). U ziet ook hoe u opname-eigenschappen opgeeft.

.ingest into table T ('adl://contoso.azuredatalakestore.net/Path/To/File/file1.ext;impersonate')
  with (format='csv')

Amazon S3 met een toegangssleutel

In het volgende voorbeeld wordt één bestand van Amazon S3 opgenomen met behulp van een toegangssleutel-id en een geheime toegangssleutel.

.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 met een vooraf ondertekende URL

In het volgende voorbeeld wordt één bestand van Amazon S3 opgenomen met behulp van een vooraf ondertekende URL.

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