.ingest in
Gilt für: ✅Microsoft Fabric✅Azure Data Explorer
Der Befehl .ingest into erfasst Daten in eine Tabelle, indem die Daten aus einer oder mehreren Cloudspeicherdateien "abgerufen" werden.
Beispielsweise kann der Befehl 1.000 CSV-formatierte Blobs aus Azure Blob Storage abrufen, diese analysieren und in einer einzelnen Zieltabelle zusammen aufnehmen.
Daten werden an die Tabelle angefügt, ohne dass sich dies auf vorhandene Datensätze auswirkt, und ohne das Schema der Tabelle zu ändern.
Anmerkung
Diese Aufnahmemethode ist für Die Erforschung und Prototyperstellung vorgesehen. Verwenden Sie sie nicht in Produktions- oder Volumenszenarien.
Anmerkung
Diese Aufnahmemethode ist für Die Erforschung und Prototyperstellung vorgesehen. Verwenden Sie sie nicht in Produktions- oder Volumenszenarien. Weitere Informationen zu Aufnahmeoptionen finden Sie unter Datenaufnahmeübersicht.
Erlaubnisse
Sie müssen mindestens Table Ingestor Berechtigungen zum Ausführen dieses Befehls besitzen.
Syntax
.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]
Erfahren Sie mehr über Syntaxkonventionen.
Parameter
| Name | Art | Erforderlich | Beschreibung |
|---|---|---|---|
async |
string |
Wenn angegeben, gibt der Befehl sofort zurück und setzt die Aufnahme im Hintergrund fort. Die Ergebnisse des Befehls enthalten einen OperationId Wert, der dann mit dem Befehl .show operation verwendet werden kann, um den Status und die Ergebnisse des Aufnahmeabschlusses abzurufen. |
|
| TableName- | string |
✔️ | Der Name der Tabelle, in die Daten aufgenommen werden sollen. Der Tabellenname ist immer relativ zur Datenbank im Kontext. Wenn kein Schemazuordnungsobjekt bereitgestellt wird, wird das Schema der Datenbank im Kontext verwendet. |
| SourceDataLocator- | string |
✔️ | Eine einzelne oder kommagetrennte Liste Speicherverbindungszeichenfolgen. Eine einzelne Verbindungszeichenfolge muss auf eine einzelne Datei verweisen, die von einem Speicherkonto gehostet wird. Die Erfassung mehrerer Dateien kann durch Angeben mehrerer Verbindungszeichenfolgen oder durch Aufnahme aus einer Abfrage einer externen Tabelleerfolgen. |
Anmerkung
Es wird empfohlen, verschleierten Zeichenfolgenliterale für die SourceDataLocators-zu verwenden. Der Dienst bereinigt Anmeldeinformationen in internen Ablaufverfolgungen und Fehlermeldungen.
Aufnahmeeigenschaften
Wichtig
Bei der Aufnahme in die Warteschlange werden Daten mithilfe von Ingestion-Eigenschaftenbatched. Je unterschiedliche Zuordnungseigenschaften verwendet werden, z. B. verschiedene ConstValue-Werte, desto fragmentierter wird die Aufnahme, was zu Leistungsbeeinträchtigungen führen kann.
In der folgenden Tabelle werden die unterstützten Eigenschaften aufgelistet und beschrieben und Beispiele bereitgestellt:
| Eigentum | Beschreibung | Beispiel |
|---|---|---|
ingestionMapping |
Ein Zeichenfolgenwert, der angibt, wie Daten aus der Quelldatei den tatsächlichen Spalten in der Tabelle zugeordnet werden. Definieren Sie den format Wert mit dem relevanten Zuordnungstyp. Siehe Datenzuordnungen. |
with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]")(veraltet: avroMapping, csvMapping, jsonMapping) |
ingestionMappingReference |
Ein Zeichenfolgenwert, der angibt, wie Daten aus der Quelldatei den tatsächlichen Spalten in der Tabelle mithilfe eines benannten Zuordnungsrichtlinienobjekts zugeordnet werden. Definieren Sie den format Wert mit dem relevanten Zuordnungstyp. Siehe Datenzuordnungen. |
with (format="csv", ingestionMappingReference = "Mapping1")(veraltet: avroMappingReference, csvMappingReference, jsonMappingReference) |
creationTime |
Der datetime-Wert (formatiert als ISO8601 Zeichenfolge), der zum Erstellungszeitpunkt der erfassten Datenausdehnungen verwendet werden soll. Wenn nicht angegeben, wird der aktuelle Wert (now()) verwendet. Das Überschreiben des Standardwerts ist beim Aufnehmen älterer Daten hilfreich, sodass die Aufbewahrungsrichtlinie ordnungsgemäß angewendet wird. Stellen Sie bei Angabe sicher, dass die Lookback-Eigenschaft in der effektiven Richtlinie für die Zusammenführungszusammenführung der Zieltabelle an den angegebenen Wert ausgerichtet ist. |
with (creationTime="2017-02-13") |
extend_schema |
Ein boolescher Wert, der den Befehl anweist, das Schema der Tabelle zu erweitern (Standardwert ist false). Diese Option gilt nur für befehle .append und .set-or-append. Die einzigen zulässigen Schemaerweiterungen verfügen über weitere Spalten, die der Tabelle am Ende hinzugefügt werden. |
Wenn das ursprüngliche Tabellenschema (a:string, b:int)ist, wäre eine gültige Schemaerweiterung (a:string, b:int, c:datetime, d:string), aber (a:string, c:datetime) wäre ungültig. |
folder |
Für Abfrage- Befehle, der der Tabelle zugewiesen werden soll. Wenn die Tabelle bereits vorhanden ist, setzt diese Eigenschaft den Ordner der Tabelle außer Kraft. | with (folder="Tables/Temporary") |
format |
Das Datenformat (siehe unterstützte Datenformate). | with (format="csv") |
ingestIfNotExists |
Ein Zeichenfolgenwert, der bei Angabe verhindert, dass die Aufnahme erfolgreich ausgeführt wird, wenn die Tabelle bereits Daten mit einem ingest-by: Tag mit demselben Wert markiert hat. Dadurch wird die Erfassung von idempotenten Daten sichergestellt. Weitere Informationen finden Sie unter Erfassung von: Tags. |
Die Eigenschaften with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') angeben, dass, wenn Daten mit dem Tag ingest-by:Part0001 bereits vorhanden sind, die aktuelle Aufnahme nicht abschließen. Wenn sie noch nicht vorhanden ist, sollte diese neue Aufnahme diesen Tagsatz haben (falls eine zukünftige Aufnahme versucht, die gleichen Daten erneut aufzunehmen.) |
ignoreFirstRecord |
Ein boolescher Wert, der, wenn er auf truefestgelegt ist, angibt, dass die Aufnahme den ersten Datensatz jeder Datei ignorieren soll. Diese Eigenschaft ist nützlich für Dateien in CSVund ähnlichen Formaten, wenn der erste Datensatz in der Datei die Spaltennamen sind. Standardmäßig wird false angenommen. |
with (ignoreFirstRecord=false) |
policy_ingestiontime |
Ein boolescher Wert, der, falls angegeben, beschreibt, ob die Ingestion Time Policy für eine Tabelle aktiviert werden soll, die mit diesem Befehl erstellt wird. Der Standardwert ist true. |
with (policy_ingestiontime=false) |
recreate_schema |
Ein boolescher Wert, der, falls angegeben, beschreibt, ob der Befehl das Schema der Tabelle neu erstellen kann. Diese Eigenschaft gilt nur für den Befehl .set-or-replace. Diese Eigenschaft hat Vorrang vor der extend_schema Eigenschaft, wenn beide festgelegt sind. |
with (recreate_schema=true) |
tags |
Eine Liste mit Tags, die den aufgenommenen Daten zugeordnet werden sollen, die als JSON-Zeichenfolge formatiert sind. | with (tags="['Tag1', 'Tag2']") |
TreatGzAsUncompressed |
Ein boolescher Wert, der bei Festlegung auf trueangibt, dass Dateien mit der Erweiterung .gz nicht komprimiert werden. Diese Kennzeichnung wird manchmal benötigt, wenn Sie von Amazon AWS S3 aufgenommen werden. |
with (treatGzAsUncompressed=true) |
validationPolicy |
Eine JSON-Zeichenfolge, die angibt, welche Überprüfungen während der Erfassung von Daten ausgeführt werden sollen, die im CSV-Format dargestellt werden. Eine Erläuterung der verschiedenen Optionen finden Sie unter Datenaufnahme. |
with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (dies ist die Standardrichtlinie) |
zipPattern |
Verwenden Sie diese Eigenschaft beim Aufnehmen von Daten aus dem Speicher mit einem ZIP-Archiv. Dies ist ein Zeichenfolgenwert, der den regulären Ausdruck angibt, der beim Auswählen der zu verwendenden Dateien im ZIP-Archiv verwendet werden soll. Alle anderen Dateien im Archiv werden ignoriert. | with (zipPattern="*.csv") |
Authentifizierung und Autorisierung
Jede Speicherverbindungszeichenfolge gibt die Autorisierungsmethode an, die für den Zugriff auf den Speicher verwendet werden soll. Je nach Autorisierungsmethode muss dem Prinzipal möglicherweise Berechtigungen für den externen Speicher erteilt werden, um die Aufnahme durchzuführen.
In der folgenden Tabelle sind die unterstützten Authentifizierungsmethoden und die Berechtigungen aufgeführt, die zum Aufnehmen von Daten aus externem Speicher erforderlich sind.
| Authentifizierungsmethode | Azure Blob Storage / Data Lake Storage Gen2 | Data Lake Storage Gen1 |
|---|---|---|
| Identitätswechsel | Speicher-Blob-Datenleser | Leser |
| Sas-Token (Shared Access) | Liste + Lesen | Diese Authentifizierungsmethode wird in Gen1 nicht unterstützt. |
| Microsoft Entra-Zugriffstoken | ||
| Zugriffsschlüssel für Speicherkonto | Diese Authentifizierungsmethode wird in Gen1 nicht unterstützt. | |
| verwaltete Identität | Speicher-Blob-Datenleser | Leser |
Ertrag
Das Ergebnis des Befehls ist eine Tabelle mit so vielen Datensätzen, wie datenshards ("Extents") vom Befehl generiert werden. Wenn keine Datensharders generiert wurden, wird ein einzelner Datensatz mit einer leeren (nullwertigen) Erweiterungs-ID zurückgegeben.
| Name | Art | Beschreibung |
|---|---|---|
| ExtentId | guid |
Der eindeutige Bezeichner für den datenshard, der vom Befehl generiert wurde. |
| ItemLoaded | string |
Mindestens eine Speicherdatei, die mit diesem Datensatz verknüpft sind. |
| Dauer | timespan |
Wie lange dauerte es, bis die Aufnahme durchgeführt wurde. |
| HasErrors | bool |
Gibt an, ob dieser Datensatz einen Aufnahmefehler darstellt. |
| OperationId | guid |
Eine eindeutige ID, die den Vorgang darstellt. Kann mit dem Befehl .show operation verwendet werden. |
Anmerkung
Mit diesem Befehl wird das Schema der Tabelle, in die aufgenommen wird, nicht geändert. Falls erforderlich, werden die Daten während der Aufnahme in dieses Schema "umgewandelt", nicht umgekehrt (zusätzliche Spalten werden ignoriert, und fehlende Spalten werden als NULL-Werte behandelt).
Beispiele
Azure Blob Storage mit freigegebener Zugriffssignatur
Im folgenden Beispiel wird Ihre Datenbank angewiesen, zwei Blobs aus Azure Blob Storage als CSV-Dateien zu lesen und deren Inhalt in Tabelle Taufzunehmen. Die ... stellt eine Freigegebene Azure Storage-Zugriffssignatur (SAS) dar, die Lesezugriff auf jedes Blob gewährt. Verschleierte Zeichenfolgen (die h vor den Zeichenfolgenwerten) werden verwendet, um sicherzustellen, dass die SAS nie aufgezeichnet wird.
.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 mit verwalteter Identität
Das folgende Beispiel zeigt, wie Sie eine CSV-Datei aus Azure Blob Storage lesen und deren Inhalt mithilfe der verwalteten Identitätsauthentifizierung in Tabelle T aufnehmen. Die Authentifizierung verwendet die verwaltete Identitäts-ID (Objekt-ID), die azure Blob Storage in Azure zugewiesen ist. Weitere Informationen finden Sie unter Erstellen einer verwalteten Identität für Speichercontainer.
.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
Das folgende Beispiel dient zum Aufnehmen von Daten aus Azure Data Lake Storage Gen 2 (ADLSv2). Die hier verwendeten Anmeldeinformationen (...) sind die Anmeldeinformationen des Speicherkontos (freigegebener Schlüssel), und wir verwenden die Zeichenfolgenverschleierung nur für den geheimen Teil der Verbindungszeichenfolge.
.ingest into table T (
'abfss://myfilesystem@contoso.dfs.core.windows.net/path/to/file1.csv;...'
)
Azure Data Lake Storage
Im folgenden Beispiel wird eine einzelne Datei aus Azure Data Lake Storage (ADLS) aufgenommen. Er verwendet die Anmeldeinformationen des Benutzers für den Zugriff auf ADLS (daher muss der Speicher-URI nicht als geheimer Schlüssel behandelt werden). Außerdem wird gezeigt, wie Sie Aufnahmeeigenschaften angeben.
.ingest into table T ('adl://contoso.azuredatalakestore.net/Path/To/File/file1.ext;impersonate')
with (format='csv')
Amazon S3 mit zugriffstaste
Im folgenden Beispiel wird eine einzelne Datei von Amazon S3 mithilfe einer Zugriffstasten-ID und eines geheimen Zugriffsschlüsselsaufgenommen.
.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 mit einer vorsignierten URL
Im folgenden Beispiel wird eine einzelne Datei von Amazon S3 mithilfe einer preSigned URLaufgenommen.
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
with (format='csv')