Freigeben über

Erfassung aus dem Speicher

  • Artikel

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. Der Befehl kann beispielsweise 1.000 Blobs im CSV-Format aus Azure Blob Storage abrufen, analysieren und zusammen in einer einzelnen Zieltabelle erfassen. 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.

Berechtigungen

Sie müssen mindestens über Die Berechtigungen "Table Ingestor " verfügen, um diesen Befehl auszuführen.

Syntax

.ingest [async] into table TableName SourceDataLocator [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. Wurden keine Datenshards generiert, wird ein einzelner Datensatz mit einer leeren Block-ID (Wert: 0) zurückgegeben.

Name Typ 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 Erfassungsfehler 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. Beachten Sie auch die Verwendung von verschleierten Zeichenfolgen (h vor den Zeichenfolgenwerten), 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. Weitere Informationen zur Methode der verwalteten Identitätsauthentifizierung finden Sie unter "Übersicht über die Verwaltete Identitätsauthentifizierung".

.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')