Erfassung aus dem Speicher
Gilt für: ✅Microsoft Fabric✅Azure Data Explorer
Mit dem Befehl .ingest into werden Daten in einer Tabelle erfasst, indem die Daten aus Cloudspeicherdateien gepullt 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 ohne Auswirkungen auf vorhandene Datensätze und ohne Änderung des Tabellenschemas an die Tabelle angefügt.
Hinweis
Diese Aufnahmemethode ist für Die Erforschung und Prototyperstellung vorgesehen. Verwenden Sie sie nicht in Produktions- oder Volumenszenarien.
Hinweis
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.
Berechtigungen
Sie müssen mindestens über Die Berechtigungen "Table Ingestor " verfügen, um diesen Befehl auszuführen.
Syntax
.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]
Erfahren Sie mehr über Syntaxkonventionen.
Parameter
| Name | Type | 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 .show operation Befehl 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 durch Kommas getrennte Liste von Speicher Verbindungszeichenfolge s. Eine einzelne Verbindungszeichenfolge muss auf eine einzelne Datei verweisen, die von einem Speicherkonto gehostet wird. Die Erfassung mehrerer Dateien kann durch Angeben mehrerer Verbindungszeichenfolge oder durch Aufnahme aus einer Abfrage einer externen Tabelle erfolgen. |
Hinweis
Es wird empfohlen, verschleierte Zeichenfolgenliterale für die SourceDataLocators zu verwenden. Der Dienst bereinigt Anmeldeinformationen in internen Ablaufverfolgungen und Fehlermeldungen.
Erfassungseigenschaften
Wichtig
In der Warteschlange gespeicherte Erfassungsdaten werden mithilfe von Ingestion-Eigenschaften batched. 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:
| Eigenschaft | Beschreibung | Beispiel |
|---|---|---|
ingestionMapping |
Ein Zeichenfolgenwert, der angibt, wie Daten aus der Quelldatei den tatsächlichen Spalten in der Tabelle zugeordnet werden sollen. Definieren Sie den Wert format mit dem entsprechenden Zuordnungstyp. Weitere Informationen finden Sie unter Data mappings (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 zugeordnet werden sollen (unter Verwendung eines benannten Zuordnungsrichtlinienobjekts). Definieren Sie den Wert format mit dem entsprechenden Zuordnungstyp. Weitere Informationen finden Sie unter Data mappings (Datenzuordnungen). |
with (format="csv", ingestionMappingReference = "Mapping1")(veraltet: avroMappingReference, csvMappingReference, jsonMappingReference) |
creationTime |
Der datetime-Wert (formatiert als ISO8601-Zeichenfolge), der zum Zeitpunkt der Erstellung der erfassten Datenerweiterungen 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. Achten Sie bei Angabe eines Werts darauf, dass die Eigenschaft Lookback in der effektiven Richtlinie für die Zusammenführung von Blöcken der Zieltabelle auf den angegebenen Wert abgestimmt ist. |
with (creationTime="2017-02-13") |
extend_schema |
Ein boolescher Wert, der den Befehl anweist, das Schema der Tabelle zu erweitern (Standardwert: false). Diese Option betrifft nur die 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) lautet, wäre (a:string, b:int, c:datetime, d:string) eine gültige Schemaerweiterung, (a:string, c:datetime) dagegen nicht. |
folder |
Für ingest-from-query-Befehle der Ordner, 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 eine erfolgreiche Erfassung verhindert, wenn die Tabelle bereits Daten enthält, die mit einem Tag vom Typ ingest-by: mit identischem Wert gekennzeichnet sind. Dadurch wird die idempotente Datenerfassung sichergestellt. Weitere Informationen finden Sie unter ingest-by: Tags. |
Die Eigenschaften with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') geben an, dass die aktuelle Erfassung nicht ausgeführt werden soll, wenn bereits Daten mit dem Tag ingest-by:Part0001 vorhanden sind. Sind noch keine vorhanden, wird das Tag für diese neue Erfassung festgelegt (für den Fall, dass bei einer zukünftigen Erfassung versucht wird, die gleichen Daten zu erfassen). |
ignoreFirstRecord |
Ein boolescher Wert. Bei true wird bei der Erfassung jeweils der erste Datensatz der Datei ignoriert. Diese Eigenschaft ist hilfreich bei Dateien im CSV-Format und ähnlichen Formaten, wenn es sich beim ersten Datensatz in der Datei um die Spaltennamen handelt. Standardmäßig wird false verwendet. |
with (ignoreFirstRecord=false) |
policy_ingestiontime |
Ein boolescher Wert, der angibt, ob die IngestionTime-Richtlinie für eine Tabelle aktiviert werden soll, die durch diesen Befehl erstellt wird. Der Standardwert lautet true. |
with (policy_ingestiontime=false) |
recreate_schema |
Ein boolescher Wert, der angibt, ob der Befehl das Schema der Tabelle neu erstellen darf. Diese Eigenschaft gilt nur für den Befehl .set-or-replace. Sie hat Vorrang vor der extend_schema-Eigenschaft, wenn beide festgelegt sind. |
with (recreate_schema=true) |
tags |
Eine Liste der Tags, die den erfassten Daten zugeordnet werden sollen (formatiert als JSON-Zeichenfolge). | with (tags="['Tag1', 'Tag2']") |
TreatGzAsUncompressed |
Ein boolescher Wert, der, falls festgelegt true, angibt, 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 Beschreibung der verschiedenen Optionen finden Sie unter Datenerfassung. |
with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (dies ist die Standardrichtlinie) |
zipPattern |
Verwenden Sie diese Eigenschaft, wenn Sie Daten aus einem Speicher erfassen, der ein ZIP-Archiv enthält. Dieser Zeichenfolgenwert gibt den regulären Ausdruck an, der zum Auswählen der zu erfassenden Dateien im ZIP-Archiv verwendet werden soll. Alle anderen Dateien im Archiv werden ignoriert. | with (zipPattern="*.csv") |
Authentifizierung und Autorisierung
Jeder Speicher Verbindungszeichenfolge 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 | Leser von Speicherblobdaten | Leser |
| Token für gemeinsamen Zugriff (SAS) | Liste + Lesen | Diese Authentifizierungsmethode wird in Gen1 nicht unterstützt. |
| Microsoft Entra-Zugriffstoken | ||
| Zugriffsschlüssel für das Speicherkonto | Diese Authentifizierungsmethode wird in Gen1 nicht unterstützt. | |
| Verwaltete Identität | Leser von Speicherblobdaten | Leser |
Gibt zurück
Das Ergebnis des Befehls ist eine Tabelle mit so vielen Datensätzen, wie Datenshards („Blöcke“) vom Befehl generiert werden. Wenn keine Datensharders generiert wurden, wird ein einzelner Datensatz mit einer leeren (nullwertigen) Erweiterungs-ID zurückgegeben.
| Name | Type | Beschreibung |
|---|---|---|
| ExtentId | guid |
Der eindeutige Bezeichner für den vom Befehl generierten Datenshard |
| ItemLoaded | string |
Mindestens eine Speicherdatei, die mit diesem Datensatz verknüpft ist |
| Duration | timespan |
Zeit für die Ausführung der Erfassung |
| 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. |
Hinweis
Mit diesem Befehl wird das Schema der Tabelle, in die aufgenommen wird, nicht geändert. Bei Bedarf werden die Daten während der Erfassung 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 eine Tabelle Taufzunehmen.
... stellt eine Azure Storage Shared Access Signature (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 Inhalte mithilfe der verwalteten Identitätsauthentifizierung in eine 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 Gen2
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 (gemeinsam verwendeter Schlüssel), und die Zeichenfolgenverschleierung wird nur für den geheimen Teil der Verbindungszeichenfolge verwendet.
.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. Dabei werden die Anmeldeinformationen des Benutzers für den Zugriff auf ADLS genutzt (sodass der Speicher-URI nicht so behandelt werden muss, als enthielte er ein Geheimnis). Außerdem wird gezeigt, wie Erfassungseigenschaften angegeben werden.
.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üssels aufgenommen.
.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-URL aufgenommen.
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
with (format='csv')