Erfassung aus dem Speicher

  • Artikel

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 Erfassungsmethode ist für die Untersuchung und Prototyperstellung vorgesehen. Verwenden Sie es nicht in Produktions- oder Großvolumeszenarien.

Berechtigungen

Sie müssen mindestens über Table Ingestor-Berechtigungen verfügen, um diesen Befehl ausführen zu können.

Syntax

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

Erfahren Sie mehr über Syntaxkonventionen.

Parameter

Name Typ Erforderlich Beschreibung
async string Wenn angegeben, gibt der Befehl sofort zurück und setzt die Erfassung im Hintergrund fort. Die Ergebnisse des Befehls enthalten einen OperationId Wert, der dann mit dem .show operation Befehl verwendet werden kann, um den Erfassungsabschluss status und Ergebnisse abzurufen.
TableName string ✔️ Der Name der Tabelle, in der Daten erfasst 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 Trennzeichen getrennte Liste von 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 Erfassung aus einer Abfrage einer externen Tabelle erfolgen.

Hinweis

Es wird empfohlen, verschleierte Zeichenfolgenliterale für den SourceDataPointer zu verwenden. Der Dienst scrubt Anmeldeinformationen in internen Ablaufverfolgungen und Fehlermeldungen.

Erfassungseigenschaften

Wichtig

In der folgenden Tabelle sind die von Azure Data Explorer unterstützten Eigenschaften mit einer Beschreibung und Beispielen aufgeführt:

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. Ohne Angabe wird der aktuelle Wert (now()) verwendet. Das Überschreiben der Standardeinstellung ist bei der Erfassung älterer Daten hilfreich, um eine korrekte Anwendung der Aufbewahrungsrichtlinie zu gewährleisten. 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. Es sind nur Schemaerweiterungen zulässig, bei denen zusätzliche Spalten am Ende der Tabelle 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, überschreibt diese Eigenschaft den Ordner der Tabelle. 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']")
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}') (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. Abhängig von der Autorisierungsmethode müssen dem Prinzipal möglicherweise Berechtigungen für den externen Speicher erteilt werden, um die Erfassung durchzuführen.

In der folgenden Tabelle sind die unterstützten Authentifizierungsmethoden und die Berechtigungen aufgeführt, die zum Erfassen 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
SAS-Token (Shared Access) Liste + Lesen Diese Authentifizierungsmethode wird in Gen1 nicht unterstützt.
Microsoft Entra Zugriffstoken
Speicherkonto-Zugriffsschlüssel 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

Dieser Befehl ändert nicht das Schema der Tabelle, in die erfasst wird. 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 Shared Access Signature

Im folgenden Beispiel wird Ihr Cluster angewiesen, zwei Blobs aus Azure Blob Storage als CSV-Dateien zu lesen und deren Inhalt in der Tabelle Tzu erfassen. ... 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 Inhalt mithilfe der Authentifizierung für verwaltete Identitäten in die Tabelle T erfassen. Weitere Informationen zur Authentifizierungsmethode für verwaltete Identitäten finden Sie unter Übersicht über die Authentifizierung verwalteter Identitäten.

.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 Erfassen von Daten aus Azure Data Lake Storage Gen2 (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) erfasst. 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 einem Zugriffsschlüssel

Im folgenden Beispiel wird eine einzelne Datei aus Amazon S3 mithilfe einer Zugriffsschlüssel-ID und eines geheimen Zugriffsschlüssels erfasst.

.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 vorab signierten URL

Im folgenden Beispiel wird eine einzelne Datei aus Amazon S3 mithilfe einer vorab signierten URL erfasst.

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