.ingest in
Van toepassing op: ✅Microsoft Fabric✅Azure Data Explorer-
Met de opdracht .ingest into worden gegevens opgenomen in een tabel door de gegevens uit een of meer cloudopslagbestanden op te halen.
De opdracht kan bijvoorbeeld 1000 CSV-blobs ophalen uit Azure Blob Storage, deze parseren en opnemen in één doeltabel.
Gegevens worden toegevoegd aan de tabel 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 deze niet in productie- of grote volumescenario's.
Notitie
Deze opnamemethode is bedoeld voor verkenning en prototypen. Gebruik deze niet in productie- of grote volumescenario's. Zie Overzicht van gegevensopnamevoor meer informatie over opnameopties.
Machtigingen
U moet ten minste Table Ingestor machtigingen hebben om deze opdracht uit te voeren.
Syntaxis
.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]
Meer informatie over syntaxisconventies.
Parameters
| Naam | Type | Vereist | Beschrijving |
|---|---|---|---|
async |
string |
Indien opgegeven, wordt de opdracht onmiddellijk geretourneerd en wordt de opname op de achtergrond voortgezet. De resultaten van de opdracht bevatten een OperationId waarde die vervolgens kan worden gebruikt met de opdracht .show operation 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 is 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 de SourceDataLocators. De service verwijdert referenties in interne traceringen en foutberichten.
Opname-eigenschappen
Belangrijk
In de wachtrij opgenomen gegevens in batches worden gebatcheerd met behulp van opname-eigenschappen. Hoe meer afzonderlijke opnametoewijzingseigenschappen worden gebruikt, zoals verschillende ConstValue-waarden, hoe gefragmenteerder de opname wordt, wat kan leiden tot prestatievermindering.
In de volgende tabel worden de ondersteunde eigenschappen vermeld en beschreven en worden voorbeelden weergegeven:
| Eigenschap | Beschrijving | Voorbeeld |
|---|---|---|
ingestionMapping |
Een tekenreekswaarde die aangeeft hoe gegevens uit het bronbestand 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 tijdens het maken van de opgenomen gegevensbereiken. Indien niet opgegeven, 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 u dit hebt opgegeven, moet u ervoor zorgen dat de eigenschap Lookback in het effectieve -beleid voor het samenvoegen van gebieden is afgestemd op de opgegeven waarde. |
with (creationTime="2017-02-13") |
extend_schema |
Een Booleaanse waarde die, indien opgegeven, de opdracht geeft om het schema van de tabel uit te breiden (standaard ingesteld op false). Deze optie is alleen van toepassing op .append- en .set-or-append opdrachten. De enige toegestane schema-extensies hebben meer kolommen toegevoegd aan de tabel aan het einde. |
Als het oorspronkelijke tabelschema (a:string, b:int)is, zou een geldige schema-extensie (a:string, b:int, c:datetime, d:string)zijn, maar (a:string, c:datetime) niet geldig zou zijn |
folder |
Voor opdrachten voor opnemen van query's, moet de map aan de tabel 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 de opname slaagt als de tabel al gegevens bevat die zijn gelabeld met een ingest-by: tag met dezelfde waarde. Dit zorgt voor idempotente gegevensopname. Zie opname per: tagsvoor meer informatie. |
De eigenschappen with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') aangeven dat als gegevens met de tag ingest-by:Part0001 al bestaan, de huidige opname niet voltooien. Als deze nog niet bestaat, moet deze nieuwe opname deze tagset hebben (voor het geval een toekomstige opname dezelfde gegevens opnieuw probeert op te nemen.) |
ignoreFirstRecord |
Een Booleaanse waarde die, indien ingesteld op true, aangeeft dat 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. Standaard wordt false ervan uitgegaan. |
with (ignoreFirstRecord=false) |
policy_ingestiontime |
Een Booleaanse waarde die, indien opgegeven, beschrijft of de 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 opdracht .set-or-replace. Deze eigenschap heeft voorrang op de eigenschap extend_schema als beide zijn ingesteld. |
with (recreate_schema=true) |
tags |
Een lijst met tags om te koppelen aan de opgenomen gegevens, opgemaakt als een JSON-tekenreeks | with (tags="['Tag1', 'Tag2']") |
TreatGzAsUncompressed |
Een Booleaanse waarde die, indien ingesteld op true, aangeeft dat bestanden met de extensie .gz niet worden gecomprimeerd. Deze vlag is soms nodig bij het opnemen van Amazon AWS S3. |
with (treatGzAsUncompressed=true) |
validationPolicy |
Een JSON-tekenreeks die aangeeft welke validaties moeten worden uitgevoerd tijdens het opnemen van gegevens die worden weergegeven met csv-indeling. Zie Gegevensopname voor een uitleg van de verschillende opties. |
with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (dit is 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 welke bestanden in het ZIP-archief moeten worden opgenomen. Alle andere bestanden in het archief worden genegeerd. | with (zipPattern="*.csv") |
Verificatie en autorisatie
Elke opslagverbindingsreeks geeft de autorisatiemethode aan die moet worden gebruikt voor toegang tot de opslag. Afhankelijk van de autorisatiemethode moet de principal mogelijk machtigingen krijgen 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 | Opslagblobgegevenslezer | Lezer |
| SAS-token (Shared Access) | Lijst + lezen | Deze verificatiemethode wordt niet ondersteund in Gen1. |
| Microsoft Entra-toegangstoken | ||
| toegangssleutel voor opslagaccounts | Deze verificatiemethode wordt niet ondersteund in Gen1. | |
| beheerde identiteit | Opslagblobgegevenslezer | Lezer |
Retourneert
Het resultaat van de opdracht is een tabel met zo veel records als er gegevensshards ('extents') zijn die door de opdracht worden gegenereerd. Als er geen gegevensshards zijn gegenereerd, wordt één record geretourneerd met een lege (nulwaarde)-id.
| Naam | Type | Beschrijving |
|---|---|---|
| ExtentId | guid |
De unieke id voor de gegevensshard die is gegenereerd door de opdracht. |
| 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 al dan niet een opnamefout vertegenwoordigt. |
| OperationId | guid |
Een unieke id die de bewerking vertegenwoordigt. Kan worden gebruikt met de opdracht .show operation. |
Notitie
Met deze opdracht wordt het schema van de tabel waarin wordt opgenomen, niet gewijzigd. Indien nodig worden de gegevens 'verplicht' in dit schema weergegeven tijdens 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 database geïnstrueerd om twee blobs uit Azure Blob Storage als CSV-bestanden te lezen en hun inhoud op te nemen in tabel T. De ... vertegenwoordigt een Sas (Shared Access Signature) van Azure Storage, die leestoegang geeft tot elke blob. Verborgen tekenreeksen (de h vóór de tekenreekswaarden) worden gebruikt 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 beheerde identiteit
In het volgende voorbeeld ziet u hoe u een CSV-bestand uit Azure Blob Storage leest en de inhoud ervan opneemt in een tabel T met behulp van verificatie van beheerde identiteiten. Verificatie maakt gebruik van de beheerde id (object-id) die is toegewezen aan Azure Blob Storage in Azure. Zie Een beheerde identiteit maken voor opslagcontainersvoor meer informatie.
.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 referenties van het opslagaccount (gedeelde sleutel) en we gebruiken alleen tekenreeksen 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 opgenomen uit Azure Data Lake Storage (ADLS). Er worden de referenties van de gebruiker gebruikt om toegang te krijgen tot ADLS (zodat de opslag-URI niet hoeft te worden behandeld als een geheim). Ook ziet u hoe u opname-eigenschappen kunt opgeven.
.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')