Verwenden von LightIngest zum Erfassen von Daten in Azure Data Explorer

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.

Voraussetzungen

• LightIngest. LightIngest auf eine von zwei Arten abrufen:

  • Laden Sie LightIngest-Binärdateien für Ihr Betriebssystem herunter. Stellen Sie sicher, dass Sie die Binärdateien nach dem Download entpacken.

  • Installieren Sie LightIngest als .NET-Tool. Für diese Methode ist erforderlich, dass sie auf Ihrem Computer .NET SDK Version 6.0 oder höher installiert haben. Führen Sie dann den folgenden Befehl aus:

    dotnet tool install -g Microsoft.Azure.Kusto.LightIngest
    

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 zum Azure Data Explorer-Cluster ein, der für die Verwaltung der Aufnahme zuständig ist. 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 Aufnahmeleistung benötigt LightIngest die Rohdatengröße, damit sie die nicht komprimierte Größe lokaler Dateien schätzen 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

Für Azure-Blobs spezifische Funktionen

Wenn Sie LightIngest mit Azure-Blobs verwenden, werden bestimmte Blobmetadateneigenschaften verwendet, um den Aufnahmeprozess zu verbessern.

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 das gleiche Aufnahmedatum. Verwenden Sie das -creationTimePattern Argument, um Ihre Daten zu partitionieren, indem Sie die Erstellungszeit anstelle der Erfassungszeit verwenden. Mit dem Argument -creationTimePattern wird die CreationTime-Eigenschaft aus dem Datei- oder Blobpfad extrahiert. Das Muster muss nicht den gesamten Elementpfad widerspiegeln, nur der Abschnitt, der den zu verwendenden Zeitstempel einschließt.

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)

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
  

Einlesen 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

• Einlesen aller Dateien unter dem Pfad PATH, die dem Muster *.json entsprechen.
• Festlegen des Ziels auf Datenbank DB, Tabelle TABLE, und Definieren der Ingestionszuordnung in der lokalen Datei MAPPING_FILE_PATH
• 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"

Dateien einlesen und Diagnosetracedateien schreiben

• Einlesen aller Dateien unter dem Pfad PATH, die dem Muster *.json entsprechen.
• Festlegen des Ziels auf Datenbank DB, Tabelle TABLE, und Definieren der Ingestionszuordnung in der lokalen Datei MAPPING_FILE_PATH
• Das Tool stellt die Daten für die Erfassung bereit und wartet nicht, bis die Erfassungsvorgänge abgeschlossen wurden
• Lokales Schreiben von Diagnoseablaufverfolgungsdateien unter Ordner 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"

Authentifizierung mit verwalteter Identität

LightIngest führt drei Aktionen aus, die verwaltete Identität für die 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 (Azure Storage-Verbindung zum Herunterladen von Blobs), muss die verwaltete Identität auch über Leseberechtigungen verfügen, und ein Token wird an den Kusto-Dienst übergeben, das für die Ingestion verwendet werden soll. Legen Sie alle drei Argumente fest.