Verwenden von LightIngest zum Erfassen von Daten in Azure Data Explorer

  • Artikel

LightIngest ist ein Befehlszeilenprogramm für die Ad-hoc-Datenerfassung in Azure Data Explorer. Das Hilfsprogramm kann Quelldaten aus einem lokalen Ordner, einem Azure Blob Storage-Container oder einem Amazon S3-Bucket pullen.

LightIngest ist besonders nützlich, wenn Sie eine große Menge von Daten erfassen möchten, da es keine Zeitlichen Einschränkungen für die Erfassungsdauer gibt. LightIngest ist außerdem nützlich, wenn Sie Datensätze später anhand des Erstellungszeitpunkts und nicht anhand des Erfassungszeitpunkts abfragen möchten.

Ein Beispiel zum automatischen Generieren eines LightIngest-Befehls finden Sie unter Erfassen von Verlaufsdaten.

Hinweis

Die Erfassung unterstützt eine maximale Dateigröße von 6 GB. Es wird empfohlen, Dateien zwischen 100 MB und 1 GB zu erfassen.

Voraussetzungen

Ausführen von LightIngest

So führen Sie LightIngest aus:

  1. Geben Sie an der Eingabeaufforderung LightIngest ein, gefolgt vom entsprechenden Befehlszeilenargument.

    Tipp

    Eine Liste der unterstützten Befehlszeilenargumente erhalten Sie durch Eingeben von LightIngest /help.

  2. Geben Sie ingest- gefolgt von der Verbindungszeichenfolge für den Azure Data Explorer-Cluster ein, in dem die Datenerfassung verwaltet wird. Setzen Sie die Verbindungszeichenfolge in doppelte Anführungszeichen, und befolgen Sie die Spezifikation für Kusto-Verbindungszeichenfolgen.

    Beispiel:

    LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -pattern:"*.csv.gz" -format:csv -limit:2 -ignoreFirst:true -cr:10.0 -dontWait:true

Empfehlungen zur Leistung

  • Verwenden Sie den Erfassungsendpunkt unter https://ingest-{yourClusterNameAndRegion}.kusto.windows.net, um die Erfassungslast am besten zu verwalten und nach vorübergehenden Fehlern wiederherzustellen.

  • Für eine optimale Erfassungsleistung ist die Rohdatengröße erforderlich, sodass in LightIngest die nicht komprimierte Größe der lokalen Dateien geschätzt werden kann. Allerdings kann die Größe der Rohdaten der komprimierten Blobs in LightIngest möglicherweise erst nach dem Herunterladen der Blobs korrekt geschätzt werden. Legen Sie daher bei der Erfassung von komprimierten Blobs die rawSizeBytes-Eigenschaft für die Blobmetadaten auf die nicht komprimierte Datengröße in Byte fest.

Befehlszeilenargumente

Argument Typ BESCHREIBUNG Erforderlich
string Ein Kusto-Verbindungszeichenfolge, der den Kusto-Endpunkt angibt, der die Erfassung verarbeitet. Dieser Wert sollte in doppelte Anführungszeichen eingeschlossen werden. ✔️
-database, -db string Der Azure Data Explorer-Zieldatenbankname.
-table string Der Azure-Zieltabellenname Data Explorer. ✔️
-sourcePath, -source string Der Speicherort der Quelldaten, der entweder ein lokaler Dateipfad, der Stamm-URI eines Azure-Blobcontainers oder der URI eines Amazon S3-Buckets sein kann. Wenn die Daten in Azure-Blobs gespeichert werden, muss der URI den Speicherkontoschlüssel oder die Shared Access Signature (SAS) enthalten. Wenn sich die Daten in einem S3-Bucket befindet, muss der URI den Anmeldeinformationsschlüssel enthalten. Es wird empfohlen, diesen Wert in doppelte Anführungszeichen einzuschließen. Weitere Informationen finden Sie unter Speicherverbindungszeichenfolgen. Pass -sourcePath:; Identitätswechsel zum Auflisten von Azure-Speicherelementen mit Benutzerberechtigungen (Benutzereingabeaufforderungsautorisierung). ✔️
-managedIdentity, -mi string Client-ID der verwalteten Identität (benutzerseitig oder systemseitig zugewiesen), die für die Verbindungsherstellung verwendet werden soll. Verwenden Sie "System" für systemseitig zugewiesene Identitäten.
-ingestWithManagedIdentity, -imgestmi string Client-ID der verwalteten Identität (benutzerseitig oder systemseitig zugewiesen), die für die Verbindungsherstellung verwendet werden soll. Verwenden Sie "System" für systemseitig zugewiesene Identitäten.
-connectToStorageWithUserAuth, -storageUserAuth string Authentifizieren Sie sich beim Datenquellenspeicherdienst mit Benutzeranmeldeinformationen. Die Optionen für diesen Wert sind PROMPT oder DEVICE_CODE.
-connectToStorageLoginUri, -storageLoginUri string Wenn -connectToStorageWithUserAuth festgelegt ist, können Sie optional einen Microsoft Entra ID Anmelde-URI angeben.
-prefix string Wenn sich die zu erfassenden Quelldaten in Blob Storage befinden, wird dieses URL-Präfix in allen Blobs gemeinsam genutzt, mit Ausnahme des Containernamens.
Wenn sich die Daten beispielsweise in MyContainer/Dir1/Dir2 befinden, sollte das Präfix Dir1/Dir2 lauten. Es wird empfohlen, diesen Wert in doppelte Anführungszeichen einzuschließen.
-pattern string Muster, nach dem Quelldateien oder Blobs ausgewählt werden. Unterstützt Platzhalter. Beispiel: "*.csv". Es wird empfohlen, diesen Wert in doppelte Anführungszeichen einzuschließen.
-zipPattern string Regulärer Ausdruck, der zum Auswählen der zu erfassenden Dateien in einem ZIP-Archiv verwendet werden soll. Alle anderen Dateien im Archiv werden ignoriert. Beispiel: "*.csv". Es wird empfohlen, diesen Wert in doppelte Anführungszeichen einzuschließen.
-format, -f string Format der Quelldaten. Muss in einem der unterstützten Formate vorliegen.
-ingestionMappingPath, -mappingPath string Ein Pfad zu einer lokalen Datei für die Erfassungsspaltenzuordnung. Weitere Informationen finden Sie unter Data mappings (Datenzuordnungen).
-ingestionMappingRef, -mappingRef string Der Name einer Erfassungsspaltenzuordnung, die zuvor für die Tabelle erstellt wurde. Weitere Informationen finden Sie unter Data mappings (Datenzuordnungen).
-creationTimePattern string Wenn das Argument festgelegt ist, wird es zum Extrahieren der CreationTime-Eigenschaft aus dem Datei- oder Blobpfad verwendet. Weitere Informationen finden Sie unter Erfassen von Daten mit CreationTime.
-ignoreFirstRow, -ignoreFirst bool Wenn festgelegt, wird der erste Datensatz jeder Datei/jedes Blobs ignoriert. Beispiel: Die Quelldaten verfügen über Header.
-tag string Tags, die den erfassten Daten zugeordnet werden. Mehrere Vorkommen sind zulässig.
-dontWait bool Wenn auf truefestgelegt ist, wartet nicht auf den Abschluss der Erfassung. Nützlich beim Erfassen großer Mengen von Dateien/Blobs.
-compression, -cr double Komprimierungsverhältnis. Nützlich, wenn komprimierte Dateien oder Blobs erfasst werden, damit in Azure Data Explorer die Größe der Rohdaten bewertet werden kann. Berechnet als Originalgröße dividiert durch komprimierte Größe.
-limit, -l integer Falls festgelegt, wird die Erfassung auf die ersten N-Dateien beschränkt.
-listOnly, -list bool Wenn festgelegt, werden nur die Elemente angezeigt, die für die Erfassung ausgewählt worden wären.
-ingestTimeout integer Zeitlimit in Minuten für den Abschluss aller Erfassungsvorgänge. Der Standardwert lautet 60.
-forceSync bool Wenn das Argument festgelegt ist, wird die synchrone Erfassung erzwungen. Wird standardmäßig auf false festgelegt.
-Interaktive bool Wenn auf falsefestgelegt ist, wird nicht zur Bestätigung von Argumenten aufgefordert. Für unbeaufsichtigte Flows und nicht interaktive Umgebungen. Der Standardwert ist true.
-dataBatchSize integer Legt die Gesamtgröße (MB, unkomprimiert) der einzelnen Erfassungsvorgänge fest.
-filesInBatch integer Legt den Grenzwert für die Anzahl von Dateien/Blobs für jeden Erfassungsvorgang fest.
-devTracing, -trace string Falls festgelegt, werden Diagnoseprotokolle in ein lokales Verzeichnis geschrieben (standardmäßig RollingLogs im aktuellen Verzeichnis oder können durch Festlegen des Switchwerts geändert werden).

Für Azure-Blobs spezifische Funktionen

Bei Verwendung mit Azure-Blobs verwendet LightIngest bestimmte Blobmetadateneigenschaften, um den Erfassungsprozess zu erweitern.

Metadateneigenschaft Verwendung
rawSizeBytes, kustoUncompressedSizeBytes Wenn die Eigenschaft festgelegt ist, wird die Größe der nicht komprimierten Daten interpretiert.
kustoCreationTime, kustoCreationTimeUtc Wird als UTC-Zeitstempel interpretiert. Wenn die Eigenschaft festgelegt ist, wird sie zum Überschreiben der Erstellungszeit in Kusto verwendet. Nützlich für Abgleichszenarien.

Anwendungsbeispiele

In den folgenden Beispielen wird davon ausgegangen, dass Sie LightIngest-Binärdateien für Ihr Betriebssystem installiert haben. Wenn Sie LightIngest als .NET-Tool installiert haben, ersetzen Sie LightIngest in den Beispielen durch LightIngest .

Erfassen von Verlaufsdaten mit der CreationTime-Eigenschaft

Wenn Sie Verlaufsdaten aus dem vorhandenen System in Azure Data Explorer laden, erhalten alle Datensätze das gleiche Erfassungsdatum. Sie können das Argument -creationTimePattern verwenden, um die Partitionierung Ihrer Daten basierend auf der Erstellungszeit und nicht der Erfassungszeit zu ermöglichen. Mit dem Argument -creationTimePattern wird die CreationTime-Eigenschaft aus dem Datei- oder Blobpfad extrahiert. Das Muster muss nicht den gesamten Elementpfad darstellen, sondern lediglich den Abschnitt, der den zu verwendenden Zeitstempel enthält.

Die Argumentwerte müssen Folgendes enthalten:

  • Konstanter Text direkt vor dem Zeitstempelformat, in einfache Anführungszeichen eingeschlossen (Präfix)
  • Zeitstempelformat in der standardmäßigen .NET-DateTime-Notation
  • Konstanter Text direkt nach dem Zeitstempel (Suffix)

Wichtig

Wenn Sie angeben, dass die Erstellungszeit überschrieben werden soll, achten Sie darauf, dass die Eigenschaft Lookback in der effektiven Richtlinie für die Zusammenführung von Blöcken der Zieltabelle auf die Werte in Ihren Datei- oder Blobpfaden abgestimmt ist.

Beispiele

  • Ein Blobname, der Datum und Uhrzeit im folgenden Format enthält: historicalvalues19840101.parquet. (Der Zeitstempel setzt sich aus vier Ziffern für das Jahr sowie jeweils zwei Ziffern für Monat und Tag zusammen.)

    Der Wert für das Argument -creationTimePattern ist Teil des Dateinamens: 'historicalvalues'yyyyMMdd'.parquet' .

    LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -creationTimePattern:"'historicalvalues'yyyyMMdd'.parquet'"
 -pattern:"*.parquet" -format:parquet -limit:2 -cr:10.0 -dontWait:true

  • Bei einem Blob-URI, der sich auf eine hierarchische Ordnerstruktur bezieht (etwa https://storageaccount/mycontainer/myfolder/2002/12/01/blobname.extension):

    Der Wert für das Argument -creationTimePattern ist Teil der Ordnerstruktur: 'folder/'yyyy/MM/dd'/blob' .

      LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -creationTimePattern:"'mycontainer/myfolder/'yyyy/MM/dd'/'"
   -pattern:"*.csv.gz" -format:csv -limit:2 -ignoreFirst:true -cr:10.0 -dontWait:true

Erfassen von Blobs mithilfe eines Speicherkontoschlüssels oder eines SAS-Tokens

  • Erfassen von 10 Blobs unter dem angegebenen Speicherkonto ACCOUNT im Ordner DIR unter dem Container CONT und in Übereinstimmung mit dem Muster *.csv.gz
  • Ziel ist die Datenbank DB, Tabelle TABLE, und die Erfassungszuordnung MAPPING, die im Ziel vorab erstellt wurde.
  • Das Tool wartet, bis die Erfassungsvorgänge abgeschlossen sind.
  • Beachten Sie die unterschiedlichen Optionen zum Angeben der Zieldatenbank und des Speicherkontoschlüssels im Vergleich zum SAS-Token
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}"
  -prefix:"DIR"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -limit:10

LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True;Initial Catalog=DB"
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER}?{SAS token}"
  -prefix:"DIR"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -limit:10

Erfassen aller Blobs in einem Container, ohne Headerzeilen

  • Erfassen aller Blobs unter dem angegebenen Speicherkonto ACCOUNT im Ordner DIR1/DIR2 unter dem Container CONT und in Übereinstimmung mit dem Muster *.csv.gz
  • Ziel ist die Datenbank DB, Tabelle TABLE, und die Erfassungszuordnung MAPPING, die im Ziel vorab erstellt wurde.
  • Die Quellblobs enthalten eine Headerzeile. Daher wird das Tool angewiesen, den ersten Datensatz jedes Blobs zu ignorieren.
  • Das Tool stellt die Daten für die Erfassung bereit und wartet nicht, bis die Erfassungsvorgänge abgeschlossen sind.
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER}?{SAS token}"
  -prefix:"DIR1/DIR2"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -ignoreFirstRow:true

Erfassen aller JSON-Dateien unter einem Pfad

  • Erfassen aller Dateien unter dem Pfad PATH in Übereinstimmung mit dem Muster *.json
  • Ziel ist die Datenbank DB, Tabelle TABLE, und die Erfassungszuordnung wird in der lokalen Datei MAPPING_FILE_PATH definiert.
  • Das Tool stellt die Daten für die Erfassung bereit und wartet nicht, bis die Erfassungsvorgänge abgeschlossen sind.
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"

Erfassen von Dateien und Schreiben von Diagnosedateien für die Ablaufverfolgung

  • Erfassen aller Dateien unter dem Pfad PATH in Übereinstimmung mit dem Muster *.json
  • Ziel ist die Datenbank DB, Tabelle TABLE, und die Erfassungszuordnung wird in der lokalen Datei MAPPING_FILE_PATH definiert.
  • Das Tool stellt die Daten für die Erfassung bereit und wartet nicht, bis die Erfassungsvorgänge abgeschlossen sind.
  • Diagnoseablaufverfolgungsdateien werden lokal unter dem Ordner geschrieben. LOGS_PATH
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"
  -trace:"LOGS_PATH"