Freigeben über

Verwenden von LightIngest zum Erfassen von Daten in Azure Data Explorer

  • Artikel

LightIngest ist ein Befehlszeilen-Hilfsprogramm 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 abrufen.

LightIngest ist besonders bei der Erfassung großer Datenmengen hilfreich, da die Erfassung zeitlich nicht beschränkt ist. 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 Historische Daten erfassen.

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.

    Zum 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

  • Um die Erfassungslast optimal zu verwalten und vorübergehende Fehler zu beheben, verwenden Sie den Erfassungsendpunkt unter https://ingest-{yourClusterNameAndRegion}.kusto.windows.net.

  • 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 Type Beschreibung Erforderlich
string Eine Kusto-Verbindungszeichenfolge, die den Kusto-Endpunkt angibt, an dem die Aufnahme verarbeitet wird. Dieser Wert sollte in doppelte Anführungszeichen eingeschlossen werden. ✔️
-database, -db string Der Name der Azure Data Explorer-Zieldatenbank.
-table string Der Name der Azure Data Explorer-Zieltabelle. ✔️
-sourcePath, -source string Der Speicherort der Quelldaten, bei denen es sich entweder um einen lokalen Dateipfad, den Stamm-URI eines Azure-Blobcontainers oder den URI eines Amazon S3-Buckets handeln kann. Wenn die Daten in Azure-Blobs gespeichert sind, muss der URI den Speicherkontoschlüssel oder die Shared Access Signature (SAS) enthalten. Wenn sich die Daten in einem S3-Bucket befinden, muss der URI den Anmeldeinformationsschlüssel enthalten. Es wird empfohlen, diesen Wert in doppelte Anführungszeichen einzuschließen. Weitere Informationen finden Sie unter Verbindungszeichenfolgen für den Speicher. Übergeben Sie -sourcePath:;impersonate, um Azure-Speicherobjekte mit benutzenden Personen aufzulisten (Autorisierung der Benutzeraufforderungen). ✔️
-managedIdentity, -mi string Client-ID der verwalteten Identität (benutzer- oder systemseitig zugewiesene Identität), die für die Verbindung verwendet werden soll. Verwenden Sie „system“ für die vom System zugewiesene Identität.
-azCli bool Wenn festgelegt, verwendet die Azure CLI, um sich beim Kusto-Dienst zu authentifizieren. Die Azure CLI muss installiert und angemeldet sein.
-ingestWithManagedIdentity, -ingestmi string Client-ID der verwalteten Identität (benutzer- oder systemseitig zugewiesene Identität), die auf dem Kusto-Dienst installiert ist und aus dem Speicher heruntergeladen werden soll. Verwenden Sie „system“ für die vom System zugewiesene Identität.
-connectToStorageWithManagedIdentity, -storageMi string Client-ID der verwalteten Identität (benutzer- oder systemseitig zugewiesene Identität), die auf dem Client installiert ist und aus dem Speicher aufgelistet werden soll.
-connectToStorageWithUserAuth, -storageUserAuth string Authentifizieren Sie sich mit den Anmeldeinformationen der benutzenden Person bei dem Dienst, der die Datenquelle speichert. Die Optionen für diesen Wert sind PROMPT oder DEVICE_CODE.
-connectToStorageLoginUri, -storageLoginUri string Wenn -connectToStorageWithUserAuth festgelegt ist, können Sie optional einen Anmelde-URI der Microsoft Entra ID 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 Der Pfad zur 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. Siehe Erfassen von Daten mithilfe von CreationTime.
-ignoreFirstRow, -ignoreFirst bool Bei Festlegung wird der erste Datensatz der einzelnen Dateien/Blobs ignoriert. Beispiel: Wenn die Quelldaten Kopfzeilen enthalten.
-tag string Tags, die den erfassten Daten zugeordnet werden. Mehrere Vorkommen sind zulässig.
-dontWait bool Wenn das Argument auf true festgelegt ist, wird nicht auf den Abschluss der Erfassung gewartet. Nützlich, wenn große Mengen an Dateien oder Blobs erfasst werden.
-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. Wird als ursprüngliche Größe geteilt durch die komprimierte Größe berechnet.
-limit, -l integer Wenn das Argument festgelegt ist, wird die Erfassung auf die ersten N Dateien beschränkt.
-listOnly, -list bool Wenn das Argument festgelegt ist, 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. Wird standardmäßig auf 60 festgelegt.
-forceSync bool Wenn das Argument festgelegt ist, wird die synchrone Erfassung erzwungen. Wird standardmäßig auf false festgelegt.
-interactive bool Wenn dieser Parameter auf falsefestgelegt ist, werden keine Argumente bestätigt. Für unbeaufsichtigte Flüsse und nicht interaktive Umgebungen. Der Standardwert ist true.
-dataBatchSize integer Legt die Beschränkung der Gesamtgröße (MB, nicht komprimiert) für jeden Erfassungsvorgang fest.
-filesInBatch integer Legt die maximal zulässige Anzahl der Dateien oder Blobs für jeden Erfassungsvorgang fest.
-devTracing, -trace string Wenn das Argument festgelegt ist, werden Diagnoseprotokolle in ein lokales Verzeichnis geschrieben (standardmäßig RollingLogs im aktuellen Verzeichnis, kann durch Festlegen des Schalterwerts geändert werden).

Für Azure-Blobs spezifische Funktionen

Bei Verwendung mit Azure-Blobs werden in LightIngest bestimmte Blob-Metadateneigenschaften verwendet, um den Erfassungsprozess zu erweitern.

Metadateneigenschaft Verbrauch
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 durch LightIngest in den Beispielen.

Erfassen von historischen Daten mit der CreationTime-Eigenschaft

Wenn Sie Verlaufsdaten aus einem vorhandenen System in Azure Data Explorer laden, erhalten alle Datensätze dasselbe 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 wurden
  • 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 wurden
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 wurden
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 wurden
  • Diagnosedateien für die Ablaufverfolgung werden lokal in den Ordner LOGS_PATH geschrieben
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"

Authentifizierung mit verwalteter Identität

LightIngest führt drei Aktionen durch, die verwaltete Identitäten zur Authentifizierung verwenden können. Die Verwendung der verwalteten Identität in jedem Schritt erfordert keine Verwendung der verwalteten Identität in anderen Schritten. Für jede Aktion wird das zugehörige Befehlszeilenargument angegeben.

  • Herstellen einer Verbindung mit dem Kusto-Cluster: Um die Aufnahme in die Warteschlange zu stellen, verwendet das Tool eine Verbindungszeichenfolge. Verwenden Sie das Argument „-mi“, um eine verwaltete Identität anzugeben, die auf der Client-VM installiert ist, die Erfassungsberechtigungen in der Zieldatenbank hat.

  • Herstellen einer Verbindung mit Azure Storage her zum Herunterzuladen von Blobs: Verwenden Sie „-ingestmi“, um eine verwaltete Identität anzugeben, die auf dem Kusto-Dienst mit Leseberechtigungen für den Speichercontainer installiert ist.

  • Herstellen einer Verbindung mit Azure Storage zum Auflisten von Container-Blobs: Verwenden Sie das Argument „-storageMi“, um eine verwaltete Identität anzugeben, die auf dem virtuellen Clientcomputer mit Listenrechten für den Speichercontainer installiert ist. Wenn Sie diese Methode verwenden, jedoch nicht die vorherige (Herstellen einer Verbindung mit Azure Storage her zum Herunterzuladen von Blobs), muss die verwaltete Identität ebenfalls über Leserechte verfügen, und ein Token wird an den Kusto-Dienst übergeben, der für die Erfassung verwendet wird. Daher wird empfohlen, alle drei Argumente festzulegen.